自定义样式
聊天窗口样式
本节说明聊天窗口主题、头像、气泡、输入框和资源样式等 UI 配置。
iOS SDK 提供聊天界面部分样式自定义,通过 QYSDK 单例的 customUIConfig 方法获取 QYCustomUIConfig 自定义 UI 配置类,该类为单例模式。
注意:以下自定义样式优先级比后台样式低,如果后台样式开关开启了,优先展示后台样式配置的效果。
属性列表
提供如下属性:
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sessionBackground | UIImageView | nil-纯灰底 | 消息 tableview 的背景图片视图 |
| themeColor | UIColor | 七鱼蓝 | 聊天页面主题色 |
| rightItemStyleGrayOrWhite | BOOL | YES-灰色 | 导航栏右侧按钮风格 |
| showCloseSessionEntry | BOOL | NO-隐藏 | 导航栏右侧退出会话按钮 |
| showHeadImage | BOOL | YES-显示 | 是否显示消息流头像 |
| showTopHeadImage | BOOL | NO-隐藏 | 是否显示导航栏客服头像 |
| customerHeadImage | UIImage | 默认头像 | 访客头像图片 |
| customerHeadImageUrl | NSString | nil | 访客头像URL |
| customerMessageBubbleNormalImage | UIImage | 默认气泡 | 访客消息气泡图片 |
| customerMessageBubblePressedImage | UIImage | 默认气泡 | 访客消息气泡图片-按下 |
| customMessageTextColor | UIColor | 白色 | 访客文本消息字体颜色 |
| customMessageHyperLinkColor | UIColor | 白色 | 访客文本消息链接字体颜色 |
| customMessageTextFontSize | CGFloat | 16 | 访客文本消息字体大小 |
| serviceHeadImageUrl | NSString | nil | 客服头像图片地址 |
| serviceHeadImage | UIImage | 默认头像 | 客服头像图片 |
| isWebFirst | BOOL | NO | 客服头像优先级 YES 管理端配置优先 NO 代码配置优先,默认NO |
| serviceMessageBubbleNormalImage | UIImage | 默认气泡 | 客服消息气泡图片 |
| serviceMessageBubblePressedImage | UIImage | 默认气泡 | 客服消息气泡图片-按下 |
| serviceMessageTextColor | UIColor | 深灰色 | 客服文本消息字体颜色 |
| serviceMessageHyperLinkColor | UIColor | 七鱼蓝 | 客服文本消息链接字体颜色 |
| serviceMessageTextFontSize | CGFloat | 16 | 客服文本消息字体大小 |
| tipMessageTextColor | UIColor | 白色 | 提示文本消息字体颜色 |
| tipMessageTextFontSize | CGFloat | 12 | 提示文本消息字体大小 |
| bypassDisplayMode | NSInteger | 底部(2) | 访客分流展示模式 |
| sessionMessageSpacing | CGFloat | 0 | 消息竖直方向间距 |
| headMessageSpacing | CGFloat | 4 | 头像与消息气泡间距 |
| messageButtonTextColor | UIColor | 白色 | 消息内强提示按钮文字颜色 |
| messageButtonBackColor | UIColor | 七鱼蓝 | 消息内强提示按钮底色 |
| actionButtonTextColor | UIColor | 灰色 | 输入框上方操作按钮文字颜色 |
| actionButtonBorderColor | UIColor | 灰色 | 输入框上方操作按钮边框颜色 |
| inputTextColor | UIColor | 深灰色 | 输入框字体颜色 |
| inputTextFontSize | CGFloat | 14 | 输入框字体大小 |
| inputTextPlaceholder | NSString | 默认文案 | 输入框占位文案 |
| showAudioEntry | BOOL | YES-显示 | 输入栏语音按钮-人工 |
| showAudioEntryInRobotMode | BOOL | YES-显示 | 输入栏语音按钮-机器人 |
| showEmoticonEntry | BOOL | YES-显示 | 输入栏表情按钮 |
| showImageEntry | BOOL | YES-显示 | 输入栏相机按钮 |
| robotImageStyle | NSInteger | 0-展示相机图标 | 输入栏机器人阶段相机按钮展示样式 注意:此配置依赖showRobotImageEntry为YES时生效 |
| imagePickerColor | UIColor | 七鱼蓝 | 照片/视频选择页面主题颜色 |
| autoShowKeyboard | BOOL | YES-弹出 | 自动弹出键盘 |
| bottomMargin | CGFloat | 0 | 聊天页面距离界面底部间距 |
| showShopEntrance | BOOL | NO-隐藏 | 导航栏右侧商铺入口按钮 |
| showSessionListEntrance | BOOL | NO-隐藏 | 会话列表入口按钮 |
| sessionListEntranceImage | UIImage | nil | 会话列表入口图片 |
| sessionListEntrancePosition | BOOL | YES-右上角 | 会话列表入口位置,YES代表在右上角,NO代表在左上角,默认在右上角 |
| sessionTipTextColor | UIColor | 橘色 | 会话窗口上方提示条字体颜色 |
| sessionTipTextFontSize | CGFloat | 14 | 会话窗口上方提示条字体大小 |
| sessionTipBackgroundColor | UIColor | 黄色 | 会话窗口上方提示条背景颜色 |
| customInputItems | NSArray | nil-无 | 输入栏更多按钮展开项 |
| allowAutoRotate | BOOL | YES-可以旋转 | 是否允许旋转 |
| suffixType | 枚举 | QYAttachmentSuffixTypeJPG表示后缀是jpg,QYAttachmentSuffixTypePNG表示后缀是png | 工单附件后缀 |
| lineHeightMultiple | CGFloat | 1.0 | 富文本行高倍数 |
| textLineSpacing | CGFloat | 0 | 普通文本消息行间距 |
| productOrderCardMessageWhiteBubbleEnabled | BOOL | NO-后台UI配置 | 当卡片消息包含商品或订单模板时,发出和收到都使用白色气泡 |
接口列表
提供如下接口:
| 接口 | 说明 |
|---|---|
| restoreToDefault | 恢复默认设置 |
| setMessagesLoadImages: duration: forState: | 消息下拉刷新loading图片设置,区分不同state状态 |
| registerCustomCommodityInfoModelClass:contentViewClass: | 注册自定义商品卡片消息的model及contentView,配置其UI显示 |
配置更多按钮
V4.4.0 版本后,聊天界面输入栏 相机 按钮可替换为 更多 按钮,点击按钮显示半屏页面,放置自定义按钮;按钮数组通过QYCustomUIConfig的customInputItems属性配置,数组元素为QYCustomInputItem对象,该类提供如下配置项:
| 属性 | 类型 | 必须 | 说明 |
|---|---|---|---|
| normalImage | UIImage | 否 | 按钮图片(64pt) |
| selectedImage | UIImage | 否 | 按钮图片-按下(64pt) |
| text | NSString | 否 | 按钮标题 |
| block | QYCustomInputItemBlock | 否 | 点击事件回调 |
为达到最佳效果,建议按钮图片宽高均为64pt。目前SDK对外开放了发送文本、图片、视频、商品、订单等能力,可自由选择使用。配置customInputItems样例代码:
/**
* 相册/拍摄功能可直接调用UIImagePickerController,也可自定义界面,选择照片后调用接口发送图片消息即可
*/
QYCustomInputItem *photoItem = [[QYCustomInputItem alloc] init];
photoItem.normalImage = [UIImage imageNamed:@"icon_photo_normal"];
photoItem.selectedImage = [UIImage imageNamed:@"icon_photo_pressed"];
photoItem.text = @"相册";
photoItem.block = ^{ };
QYCustomInputItem *cameraItem = [[QYCustomInputItem alloc] init];
cameraItem.normalImage = [UIImage imageNamed:@"icon_camera_normal"];
cameraItem.selectedImage = [UIImage imageNamed:@"icon_camera_pressed"];
cameraItem.text = @"拍摄";
cameraItem.block = ^{ };
[[QYSDK sharedSDK] customUIConfig].customInputItems = @[photoItem, cameraItem];配置消息加载动效
V5.0.0 版本后,SDK 支持自定义历史消息下拉加载动效,需提供不同状态下图片数组,目前下拉加载状态有三种:空闲/即将加载/加载中,可提供不同动效图片组来实现不同状态加载动效。
/**
* 消息下拉加载状态
*/
typedef NS_ENUM(NSInteger, QYMessagesLoadState) {
QYMessagesLoadStateIdle,
QYMessagesLoadStateWillLoad,
QYMessagesLoadStateLoading,
};使用样例:
[[[QYSDK sharedSDK] customUIConfig] setMessagesLoadImages:@[idleImg]
duration:0
forState:QYMessagesLoadStateIdle];
[[[QYSDK sharedSDK] customUIConfig] setMessagesLoadImages:@[willImg]
duration:0
forState:QYMessagesLoadStateWillLoad];
NSArray *loadingArray = @[loadingImg_1, loadingImg_2, loadingImg_3, loadingImg_4];
[[[QYSDK sharedSDK] customUIConfig] setMessagesLoadImages:loadingArray
duration:0.2
forState:QYMessagesLoadStateLoading];管理端样式设置
V5.2.0 版本后,新增后台样式设置功能,位于 管理端-应用-在线系统-设置-访客端-样式设置-APP端 ,可根据企业需要配置。如需使用该功能,应首先开启 后台样式设置 开关,注意此开关变更非实时生效,接口24小时请求一次。
在可配置的样式中,主题色、客服头像位置、输入框占位文案、语音/表情按钮显示 跟随总开关配置,24小时生效;其他的 导航栏右侧按钮、企业客服头像、输入框快捷入口、+扩展按钮 配置可跟随会话实时生效。
开启 后台样式设置 后,应注意后台设置优先级高于代码设置优先级;即开启后,代码层面的属性themeColor、customerHeadImage、customerMessageBubbleNormalImage、customerMessageBubblePressedImage、messageButtonBackColor、imagePickerColor、showHeadImage、showTopHeadImage、inputTextPlaceholder、showAudioEntry、showAudioEntryInRobotMode、showEmoticonEntry、actionButtonBorderColor均设置无效,导航栏右侧按钮、输入框快捷入口、+扩展按钮 全部以管理端配置为准。
界面区域自定义
本节说明输入栏、导航栏、顶部区域和其他界面区域的自定义方式。
导航栏可以自定义吗
部分自定义。聊天界面会占用导航栏navigationItem的标题文字属性title、标题视图属性titleView、右侧按钮属性rightBarButtonItems;navigationItem的其它部分,比如leftBarButtonItems等,可以根据需要做自定义。
聊天界面可以自定义吗
部分样式及事件自定义。 具体可参考QYCustomUIConfig等配置类,Demo 源码中也有相关样例代码。
客服页面导航栏支持哪些配置?
- 导航控制器是开发者自行提供的,七鱼不内置导航控制器。
- 导航栏分三块区域,分别是:左侧返回按钮、中间视图区、右侧功能区
左侧返回按钮
返回按钮是开发者自定义的内容,可以参考下面代码自行实现:
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:sessionViewController];
nav.modalPresentationStyle = UIModalPresentationFullScreen;
UIBarButtonItem *item = [[UIBarButtonItem alloc] initWithTitle:@"返回" style:UIBarButtonItemStylePlain target:self action:@selector(onBack:)];
sessionViewController.navigationItem.leftBarButtonItem = item;中间视图区
中间视图区会展示两个内容:头像和标题栏
头像
头像受两个方面影响:网页端的后台样式配置和代码,具体逻辑如下:
- 后台样式开关开启,导航栏样式开关开启,企业logo勾选;------展示企业logo
- 后台样式开关开启,导航栏样式开关开启,企业logo和企业名称都不勾选;------不展示企业logo,展示客服头像
- 后台样式开关开启,导航栏样式开关关闭;-----不展示logo和客服头像
- 后台样式开关关闭,走代码配置,配置项如下:
[QYCustomUIConfig sharedInstance].showTopHeadImage=YES;右侧功能区
后台样式开启的情况下,根据网页端的配置项来,没有开启时,根据QYCustomUIConfig类中的属性配置
输入栏快捷入口
七鱼客服聊天界面提供输入栏上方快捷入口设置,区分机器人与人工两种模式。机器人模式下,快捷入口需在企业机器人相关配置页面进行按钮及事件的配置,不同节点可配置不同快捷入口,配置成功后快捷入口自动显示在输入栏上方,且根据配置自动更新,无需代码配置。
人工模式下,快捷入口按钮有两种配置方案,一种通过 管理端-应用-在线系统-设置-访客端-样式设置-App端-输入框上方快捷入口 配置按钮,并设置相应事件,注意此功能在 V5.2.0 版本后提供;在后台样式设置关闭情况下,可通过代码配置人工快捷入口。
快捷入口按钮QYButtonInfo类提供了如下属性:
| 属性 | 类型 | 必须 | 说明 |
|---|---|---|---|
| buttonId | id | 是 | 快捷入口ID,id为任意类型入参 |
| title | NSString | 否 | 快捷入口标题 |
| userData | id | 否 | 透传数据,未限制类型 |
| actionType | NSUInteger, Readonly | — | 按钮响应事件传递信息,1-文本/2-链接或自定义行为 |
| index | NSUInteger, Readonly | — | 响应按钮位置 |
添加按钮的示例代码:
QYButtonInfo *button_1 = [[QYButtonInfo alloc] init];
button_1.buttonId = [NSNumber numberWithLongLong:1001];
button_1.title = @"按钮标题1";
QYButtonInfo *button_2 = [[QYButtonInfo alloc] init];
button_2.buttonId = [NSNumber numberWithLongLong:1002];
button_2.title = @"按钮标题2";
sessionViewController.buttonInfoArray = @[button_1, button_2];聊天窗口顶部区域自定义
V4.7.0 版本中,获取到 sessionViewController后,可自定义聊天界面顶部区域,支持外部注册入视图,可配置视图高度和边距;此视图悬停在聊天界面导航栏下方、消息列表上方,不随消息流滚动。注册接口为:
/** 注册聊天界面顶部悬停视图 * @param hoverView 顶部悬停视图 @param height 视图高度 @param insets 视图边距,默认UIEdgeInsetsZero;top表示视图与导航栏底部距离,bottom设置无效,left/right分别表示距离屏幕左右边距 */
- (void)registerTopHoverView:(UIView *)hoverView height:(CGFloat)height marginInsets:(UIEdgeInsets)insets;支持销毁此视图,支持设置是否有渐隐动画及动画时长,销毁接口如下:
/** 销毁聊天界面顶部悬停视图 */
- (void)destroyTopHoverViewWithAnmation:(BOOL)animated duration:(NSTimeInterval)duration;运行时与样式选项
本节说明影响界面表现或运行行为的补充配置项。
键盘出现异常
检查 App 中是否用到了会影响全局的键盘处理,如果是这种情况,需要对QYSessionViewController做屏蔽。典型的比如第三方键盘库IQKeyboardManager
如何强制竖屏
如果您的 App 是横屏的,但希望聊天界面竖屏,可以在sessionViewController所在的UINavigationController中实现以下方法:
- (void)viewDidLoad {
AppDelegate *delegate = [UIApplication sharedApplication].delegate;
delegate.allowPort = YES;
}
-(void)viewWillDisappear:(BOOL)animated {
AppDelegate *delegate = [UIApplication sharedApplication].delegate;
delegate.allowPort = NO;
}然后在appdelegate.h里面实现:
@property (nonatomic, assign) BOOL allowPort;在appdelegate.m文件中实现:
- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window {
return self.allowPort ? UIInterfaceOrientationMaskPortrait:UIInterfaceOrientationMaskLandscape;
}客服端后台样式配置后不生效?代码设置的后台样式配置不生效?
- 后台管理页面如果开启了后台样式开关,则以web页面配置项为准,但是SDK侧有24小时时效限制,尝试将APP卸载重装看看是否生效
- 如果想通过代码设置样式,则需要关闭后台样式开关,同时在代码中配置对应的参数。 注意:样式的配置优先级是 后台样式>代码设置
自定义功能
本节收纳自定义功能相关的基础说明和平台补充内容。
这篇文档有帮助吗?