七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

自定义样式

聊天窗口样式

本节说明聊天窗口主题、头像、气泡、输入框和资源样式等 UI 配置。

iOS SDK 提供聊天界面部分样式自定义,通过 QYSDK 单例的 customUIConfig 方法获取 QYCustomUIConfig 自定义 UI 配置类,该类为单例模式。

注意:以下自定义样式优先级比后台样式低,如果后台样式开关开启了,优先展示后台样式配置的效果。

属性列表

提供如下属性:

属性类型默认说明
sessionBackgroundUIImageViewnil-纯灰底消息 tableview 的背景图片视图
themeColorUIColor七鱼蓝聊天页面主题色
rightItemStyleGrayOrWhiteBOOLYES-灰色导航栏右侧按钮风格
showCloseSessionEntryBOOLNO-隐藏导航栏右侧退出会话按钮
showHeadImageBOOLYES-显示是否显示消息流头像
showTopHeadImageBOOLNO-隐藏是否显示导航栏客服头像
customerHeadImageUIImage默认头像访客头像图片
customerHeadImageUrlNSStringnil访客头像URL
customerMessageBubbleNormalImageUIImage默认气泡访客消息气泡图片
customerMessageBubblePressedImageUIImage默认气泡访客消息气泡图片-按下
customMessageTextColorUIColor白色访客文本消息字体颜色
customMessageHyperLinkColorUIColor白色访客文本消息链接字体颜色
customMessageTextFontSizeCGFloat16访客文本消息字体大小
serviceHeadImageUrlNSStringnil客服头像图片地址
serviceHeadImageUIImage默认头像客服头像图片
isWebFirstBOOLNO客服头像优先级 YES 管理端配置优先 NO 代码配置优先,默认NO
serviceMessageBubbleNormalImageUIImage默认气泡客服消息气泡图片
serviceMessageBubblePressedImageUIImage默认气泡客服消息气泡图片-按下
serviceMessageTextColorUIColor深灰色客服文本消息字体颜色
serviceMessageHyperLinkColorUIColor七鱼蓝客服文本消息链接字体颜色
serviceMessageTextFontSizeCGFloat16客服文本消息字体大小
tipMessageTextColorUIColor白色提示文本消息字体颜色
tipMessageTextFontSizeCGFloat12提示文本消息字体大小
bypassDisplayModeNSInteger底部(2)访客分流展示模式
sessionMessageSpacingCGFloat0消息竖直方向间距
headMessageSpacingCGFloat4头像与消息气泡间距
messageButtonTextColorUIColor白色消息内强提示按钮文字颜色
messageButtonBackColorUIColor七鱼蓝消息内强提示按钮底色
actionButtonTextColorUIColor灰色输入框上方操作按钮文字颜色
actionButtonBorderColorUIColor灰色输入框上方操作按钮边框颜色
inputTextColorUIColor深灰色输入框字体颜色
inputTextFontSizeCGFloat14输入框字体大小
inputTextPlaceholderNSString默认文案输入框占位文案
showAudioEntryBOOLYES-显示输入栏语音按钮-人工
showAudioEntryInRobotModeBOOLYES-显示输入栏语音按钮-机器人
showEmoticonEntryBOOLYES-显示输入栏表情按钮
showImageEntryBOOLYES-显示输入栏相机按钮
robotImageStyleNSInteger0-展示相机图标输入栏机器人阶段相机按钮展示样式
注意:此配置依赖showRobotImageEntry为YES时生效
imagePickerColorUIColor七鱼蓝照片/视频选择页面主题颜色
autoShowKeyboardBOOLYES-弹出自动弹出键盘
bottomMarginCGFloat0聊天页面距离界面底部间距
showShopEntranceBOOLNO-隐藏导航栏右侧商铺入口按钮
showSessionListEntranceBOOLNO-隐藏会话列表入口按钮
sessionListEntranceImageUIImagenil会话列表入口图片
sessionListEntrancePositionBOOLYES-右上角会话列表入口位置,YES代表在右上角,NO代表在左上角,默认在右上角
sessionTipTextColorUIColor橘色会话窗口上方提示条字体颜色
sessionTipTextFontSizeCGFloat14会话窗口上方提示条字体大小
sessionTipBackgroundColorUIColor黄色会话窗口上方提示条背景颜色
customInputItemsNSArraynil-无输入栏更多按钮展开项
allowAutoRotateBOOLYES-可以旋转是否允许旋转
suffixType枚举QYAttachmentSuffixTypeJPG表示后缀是jpg,QYAttachmentSuffixTypePNG表示后缀是png工单附件后缀
lineHeightMultipleCGFloat1.0富文本行高倍数
textLineSpacingCGFloat0普通文本消息行间距
productOrderCardMessageWhiteBubbleEnabledBOOLNO-后台UI配置当卡片消息包含商品或订单模板时,发出和收到都使用白色气泡

