开发指南

# 自定义样式

iOS SDK 提供聊天界面部分样式自定义，通过[QYSDK sharedSDK]单例的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 底部 访客分流展示模式
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-显示 输入栏相机按钮
imagePickerColor UIColor 七鱼蓝 照片/视频选择页面主题颜色
autoShowKeyboard BOOL YES-弹出 自动弹出键盘
bottomMargin CGFloat 0 聊天页面距离界面底部间距
showShopEntrance BOOL NO-隐藏 导航栏右侧商铺入口按钮
showSessionListEntrance BOOL NO-隐藏 会话列表入口按钮
sessionListEntranceImage UIImage nil 会话列表入口图片
sessionListEntrancePosition BOOL YES-右上角 会话列表入口位置
sessionTipTextColor UIColor 橘色 会话窗口上方提示条字体颜色
sessionTipTextFontSize CGFloat 14 会话窗口上方提示条字体大小
sessionTipBackgroundColor UIColor 黄色 会话窗口上方提示条背景颜色
customInputItems NSArray nil-无 输入栏更多按钮展开项

# 接口列表

提供如下接口：

接口 说明
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均设置无效，导航栏右侧按钮、输入框快捷入口、+扩展按钮 全部以管理端配置为准。

# 更换图片素材

七鱼 iOS SDK 支持所有图片素材的替换。开发者需要新建资源文件QYCustomResource.bundle，在其中放置与 QYResource.bundle同名的图片素材，即可实现替换。为保证最佳效果，应替换同等尺寸图片。

← 功能配置 →