Merge pull request #1040 from haoxiuwen/doc-v2

Modify Flutter UIKit Docs
easemob · Nov 18, 2024 · 2ab0e04 · 2ab0e04
2 parents 689fd49 + d99c9e2
commit 2ab0e04
Show file tree

Hide file tree

Showing 11 changed files with 113 additions and 118 deletions.
diff --git a/docs/document/flutter/releasenote.md b/docs/document/flutter/releasenote.md
@@ -2,6 +2,10 @@
 
 <Toc />
 
+## 版本 V4.8.2 2024-11-18
+
+- 修复 ios `EMChatManager.searchMsgsByOptions` 和 `EMConversation.searchMsgsByOptions` 方法类型不准的问题。
+
 ## 版本 V4.8.1 2024-10-15
 
 #### 新增特性

diff --git a/docs/uikit/chatuikit/flutter/chatuikit_advancedusage.md b/docs/uikit/chatuikit/flutter/chatuikit_advancedusage.md
@@ -137,9 +137,9 @@ Widget build(BuildContext context) {
 
 ```dart
 ChatUIKitTimeFormatter.instance.formatterHandler = (context, type, time) {
-  if (type == ChatUIKitTimeType.conversation) { // 会话列表使用的时间，需要根据 time 返回时间，如 ’xx月xx日 xx:xx‘
+  if (type == ChatUIKitTimeType.conversation) { // 会话列表使用的时间，需要根据 time 返回完整时间内容，格式为 xx月xx日 HH:mm。
     return '...';
-  } else if (type == ChatUIKitTimeType.message) { // 消息使用的时间格式, 需要根据 time 返回时间，如 ’xx月xx日 xx:xx‘
+  } else if (type == ChatUIKitTimeType.message) { // 消息使用的时间格式, 需要根据 time 返回完整时间内容，格式为 xx月xx日 HH:mm。
     return '...';
   }
   return null; // 如果返回 null，则表示不做更改。
@@ -501,6 +501,6 @@ itemBuilder: (context, model) {
       );
     },
   );
-}
+},
 ```
 
diff --git a/docs/uikit/chatuikit/flutter/chatuikit_chat.md b/docs/uikit/chatuikit/flutter/chatuikit_chat.md
@@ -45,26 +45,26 @@ Widget build(BuildContext context) {
 | final ChatUIKitAppBarModel? appBarModel | 自定义消息页面 AppBar, 如不设置会使用默认的。|
 | final bool enableAppBar | 是否开启 AppBar，默认开启，关闭后将不再显示 AppBar，传入的 AppBar 也不再生效。|
 | final Widget? inputBar | 自定义输入组件。如不设置会使用默认的 `ChatUIKitInputBar`。|
-| final CustomTextEditingController? inputBarTextEditingController | `inputBar` 控制器。如果自定义了 `inputBar` 此处设置将不生效。|
-| final bool showMessageItemAvatar | 是否显示头像。|
-| final bool showMessageItemNickname | 是否显示昵称。|
-| final MessageItemTapHandler? onItemTap | 消息点击事件，默认会处理视频、图片、音频类型消息。自定义时如果需要拦截点击，返回 `true`, 如果不拦截，返回 `false`。|
-| final MessageItemTapHandler? onDoubleTap | 消息双击事件，默认没有实现。自定义时如果需要拦截点击，返回 `true`, 如果不拦截，返回 `false`。|
+| final MessageItemShowHandler showMessageItemAvatar | 是否显示头像。|
+| final MessageItemShowHandler showMessageItemNickname | 是否显示昵称。|
+| final MessageItemGlobalPositionTapHandler? onItemTap | 消息点击事件，默认会处理视频、图片、音频类型消息。自定义时如果需要拦截点击，返回 `true`, 如果不拦截，返回 `false`。|
+| final MessageItemGlobalPositionTapHandler? onDoubleTap | 消息双击事件，默认没有实现。自定义时如果需要拦截点击，返回 `true`, 如果不拦截，返回 `false`。|
 | final MessageItemTapHandler? onAvatarTap | 头像点击事件，默认会跳转到消息发送方的联系人详情页。如果发送方不是好友，则调到添加好友详情页，自定义时如果需要拦截点击，返回 `true`；如果不拦截，返回 `false`。|
 | final MessageItemTapHandler? onAvatarLongPress | 头像长按事件，默认没有实现。自定义时如果需要拦截点击，返回 `true`；如果不拦截，返回 `false`。|
 | final MessageItemTapHandler? onNicknameTap | 昵称长按事件，默认没有实现。自定义时如果需要拦截点击，返回 `true`, 如果不拦截，返回 `false`。|
 | final MessageItemBuilder? itemBuilder | 消息 item 自定义 builder。如果需要重写消息样式(包括头像，昵称，消息气泡, 消息引用等所有样式)，在此处实现。|
 | final MessageItemBuilder? alertItemBuilder | 提示消息 item 自定义 builder。如果需要重写提示消息样式，在此处实现。|
-| final List&lt;ChatUIKitBottomSheetAction&gt;? morePressActions | 默认 `inputBar` 中提供的 更多按钮菜单项。如不设置会使用默认菜单。自定义 `inputBar` 后不生效。|
+| final List&lt;ChatUIKitEventAction&gt;? morePressActions | 默认 `inputBar` 中提供的 更多按钮菜单项。如不设置会使用默认菜单。自定义 `inputBar` 后不生效。|
 | final MessagesViewMorePressHandler? onMoreActionsItemsHandler | 点击默认 `inputBar` 时回调，可以返回一个新的菜单列表。如返回 `null` 或不实现，则使用 `morePressActions` 中设置的内容。|
 | final MessagesViewItemLongPressHandler? onItemLongPressHandler | 消息长按菜单项时回调，可以返回一个新的菜单列表。如返回 `null` 或不实现，则使用 `longPressActions` 中设置的内容。|
 | final bool? forceLeft | 强制所有消息在左侧。|
 | final Widget? emojiWidget | 表情 widget，如果不设置则使用默认的。|
-| final MessageItemBuilder? replyBarBuilder | 自定义 `replyBar` 组件, 用于在消息引用时临时在输入框上方展示消息内容，如不设置会使用默认的 `ChatUIKitReplyBar`。|
+| final Widget? Function(BuildContext context, MessageModel replyMessage)? replyBarBuilder | 自定义 `replyBar` 组件, 用于在消息引用时临时在输入框上方展示消息内容，如不设置会使用默认的 `ChatUIKitReplyBar`。|
 | final Widget Function(BuildContext context, QuoteModel model)? quoteBuilder | 自定义消息引用在展示时的样式。如不设置则使用默认样式。|
 | final MessageItemTapHandler? onErrorBtnTapHandler | 错误消息点击事件，如果设置后将会替换默认的错误消息点击事件。如果不处理可以返回 `false`。默认行为为重新发送消息。|
 | final MessageItemBubbleBuilder? bubbleBuilder | 消息气泡。如果需要自定义消息气泡需要在此处实现，如果不设置则默认使用 `ChatUIKitMessageListViewBubble`。|
-| final MessageBubbleContentBuilder? bubbleContentBuilder | 消息气泡内容。如果需要自定义实现气泡内容需要在此处实现，如果不设置则使用默认。|
+| final MessageItemBuilder? bubbleContentBuilder | 消息气泡内容。如果需要自定义实现气泡内容需要在此处实现，如果不设置则使用默认。|
+| final ChatUIKitKeyboardPanelController? inputController | 输入框控制器，如果设置后将会替换默认的输入框控制器。详细参考 `ChatUIKitKeyboardPanelController`。 |
 | final String? attributes | 扩展参数，会传入到下一个页面。|
 | final Widget? multiSelectBottomBar | 多选时显示的 bottom bar。 |
 | final MessageReactionItemTapHandler? onReactionItemTap | 表情回复 Reaction 点击事件，如果设置后将会替换默认的反应点击事件。| 
@@ -176,4 +176,46 @@ ChatUIKitTimeFormatter.instance.formatterHandler = (ctx, type, time) {
 enum ChatUIKitTimeType { conversation, message, messagePinTime }
 ```
 
-- `time` 为时间戳。
+- `time` 为时间戳。
+
+
+### 自定义消息上下文菜单样式
+
+1. 设置类似微信样式
+
+若实现发送附件消息时弹出类似微信样式的弹窗，可进行如下设置：
+
+```dart
+ChatUIKitSettings.messageAttachmentMenuStyle = ChatUIKitMessageAttachmentMenuStyle.menu;
+```
+2. 设置仿系统 `BottomSheet` 样式：
+
+```dart
+ChatUIKitSettings.messageAttachmentMenuStyle = ChatUIKitMessageAttachmentMenuStyle.bottomSheet;
+```
+
+<ImageGallery>
+  <ImageItem src="/images/uikit/chatuikit/ios/configurationitem/chat/Appearance_chat_messageLongPressedActions.png" title="bottom-sheet" />
+  <ImageItem src="/images/uikit/chatuikit/ios/configurationitem/chat/[email protected]" title="context" />
+</ImageGallery>
+
+### 自定义消息长按后显示的操作
+
+1. 若实现消息长按后弹出类似微信样式的弹窗，可进行如下设置：
+
+```dart
+ChatUIKitSettings.messageLongPressMenuStyle = ChatUIKitMessageLongPressMenuStyle.popupMenu;
+```
+
+2. 设置仿系统 `BottomSheet` 样式：
+
+```dart
+ChatUIKitSettings.messageLongPressMenuStyle = ChatUIKitMessageLongPressMenuStyle.bottomSheet;
+```
+
+<ImageGallery>
+  <ImageItem src="/images/uikit/chatuikit/ios/configurationitem/chat/[email protected]" title="bottom-sheet" />
+  <ImageItem src="/images/uikit/chatuikit/ios/configurationitem/chat/[email protected]" title="context" />
+</ImageGallery>
+
+
diff --git a/docs/uikit/chatuikit/flutter/chatuikit_contactlist.md b/docs/uikit/chatuikit/flutter/chatuikit_contactlist.md
@@ -26,17 +26,16 @@ Widget build(BuildContext context) {
 | 参数 | 描述 |
 |---|---|
 | final ContactListViewController? controller | 联系人列表控制器。|
-| final ChatUIKitAppBar? appBar | 自定义消息页面 AppBar。如不设置会使用默认的。|
+| final ChatUIKitAppBarModel? appBarModel | 自定义消息页面 AppBar。如不设置会使用默认的。|
 | final bool enableAppBar | 是否开启 AppBar。默认开启，关闭后将不再显示 AppBar，传入的 AppBar 也不再生效。| 
-| final String? title | 默认 AppBar 展示的标题信息。如果使用自定义了 AppBar 或者 `enableAppBar = false`, 则不生效。|
-| final void Function(List&lt;ContactItemModel&gt; data)? onSearchTap | 联系人列表搜索点击事件回调。点击后会把当前所有的联系人回调出来，如果不设置会有默认实现。|
+| final void Function(List&lt;ContactItemModel&gt; data)? onSearchTap | 联系人列表搜索点击事件回调。点击后会把当前所有的恋人回调出来，如果不设置会有默认实现。|
 | final bool enableSearchBar | 是否显示联系人搜索框，默认为 `true`。|
-| final String? searchHideText | 搜索框中默认展示的文字内容。|
 | final List&lt;ChatUIKitListViewMoreItem&gt;? beforeItems | 展示在联系人列表前面的 widget，设置后将不再显示好友申请和群组列表的入口。|
 | final List&lt;ChatUIKitListViewMoreItem&gt;? afterItems | 展示在联系人列表后面的 widget。|
-| final ChatUIKitContactItemBuilder? listViewItemBuilder | 联系人列表 item builder。如果如要自定义显示需要在此处设置。|
+| final ChatUIKitContactItemBuilder? itemBuilder | 联系人列表 item builder。如果如要自定义显示需要在此处设置。|
 | final void Function(BuildContext context, ContactItemModel model)? onTap | 联系人列表 item 点击事件，如果不设置则默认进入联系人详情。|
 | final void Function(BuildContext context, ContactItemModel model)? onLongPress | 联系人列表 item 长按事件，无默认实现，如果需要添加长按事件需要在此处设置。|
+| final String? searchHideText | 搜索框中默认展示的文字内容。|
 | final Widget? listViewBackground | 联系人为空时展示的背景图。如果不设置会有默认实现。|
 | final String? loadErrorMessage | 联系人加载失败时现实的文字信息。如果设置会有默认实现。|
 | final String? attributes | 扩展参数，会传入到下一个页面。|

diff --git a/docs/uikit/chatuikit/flutter/chatuikit_integrated.md b/docs/uikit/chatuikit/flutter/chatuikit_integrated.md
@@ -6,8 +6,8 @@
 
 ## 前提条件
 
-- Flutter 3.3.0 或以上版本;
-- iOS 11 或以上版本;
+- Flutter 3.22.0 或以上版本;
+- iOS 12 或以上版本;
 - Android 21 或以上版本。
 
 ## 操作步骤
@@ -47,20 +47,6 @@ import 'package:em_chat_uikit/chat_uikit.dart';
 
 ### 第四步 初始化单群聊 UIKit
 
-项目中用到的组件都需要在 `ChatUIKitTheme` 内部使用。使用单群聊 UIKit 时，首先要配置 `ChatUIKitTheme`。
-
-```dart
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      ...
-      builder: (context, child) {
-        return ChatUIKitTheme(child: child!);
-      },
-    );
-  }
-```
-
 在 App 启动时初始化即时通讯 SDK。
 
 ```dart

diff --git a/docs/uikit/chatuikit/flutter/chatuikit_quickstart.md b/docs/uikit/chatuikit/flutter/chatuikit_quickstart.md
@@ -15,7 +15,7 @@
 ```yaml
 environment:
   sdk: '>=3.0.0 <4.0.0'
-  flutter: ">=3.3.0"
+  flutter: ">=3.19.0"
 ```
 
 2. 你需要添加权限：
@@ -57,30 +57,8 @@ flutter pub add em_chat_uikit
 flutter pub get
 ```
 
-### 第三步 添加主题
 
-打开新建的项目(此处使用的 IDE 是 `vscode`), 添加 `ChatUIKitTheme` 主题依赖。
-
-需要确保主题 `ChatUIKitTheme` 是 `ChatUIKit` 中所有组件的父组件，建议放在 `MyApp` 中，保证始终生效。
-
-```dart
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      ...
-      // 新添加的代码
-      builder: (context, child) {
-        return ChatUIKitTheme(child: child!);
-      },
-    );
-  }
-}
-```
-
-### 第四步 初始化
+### 第三步 初始化
 
 初始化 `ChatUIKit`，其中 `appkey` 需要替换为你自己的 App Key。
 
@@ -100,7 +78,7 @@ void main() {
 
 ```
 
