自定义样式

聊天窗口自定义

为了咨询客服窗口的界面风格能与集成七鱼 SDK 的 App 能够整体统一,七鱼 SDK 提供了简洁的 UI 自定义配置选项。

配置选项接口名为 UICustomization,配置参数放在 YSFOptionsuiCustomization 变量中,开发者可在初始化 SDK 或者在运行时任意时候修改配置,当需要与 SDK 提供的默认界面不一样表现的地方,就修改对应的项,否则不赋值即可,界面会保留默认表现。修改各设置项后,都需要等到下次进入会话界面才会看到相应的更改。

各配置项说明如下:(以下配置项可以参考demo中的uiCustomization类;现有的七鱼中可以自定义配置都已经在uiCustomization类中;若此类中没有提供的方法,就说明七鱼暂时还不支持自定义)

参数名 类型 参数说明 取值说明 是否受后台设置影响
msgBackgroundUri String 客服消息窗口背景图片设置 uri(支持格式见表后)
msgBackgroundColor int 客服消息窗口颜色。如果同时设置 uri 和颜色,优先使用 uri 32 位颜色值
msgListViewDividerHeight int 消息列表消息项间距 单位为 pixel
hideLeftAvatar boolean 是否隐藏左侧(客服消息)头像 默认为 false,不隐藏
hideRightAvatar boolean 是否隐藏右侧(访客消息)头像 默认为 false,不隐藏
avatarShape int 头像形状风格 0为圆形头像,1为方形头像
leftAvatar String 左侧 (客服消息)头像图片 uri uri(支持格式见表后)
rightAvatar String 右侧 (访客消息)头像图片 uri uri(支持格式见表后)
isShowTitleAvatar boolean 是否在标题栏上面展示头像,只对 Activity 接入方式生效 默认为 false,不展示
tipsTextColor int 提示类消息的字体颜色(包括分配客服消息,消息时间标签等) 32 位颜色值
tipsTextSize float 提示类消息的字体大小(包括分配客服消息,消息时间标签等) 单位为 sp
msgItemBackgroundLeft int 左边消息项背景, 最好是 selector,同时影响文本和语音消息。 drawable resId
msgItemBackgroundRight int 右边消息项背景, 最好是 selector,同时影响文本和语音消息。 drawable resId
msgRobotItemBackgroundLeft int 左边机器人消息项背景, 最好是 selector drawable resId
msgRobotItemBackgroundRight int 右边机器人消息项背景, 最好是 selector drawable resId
audioMsgAnimationLeft int 左侧语音消息播放时候的动画 animation-list,没有播放时显示最后一帧 drawable resId
audioMsgAnimationRight int 右侧语音消息播放时候的动画 animation-list,没有播放时显示最后一帧 drawable resId
textMsgColorLeft int 左侧文本消息颜色 32 位颜色值
hyperLinkColorLeft int 左侧文本消息中超链接的颜色 32 位颜色值
textMsgColorRight int 右侧文本消息颜色 32 位颜色值
hyperLinkColorRight int 右侧文本消息中超链接的颜色 32 位颜色值
textMsgSize float 文本消息字体大小 单位为sp
inputTextColor int 底部消息输入框的字体颜色 32 位颜色值
inputTextSize float 底部消息输入框的字体大小 单位为sp
topTipBarBackgroundColor int 顶部提示栏(没有客服,排队状态等)背景色 32 位颜色值
topTipBarTextColor int 顶部提示栏文字颜色 32 位颜色值
topTipBarTextSize float 顶部提示栏文字大小 单位为 sp
titleBackgroundResId int 标题栏背景图 drawable resId
titleBackgroundColor int 标题栏背景颜色,如果同时设置 drawable 和颜色,优先使用 drawable 32 位颜色值
titleBarStyle int 标题栏风格,影响标题和标题栏上按钮的颜色 目前支持: 0浅色系,1深色系
titleCenter boolean 标题居中 如果为 true ,居中,否则(默认)居左
buttonBackgroundColorList int 发送,选择,预览等按钮的颜色 ColorStateList,可参考 SDK 的 ysf_button_color_state_list
buttonTextColor int 发送,选择,预览等按钮的文字颜色 32 位颜色值
hideAudio boolean 是否隐藏语音输入栏 默认为 false,不隐藏
hideAudioWithRobot boolean 在机器人聊天界面是否隐藏输入栏 默认为false,不隐藏。给机器人发送语音后,会先转成文字消息,再发送给机器人
hideEmoji boolean 是否隐藏表情输入栏 默认为 false,不隐藏
screenOrientation int 屏幕旋转角度 0 为仅竖屏显示,1为仅横屏显示,2为根据重力感应切换
hideKeyboardOnEnterConsult boolean 在进入聊天界面时是否隐藏输入键盘 默认为 false,进入时就自动弹出键盘
robotBtnBack int 机器人会话中的按钮的背景 机器人按钮的背景图片 drawable
robotBtnTextColor int 机器人会话中的按钮的文字颜色 机器人按钮的文字颜色 32 位颜色值
inputUpBtnBack int 输入栏上方一触即达按钮的背景 输入栏上方一触即达按钮的背景 drawable
inputUpBtnTextColor int 输入栏上方一触即达按钮的文字颜色 输入栏上方 一触即达按钮的文字颜色 32 位颜色值
loadingAnimationDrawable int 聊天界面下拉加载更多 loading 动画的 drawable id(drawable 类型为 animation-list 帧动画) 默认为 0 ,也就是使用 SDK 默认的动画
editTextHint String 聊天界面的 editText 的 hint 默认为 请输入想要咨询的问题

