进阶用法

大约 6 分钟

进阶用法

Chat UIKit SDK UI 组件库提供主题、国际化、常用 UI 组件等。除提供默认使用方式外，该组件库支持自定义组件样式和行为。

入口组件 Container

Container 组件提供全局配置和初始化。如果没有使用该组件，则可能导致其它 UI 组件无法正常使用。

Container 提供了自定义参数，如下所示：

属性	类型	是否必填	描述
options	ChatOptionsType	是	复合参数集合，和 `ChatOptions` 一致，必填参数只有 `appKey`。
language	LanguageCode	否	语言码。指定 UI 组件显示内容的语言。例如：中文、英文。
translateLanguage	LanguageCode	否	语言码。指定消息翻译的目标语言。例如：中文、英文。
palette	Palette	否	主题调色板。主题会从调色板中选择颜色和样式搭配组成主题。
theme	Theme	否	主题。默认提供明暗两种主题。
fontFamily	string	否	自定义 UI 组件字体的样式。
emojiFontFamily	string	否	自定义 emoji 表情字体的样式。
headerFontFamily	string	否	自定义导航栏字体的样式。
releaseArea	ReleaseArea	否	设置发布区域。例如：全球、中国。
formatTime	object	否	会话列表、聊天页面的时间格式化回调通知。如果没有提供则使用默认格式化。
recallTimeout	number	否	回调超时时间。单位为毫秒。默认 120 秒。
group	object	否	创建群组选择成员数的最大数目。默认 1000.
conversationDetail	ConversationDetailType	否	聊天页面的配置集合。详见对应定义。
avatar	object	否	全局头像样式设置。支持边框圆角设置。
input	object	否	全局输入组件样式设置。支持边框圆角设置。
alert	object	否	全局警告框组件样式设置。支持边框圆角设置。
onInitLanguageSet	function	否	注册语言包的回调通知。可以自定义语言包。
onInitialized	function	否	注册初始化完成的回调通知。
onUsersHandler	function	否	注册获取用户数据的回调通知。如果用户提供该接口，那么用户的头像和昵称通过该接口获取。如果没有提供则使用默认。
onGroupsHandler	function	否	注册获取群组数据的回调通知。如果用户提供该接口，那么群组的头像和昵称通过该接口获取。如果没有提供则使用默认。
onChangeStatus	function	否	注册 Presence 状态回调通知。如果用户提供该接口，将收到用户的状态变更通知。
enableTranslate	boolean	否	是否启用翻译功能。如果启用，还需要后台开启。
enableThread	boolean	否	是否启用话题功能。如果启用，还需要后台开启。
enableReaction	boolean	否	是否启用表情回复功能。如果启用，还需要后台开启。
enablePresence	boolean	否	是否启用状态订阅功能。如果启用，还需要后台开启。
enableAVMeeting	boolean	否	是否启用音视频通话功能。如果启用，还需要后台开启。默认开启。

Chat SDK 组件 ChatService

ChatService 组件是对 Chat SDK 的封装，可以简化调用逻辑、返回标准化的结果、触发 UI 变化的事件等。

常用接口包括：登录、登出、添加和删除事件监听、添加和删除 Chat SDK 事件监听等。

核心的常用方法定义如下：

方法	类型	描述
login	function	登录。
logout	function	登出。
autoLogin	function	自动登录。
loginState	function	当前登录状态。
userId	get	获取当前登录用户 ID。
updateDataList	function	主动更新指定数据的头像和昵称。将触发已加载的 UI 组件刷新。

ChatService 提供的方法非常多，详见对应定义open in new window。

监听器

ChatService 提供常用监听器 EventServiceListener 和 ConnectServiceListener。

ConnectServiceListener：接收 SDK 与服务器的连接状态变化的通知。

方法	描述
onConnected	已连接。
onDisconnected	断开连接。详见 `DisconnectReasonType`。

EventServiceListener：接收指定接口调用的事件变化的通知。

方法	描述
onBefore	接口调用前的通知。
onFinished	接口调用完成的通知。
onError	接口调用发生错误的通知。

自定义 hooks

以下介绍常见的 hooks。

useColors

通常配合 usePaletteContext 使用，自定义颜色对象，改变组件颜色。