接口列表

提供如下接口:

接口说明
restoreToDefault恢复默认设置
setMessagesLoadImages: duration: forState:消息下拉刷新loading图片设置,区分不同state状态
registerCustomCommodityInfoModelClass:contentViewClass:注册自定义商品卡片消息的model及contentView,配置其UI显示

配置更多按钮

V4.4.0 版本后,聊天界面输入栏 相机 按钮可替换为 更多 按钮,点击按钮显示半屏页面,放置自定义按钮;按钮数组通过QYCustomUIConfig的customInputItems属性配置,数组元素为QYCustomInputItem对象,该类提供如下配置项:

属性类型必须说明
normalImageUIImage否按钮图片(64pt)
selectedImageUIImage否按钮图片-按下(64pt)
textNSString否按钮标题
blockQYCustomInputItemBlock否点击事件回调

为达到最佳效果,建议按钮图片宽高均为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;

中间视图区

中间视图区会展示两个内容:头像和标题栏

头像

头像受两个方面影响:网页端的后台样式配置和代码,具体逻辑如下:

  1. 后台样式开关开启,导航栏样式开关开启,企业logo勾选;------展示企业logo
  2. 后台样式开关开启,导航栏样式开关开启,企业logo和企业名称都不勾选;------不展示企业logo,展示客服头像
  3. 后台样式开关开启,导航栏样式开关关闭;-----不展示logo和客服头像
  4. 后台样式开关关闭,走代码配置,配置项如下:
[QYCustomUIConfig sharedInstance].showTopHeadImage=YES;

右侧功能区

后台样式开启的情况下,根据网页端的配置项来,没有开启时,根据QYCustomUIConfig类中的属性配置

输入栏快捷入口

七鱼客服聊天界面提供输入栏上方快捷入口设置,区分机器人与人工两种模式。机器人模式下,快捷入口需在企业机器人相关配置页面进行按钮及事件的配置,不同节点可配置不同快捷入口,配置成功后快捷入口自动显示在输入栏上方,且根据配置自动更新,无需代码配置。

人工模式下,快捷入口按钮有两种配置方案,一种通过 管理端-应用-在线系统-设置-访客端-样式设置-App端-输入框上方快捷入口 配置按钮,并设置相应事件,注意此功能在 V5.2.0 版本后提供;在后台样式设置关闭情况下,可通过代码配置人工快捷入口。

快捷入口按钮QYButtonInfo类提供了如下属性:

属性类型必须说明
buttonIdid是快捷入口ID,id为任意类型入参
titleNSString否快捷入口标题
userDataid否透传数据,未限制类型
actionTypeNSUInteger, Readonly—按钮响应事件传递信息,1-文本/2-链接或自定义行为
indexNSUInteger, 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卸载重装看看是否生效
  • 如果想通过代码设置样式,则需要关闭后台样式开关,同时在代码中配置对应的参数。 注意:样式的配置优先级是 后台样式>代码设置

自定义功能

本节收纳自定义功能相关的基础说明和平台补充内容。

这篇文档有帮助吗?

目录