图片 uri 支持的格式由开发者根据自己使用的图片加载框架定义。但必须要支持 file://, http:// 和 https:// 这3种。 如果开发者遇到下面两种情况,请首先检查图片加载器是否有正常初始化或是否支持当前图片路径: 1、设置的 leftAvatar 或者 rightAvatar 无效,展示的是 app 的 icon; 2、聊天框中不展示接收到的信息(没有展示聊天气泡);

后台样式读取相关

在 V5.2.0 版本中 SDK 增加了读取后台配置 UI 的功能,也就是说可以通过 web 端客服工作台配置 SDK 的样式,因为配置的样式和代码设置的样式有一些是重复的,所以当后台设置了样式的时候,代码设置的将会变为无效。具体哪些属性会受到影响请参考上面 UICustomization 配置项表格的第四列。

在后台 UI 配置功能中,主要增加的就是主题色的配置,具体主题色配置影响的 UI 有如下几处:

  1. 从本地选择视频、从本地选择图片中的发送按钮的颜色和选中图标的颜色
  2. 评价 dialog 中的确定按钮的颜色、已解决未解决按钮的边框颜色和选中的文字颜色、Tag list 的选中边框颜色和选中文字颜色、填写备注 dialog 完成按钮的颜色
  3. 评价消息在消息流中的按钮的背景颜色
  4. 默认头像颜色
  5. 机器人差评提交按钮的颜色
  6. 机器人问答的问题列表的文字颜色
  7. 机器人问答下方有用没用选中的文字颜色
  8. 选择客服分组的文字颜色
  9. 输入栏上方快捷入口的背景边框颜色
  10. 输入栏发送按钮的背景颜色
  11. bot 自助提供单中的"填写信息"按钮的文字颜色(auto_worksheet 模版)
  12. bot 商品列表中"查看更多"按钮的文字颜色(bubble_list 模版)
  13. bot 商品列表中发送商品二次确认的"确认按钮"的背景颜色
  14. bot 物流节点中"查看更多"按钮的文字颜色
  15. bot 中 action_list、static_union、order_status、radio_button 模版消息的背景颜色
  16. 右侧访客放松消息的背景颜色

其他界面自定义

SDK 的所有资源文件名均以 nim 或者 ysf 作为前缀,colors 和 strings 中的常量也以 nim 或 ysf 为前缀,以避免污染开发者的资源名字空间。

聊天界面的根 layout 文件为 ysf_message_fragment.xml,通过修改该文件,以及其引用的各子 layout 文件,可以修改聊天界面的框架布局。通过修改其中引用的素材资源,可以修改界面的上各图标,字体,背景等。

SDK 自带的会话界面为 ServiceMessageActivity, 其 theme 为 ysf_window_theme, 如果需要修改标题栏样式,可以修改该 style。 该 style 位于 ysf_styles.xml 中。

如果修改 SDK 中的资源文件,以后升级 SDK 时要注意重新替换,以免又回到默认界面上。

SDK 还提供了以 fragment 嵌入的方式集成会话界面,开发者可以更灵活的使用 SDK。示例代码如下:

String title = "聊天窗口的标题";
// 访客来源信息
ConsultSource source = new ConsultSource(sourceUrl, sourceTitle, "custom information string");
/**
 * 构造一个 ViewGroup,用于放置sdk的评价和人工客服按钮。
 * 该控件推荐放在标题栏右边。可以用以下两种方式:
 * 1. 将 container 放到 layout 文件中
 * LinearLayout sdkIconContainer = (LinearLayout)findViewById(R.id.xxx);
 * 2. 动态构建,动态添加
 * LinearLayout sdkIconContainer = new LinearLayout(this);
 * sdkIconContainer.setOrientation(LinearLayout.HORIZONTAL);
 * 构造好后,还需要将 ViewGroup 添加到你的 Activity 中
 */
ServiceMessageFragment fragment = Unicorn.newServiceFragment(title, source, sdkIconContainer);
FragmentManager fm = getSupportFragmentManager();
FragmentTransaction transaction = fm.beginTransaction();
// 将 fragment 放到对应的 containerId 中。containerId 为 ViewGroup 的 resId
transaction.replace(containerId, fragment);
try {
    transaction.commitAllowingStateLoss();
} catch (Exception e) {
}

输入栏区域自定义