-### 第五步 登录
+### 第四步 登录
 
 `ChatUIKit` 提供以下两种登录方法：用户 ID 和密码以及用户 ID 和 token。
 
@@ -124,7 +102,7 @@ ChatUIKit.instance.loginWithPassword(userId: userId, password: password);
 ChatUIKit.instance.loginWithToken(userId: userId, token: token);
 ```
 
-### 第六步 添加聊天页面
+### 第五步 添加聊天页面
 
 登录后显示聊天页面。
 
@@ -138,7 +116,7 @@ ChatUIKit.instance.loginWithToken(userId: userId, token: token);
   }
 ```
 
-### 第七步 发送第一条消息
+### 第六步 发送第一条消息
 
 在聊天页面下方输入消息，然后点击**发送**按钮发送消息。
 
@@ -176,12 +154,6 @@ class MyApp extends StatelessWidget {
         useMaterial3: true,
       ),
       home: const MyHomePage(title: 'Flutter Demo Home Page'),
-      builder: (context, child) {
-        return ChatUIKitTheme(
-          color: ChatUIKitColor.light(),
-          child: child!,
-        );
-      },
       onGenerateRoute: (settings) {
         return null;
       },

diff --git a/docs/uikit/chatuikit/flutter/chatuikit_run.md b/docs/uikit/chatuikit/flutter/chatuikit_run.md
@@ -13,7 +13,7 @@
 ```yaml
 environment:
   sdk: '>=3.0.0 <4.0.0'
-  flutter: ">=3.3.0"
+  flutter: ">=3.22.0"
 ```
 
 ## 操作步骤