例如：

export function SomeView() {
  const { colors } = usePaletteContext();
  const { getColor } = useColors({
    bg: {
      light: colors.neutral[98],
      dark: colors.neutral[1],
    },
  });
  return (
    <View
      style={{
        backgroundColor: getColor("bg"),
      }}
    />
  );
}

useDelayExecTask

延迟执行任务。如果在超时发生之前再次调用，则继续延迟，直到超时发生在执行任务。

例如：

export function SomeView() {
  const [value, setValue] = React.useState("");
  const { delayExecTask: deferSearch } = useDelayExecTask(
    500,
    React.useCallback((keyword: string) => {
      // 执行搜索
    }, [])
  );
  return (
    <Search
      onCancel={onCancel}
      onChangeText={(v) => {
        setValue(v);
        deferSearch?.(v);
      }}
      value={value}
    />
  );
}

useForceUpdate

useForceUpdate 提供强制更新。如果组件没有状态，或者需要手动更新，可以使用该 hook。

例如：

export function SomeView() {
  const count = React.useRef(0);
  const { updater } = useForceUpdate();
  return (
    <View style={{ paddingTop: 100, flexGrow: 1 }}>
      <Pressable
        onPress={() => {
          count.current += 1;
          updater();
        }}
      >
        <Text>{"test updater"}</Text>
      </Pressable>
      <Text>{`${count.current}`}</Text>
    </View>
  );
}

useGetStyleProps

useGetStyleProps 提供获取组件样式属性。通常和 getStyleSize 配合使用。

例如：

export function SomeView(props) {
  const { containerStyle } = props;
  const { getStyleSize } = useGetStyleProps();
  const { width: propsWidth } = getStyleSize(containerStyle);
  const { checkType } = useCheckType();
  if (propsWidth) {
    checkType(propsWidth, "number");
  }
  return <View style={{ width: propsWidth }} />;
}

useKeyboardHeight

useKeyboardHeight 获取用户的键盘高度。

提示

至少需要弹出一次键盘才能获取高度。

usePermissions

usePermissions 请求 UI 组件库需要的权限。

例如：

export function SomeView() {
  const { getPermission } = usePermissions();
  React.useEffect(() => {
    getPermission({
      onResult: (isSuccess: boolean) => {
        // 获取权限成功。
      },
    });
  }, [getPermission]);
  return <View />;
}

事件通知

目前 Chat UIKit SDK UI 组件库主要提供两种事件通知方式：

SDK 事件通知：Chat SDK 转发的事件，侧重于数据变化。

ConnectServiceListener：监听 SDK 和服务器的连接变化的通知。
MessageServiceListener：监听消息相关的通知。
ConversationListener：监听会话相关的通知。
GroupServiceListener：监听群组相关的通知。
ContactServiceListener：监听联系人相关的通知。
PresenceServiceListener：监听用户状态订阅的通知。
CustomServiceListener：监听自定义的通知。
MultiDeviceStateListener：监听多设备相关的通知。
EventServiceListener：监听事件通知，例如，添加好友之前的通知、添加好友成功的通知和添加好友失败的通知。

UI 事件通知：应用主动行为触发可能导致列表 item 增加、删除和变更、列表刷新和列表重载。例如，在群详情页面修改了群名称，会话列表组件的页面也会更新。很多情况下，单个界面行可能会导致多个 UI 组件发生的变化。详见 UIListener。

UIConversationListListener：监听会话列表的变更的通知。
UIContactListListener：监听联系人列表的变更的通知。
UIGroupListListener：监听群组列表的变更的通知。
UIGroupParticipantListListener：监听群成员列表的变更的通知。
UINewRequestListListener：监听好友请求列表的变更的通知。

进阶用法

# 进阶用法

# 入口组件 Container

# Chat SDK 组件 ChatService

# 监听器

# 自定义 hooks

# useColors

# useDelayExecTask

# useForceUpdate

# useGetStyleProps

# useKeyboardHeight

# usePermissions

# 事件通知

进阶用法

入口组件 Container

Chat SDK 组件 ChatService

监听器

自定义 hooks

useColors

useDelayExecTask

useForceUpdate

useGetStyleProps

useKeyboardHeight

usePermissions

事件通知