为了使我们的 SDK 界面定制性更强,在 V4.3.0 版本我们提供了输入框的相关内容自定义。 配置选项的接口名为 InputPanelOptions ,配置参数放在 YSFOptionsInputPanelOptions 变量中,开发者可在初始化 SDK 或者在运行时任意时候修改配置,当需要与 SDK 提供的默认界面不一样表现的地方,就修改对应的项,否则不赋值即可,界面会保留默认表现。修改各设置项后,都需要等到下次进入会话界面才会看到相应的更改。

参数名 类型 参数说明 取值说明
voiceIconResId int 音频输入图标id drawable resId
emojiIconResId int 表情输入图标id drawable resId
photoIconResId int 拍照和相册图标id drawable resId 当开启输入更多的时候该图标不会生效
moreIconResId int 输入更多(类似于微信 + 号的功能)的图标id drawable resId
showActionPanel boolean 是否开启输入更多功能 true 拍照和相册功能被替换为输入更多,false 不开启,输入更多图标也不会生效
actionPanelOptions ActionPanelOptions 输入更多弹框里面选项的相关配置 参考表格后面说明

在 ActionPanelOptions 可以通过设置 backgroundColor 去自定义输入更多弹出框的背景颜色,也可以通过配置 ActionPanelOptions 中的 ActionListProvider 接口去返回弹出框出现的选项列表(如果开启了输入更多功能,但是没配置这个列表,那么列表中会自动加入拍照和相册功能)上面整体的配置示例代码如下:

YSFOptions options = new YSFOptions();
options.inputPanelOptions = new InputPanelOptions();
options.inputPanelOptions.showActionPanel = true;
options.inputPanelOptions.moreIconResId = R.drawable.ysf_ic_actionpanel_strat;
options.inputPanelOptions.voiceIconResId = R.drawable.ic_launcher;
options.inputPanelOptions.emojiIconResId = R.drawable.ic_launcher;
options.inputPanelOptions.actionPanelOptions = new ActionPanelOptions();
options.inputPanelOptions.actionPanelOptions.actionListProvider = new ActionListProvider() {
    //实现 getActionList 方法,返回输入更多弹框的列表,SDK 中默认提供了 AlbumAction(相册)、CameraAction(相机)等 Action
    @Override
    public List<BaseAction> getActionList() {
        List<BaseAction> list = new ArrayList<>();
        list.add(new ImageAction(R.drawable.ic_home,R.string.ysf_action_camera_and_album));
        list.add(new SendTextAction(R.drawable.ic_kaola,R.string.ysf_action_text));
        list.add(new SendProductAction(R.drawable.ic_launcher,R.string.ysf_action_product));
        list.add(new DemoAction(R.drawable.ic_kaola,R.string.ysf_action_test));
        list.add(new CameraAction(R.drawable.ic_kaola,R.string.ysf_action_camera));
        list.add(new AlbumAction(R.drawable.ic_kaola,R.string.ysf_action_Album));
        return list;
    }
};
options.inputPanelOptions.actionPanelOptions.backgroundColor = 0xFF0000FF; //自定义输入更多弹框背景颜色

从上面的代码中可以看出列表中的每一个 item 为一个 Action ,SDK 提供了 BaseAction ,您可以继承它去实现你自己的 Action,然后加入列表。BaseAction 中提供了很多可自定义的内容,例如图标和文字,点击事件,还定义了创建文本消息和图片消息的方法。你可以通过如下代码去发送一条文本消息:

public class SendTextAction extends BaseAction {
    /**
     * 构造函数
     *
     * @param iconResId 图标 res id
     * @param titleId   图标标题的string res id
     */
    public SendTextAction(int iconResId, int titleId) {
        super(iconResId, titleId);
    }

    @Override
    public void onClick() {
        //buildTestMessage 为创建消息的方法,sendMessage 为 SDK 提供的发送消息的方法
        MessageService.sendMessage(buildTextMessage("hello world"));
    }
}

在 onClick 里面不仅仅可以发送文本消息,BaseAction 中还提供了 buildImageMessage 方法创建图片消息并发送,也可以在该方法跳转 App 的界面,然后重写 BaseAction 中的 onActivityResult 方法去处理你选择的数据。

在 V5.2.0 版本中我们新增了关闭会话(CloseSessionAction)、评价(EvaluationAction)、选择视频(VideoAlbumAction)、拍摄视频(TakeVideoAction)的 Action,用户可以通过业务的需求使用相关 Action

右上角按钮自定义

在 V4.3.0 版本中我们加入了客服窗口右上角 title 的按钮自定义的功能,您可以通过配置在 title 的右侧加入一个按钮,按钮的图片字体颜色,点击事件都可以配置,该功能示例代码如下:

YSFOptions options = new YSFOptions();
options.titleBarConfig = new TitleBarConfig();
options.titleBarConfig.titleBarRightText = "进店";  //配置按钮下面的文字
options.titleBarConfig.titleBarRightImg = R.drawable.ic_menu_phone;  //配置按钮的图片 drawable resId
//设置按钮的点击事件
options.titleBarConfig.onTitleBarRightBtnClickListener = new OnTitleBarRightBtnClickListener() {
    @Override
    public void onClick(Activity activity) {
        ToastUtils.show("恭喜你,点击事件触发了");
    }
};