diff --git a/docs/uikit/chatuikit/flutter/chatuikit_theme.md b/docs/uikit/chatuikit/flutter/chatuikit_theme.md
@@ -5,16 +5,19 @@
 单群聊 UIKit 内置浅色和深色主题，默认为浅色主题。
 
 ```dart
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      ...
-      builder: (context, child) {
-        // 设置单群聊 UIKit 主题
-        return ChatUIKitTheme(child: child!);
-      },
-    );
+  // 设置浅色主题
+  ChatUIKitTheme.instance.setColor(ChatUIKitColor.light());
+
+  // 设置深色主题
+  ChatUIKitTheme.instance.setColor(ChatUIKitColor.dark());
+
+  // 判断当前是使用深色还是浅色主题
+  if(ChatUIKitTheme.instance.color.isDark) {
+    // 深色主题
+  } else {
+    // 浅色主题
   }
+
 ```
 
 - 浅色主题
@@ -30,19 +33,11 @@
 若从当前的主题切换到单群聊 UIKit 内置的浅色或深色主题，可使用以下方法：
 
 ```dart
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      ...
-      builder: (context, child) {
-        return ChatUIKitTheme(
-          // 设置使用亮色主题，暗色为：ChatUIKitColor.dark()。
-          color: ChatUIKitColor.light(),
-          child: child!,
-        );
-      },
-    );
-  }
+  // 设置浅色主题
+  ChatUIKitTheme.instance.setColor(ChatUIKitColor.light());
+
+  // 设置深色主题
+  ChatUIKitTheme.instance.setColor(ChatUIKitColor.dark());
 ```
 
 ## 切换为自定义主题
@@ -62,31 +57,14 @@
 通过调整 HSLA 模型的色相值，你可以实现精确的色彩控制。
 
 ```dart
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      ...
-      builder: (context, child) {
-        return ChatUIKitTheme(
-            // 调整亮色模式下的色值，暗色为: 
-            //  ChatUIKitColor.dark(
-            //     primaryHue: 203,
-            //     secondaryHue: 155,
-            //     errorHue: 350,
-            //     neutralHue: 203,
-            //     neutralSpecialHue: 220,
-            //  ),
-          color: ChatUIKitColor.light(
-            primaryHue: 203,
-            secondaryHue: 155,
-            errorHue: 350,
-            neutralHue: 203,
-            neutralSpecialHue: 220,
-          ),
-          child: child!,
-        );
-      },
-    );
-  }
+ChatUIKitTheme.instance.setColor(
+  ChatUIKitColor.light(
+    primaryHue: 203,
+    secondaryHue: 155,
+    errorHue: 350,
+    neutralHue: 203,
+    neutralSpecialHue: 220,
+  ),
+);
 ```
 
diff --git a/docs/uikit/chatuikit/flutter/chatuikit_userinfo.md b/docs/uikit/chatuikit/flutter/chatuikit_userinfo.md
@@ -127,7 +127,7 @@ class ChatUIKitProfile {
 
 ```
 
-头像昵称信息在 `ChatUIKit` 中显示时，`ChatUIKitProvider` 会从你传入的数据中获取。如果没有获取到，`ChatUIKitProvider` 还会通过 `ChatUIKitProviderProfileHandler` 向你要数据。如果你将所需的 `ChatUIKitProfile` 返回，`ChatUIKitProvider` 会缓存你返回的 `ChatUIKitProfile`，从而减少向你请求的次数。如果你没有返回，`ChatUIKitProvider` 下次用到时还会继续向你要数据。
+头像昵称信息在 `ChatUIKit` 中显示时，`ChatUIKitProvider` 会从你传入的数据中获取。如果没有获取到，`ChatUIKitProvider` 还会通过 `ChatUIKitProviderProfileHandler` 向你要数据。如果你将所需的 `ChatUIKitProfile` 返回，`ChatUIKitProvider` 会缓存你返回的 `ChatUIKitProfile`，从而减少向你请求的次数。如果你没有返回，`ChatUIKitProvider` 下次用到时还会继续向要数据。
 
 ## 设置用户信息
 

diff --git a/docs/uikit/chatuikit/flutter/releasenote.md b/docs/uikit/chatuikit/flutter/releasenote.md
@@ -1,5 +1,19 @@
 # Flutter 单群聊 UIKit 更新日志
 
+## 版本 2.1.0
+
+### 新增特性
+
+- [消息长按菜单样式新增微信风格样式](chatuikit_custom_chat.html#自定义消息长按后显示的操作)；
+- [发送附件消息菜单新增微信风格样式](chatuikit_custom_chat.html#自定义消息上下文菜单样式)。
+
+### 优化
+
+- 修改 `ChatUIKitBottomSheetItem` 为 `ChatUIKitEventAction`；
+- 依赖 IM SDK 升级为 `im_flutter_sdk: 4.8.2`；
+- 依赖 Flutter 版本升级为 `3.19.0`；
+- 修改主题设置方式。
+
 ## 版本 2.0.3
 
 - 优化会话列表展示逻辑。

diff --git a/docs/uikit/chatuikit/ios/releasenote.md b/docs/uikit/chatuikit/ios/releasenote.md
@@ -8,8 +8,8 @@
 
 ### 新增特性
 
-- 消息长按菜单样式新增微信风格样式；
-- 发送附件消息菜单新增微信风格样式。
+- [消息长按菜单样式新增微信风格样式](chatuikit_custom_chat.html#设置消息长按后显示的操作)；
+- [发送附件消息菜单新增微信风格样式](chatuikit_custom_chat.html#设置附件消息)。
 
 ### 交互优化
-Original file line number
+Diff line change
@@ Expand Up / @@ -127,7 +127,7 @@ class ChatUIKitProfile { @@
     ```
-    头像昵称信息在 `ChatUIKit` 中显示时，`ChatUIKitProvider` 会从你传入的数据中获取。如果没有获取到，`ChatUIKitProvider` 还会通过 `ChatUIKitProviderProfileHandler` 向你要数据。如果你将所需的 `ChatUIKitProfile` 返回，`ChatUIKitProvider` 会缓存你返回的 `ChatUIKitProfile`，从而减少向你请求的次数。如果你没有返回，`ChatUIKitProvider` 下次用到时还会继续向你要数据。
+    头像昵称信息在 `ChatUIKit` 中显示时，`ChatUIKitProvider` 会从你传入的数据中获取。如果没有获取到，`ChatUIKitProvider` 还会通过 `ChatUIKitProviderProfileHandler` 向你要数据。如果你将所需的 `ChatUIKitProfile` 返回，`ChatUIKitProvider` 会缓存你返回的 `ChatUIKitProfile`，从而减少向你请求的次数。如果你没有返回，`ChatUIKitProvider` 下次用到时还会继续向要数据。
     ## 设置用户信息
@@ Expand Down @@