功能描述
本地消息搜索，提升 App 使用体验必备功能，可以帮助用户从纷繁复杂的信息中直接找到预期内容，快捷方便；也可作为运营工具，增加相关内容的引导，简洁高效。
消息搜索类介绍
消息搜索参数类
消息搜索参数类为 V2TimMessageSearchParam。搜索消息时，SDK 会按照该对象的设置，执行不同的搜索逻辑。
V2TIMMessageSearchParam 的参数说明如下：
| 参数 | 含义 | 说明 |
|---|---|---|
| keywordList | 关键字列表 | 最多支持 5 个。当消息发送者以及消息类型均未指定时，必须设置关键字列表；否则，关键字列表可以为空。 |
| keywordListMatchType | 指定关键字列表匹配类型 | 可设置为 “或” 关系搜索，或 “与” 关系搜索。取值分别为 V2TIM_KEYWORD_LIST_MATCH_TYPE_OR 和 V2TIM_KEYWORD_LIST_MATCH_TYPE_AND。默认为 “或” 关系搜索。 |
| senderUserIDList | 指定 userID 发送的消息 | 最多支持 5 个。 |
| messageTypeList | 指定搜索的消息类型集合 | 传空表示搜索支持的全部类型消息（V2TIMFaceElem 和 V2TIMGroupTipsElem 不支持搜索）。其他类型取值参考 V2TIMElemType。 |
| conversationID | 搜索 “全部会话” 还是搜索 “指定的会话” | conversationID 为空，搜索全部会话；conversationID 不为空，搜索指定会话。 |
| searchTimePosition | 搜索的起始时间点 | 默认为 0（从现在开始搜索）。UTC 时间戳，单位：秒。 |
| searchTimePeriod | 从起始时间点开始的过去时间范围 | 默认为 0（不限制时间范围）。24x60x60 代表过去一天。单位：秒。 |
| pageIndex | 分页的页号 | 用于分页展示查找结果，0 表示首页。 |
| pageSize | 每页结果数量 | 用于分页展示查找结果，如不希望分页可将其设置成 0。但如果结果数量太多，一次性拉取可能会引发性能问题。 |
消息搜索结果类
消息搜索结果类为 V2TIMMessageSearchResult。参数说明如下：
| 参数 | 含义 | 说明 |
|---|---|---|
| totalCount | 搜索结果总数 | 如果搜索指定会话，返回满足搜索条件的消息总数； 如果搜索全部会话，返回满足搜索条件的消息所在的所有会话总数量。 |
| messageSearchResultItems | 指定关键字列表匹配类型 | 如果搜索指定会话，返回结果列表只包含该会话结果； 如果搜索全部会话，会对满足搜索条件的消息根据会话 ID 分组，分页返回分组结果。 |
其中 messageSearchResultItems 是个列表，内含 V2TIMMessageSearchResultItem 对象，参数说明如下：
| 参数 | 含义 | 说明 |
|---|---|---|
| conversationID | 会话 ID | —— |
| messageCount | 消息数量 | 当前会话一共搜索到了多少条符合要求的消息。 |
| messageList | 满足搜索条件的消息列表 | 如果搜索指定会话，messageList 中装载的是本会话中所有满足搜索条件的消息列表。 如果搜索全部会话，messageList 中装载的消息条数会有如下两种可能： 如果某个会话中匹配到的消息条数 > 1，则 messageList 为空，您可以在 UI 上显示 “{messageCount} 条相关记录”。 如果某个会话中匹配到的消息条数 = 1，则 messageList 为匹配到的那条消息，您可以在 UI 上显示之，并高亮匹配关键词。 |
搜索全部会话的消息
当用户在搜索框输入关键字搜索消息时，您可以调用 searchLocalMessages 搜索 IM SDK 本地存储的消息。
如果您希望在全部会话范围内搜索，只需要将 V2TimMessageSearchParam 中的 conversationID 设置为空（null/nil) 或者不设置即可。
示例代码如下：
// 通过关键词搜索本地消息
V2TimValueCallback<V2TimMessageSearchResult> searchMessage = await messageManager.searchLocalMessages(searchParam: V2TimMessageSearchParam(keywordList: ['关键词1'],pageIndex: 0,pageSize: 10,type: 1));
搜索指定会话的消息
当用户在搜索框输入关键字搜索消息时，您可以调用 searchLocalMessages 搜索 IM SDK 本地存储的消息。
示例代码如下：
// 通过执行会话id和关键词搜索本地消息
V2TimValueCallback<V2TimMessageSearchResult> searchMessage = await messageManager.searchLocalMessages(searchParam: V2TimMessageSearchParam(keywordList: ['关键词1'],pageIndex: 0,pageSize: 10,type: 1,conversationID:'conversationID'));
搜索典型场景示例
普通的 IM 聊天软件，搜索界面的展示通常分这几种场景：
| 图 1：搜索聊天记录 | 图 2：搜索更多聊天记录 | 图 3：搜索指定会话的消息 |
|---|---|---|
 |
 |
 |
下文我们将依次向您展示如何利用 IM SDK 的搜索 API 实现上图的典型场景。
展示最近几个活跃的会话
如图 1 所示，最下方是搜索到的消息所属的最近 3 个会话列表，实现方式如下：
设置搜索参数
V2TIMMessageSearchParamconversationID设置为null，表示搜索所有会话的消息。pageIndex设置为 0，表示搜索到的消息所属的会话的首页数据。pageSize设置为 3，表示返回最近的会话数量，UI 上一般显示 3 条。
处理搜索回调结果
V2TIMMessageSearchResulttotalCount表示匹配到的消息所属的所有会话数量。messageSearchResultItems列表为最近 3（即入参pageSize) 个会话信息。其中元素V2TIMMessageSearchResultItem的messageCount表示当前会话搜索到的消息总数量；- 搜索到的消息条数 > 1，则
messageList为空，您可以在 UI 上显示 “4 条相关聊天记录”，其中的 4 为messageCount。 - 搜索到的消息条数 = 1，则
messageList为匹配到的那条消息，您可以在 UI 上显示消息内容并高亮搜索关键词，例如图中的 “test”。
示例代码如下：
// 通过指定messageTypeList上搜索指定类型消息
V2TimValueCallback<V2TimMessageSearchResult> searchMessage = await messageManager.searchLocalMessages(searchParam: V2TimMessageSearchParam(keywordList: ['关键词1'],pageIndex: 0,pageSize: 10,type: 1,conversationID: "",messageTypeList: [MessageElemType.V2TIM_ELEM_TYPE_TEXT]));
搜索自定义消息
通常情况下，如果您使用接口 createCustomMessage(data)创建自定义消息，该消息无法被搜到，因为 SDK 将该自定义消息保存为二进制数据流。
如果您希望自定义消息可以被搜到，需要使用接口 createCustomMessage(data, description, extension) 来创建并发送自定义消息，把需要搜索的文本放到 description 参数中。
如果您配置了离线推送功能，设置参数 description 后，自定义消息也会有离线推送且通知栏展示该参数内容。
如果不需要离线推送可以用发消息接口 sendMessage 的参数 V2TIMOfflinePushInfo 中的 disablePush 来控制。
如果推送的通知栏内容不想展示为被搜索的文本，可以用参数 V2TIMOfflinePushInfo 中的 desc 来另外设置推送内容。
搜索富媒体消息
富媒体消息包含文件、图片、语音、视频消息。
对于文件消息，界面通常显示文件名。如果调用 createFileMessage 创建文件消息时传入 fileName 参数，fileName 会作为文件消息被搜索的内容，与搜索关键词进行匹配。如果未设置 fileName，SDK 则会自动从 filePath 提取文件名作为搜索内容。
fileName 和 filePath 信息会保存到本地和服务器，换设备拉取相关信息后均可搜索。
对于图片、语音、视频消息，并没有类似 fileName 这种名称，界面通常显示缩略图或时长，此时指定 keywordList 搜索无效。
如果您希望搜索出此类消息，可以指定 messageTypeList 为 V2TIM_ELEM_TYPE_IMAGE/V2TIM_ELEM_TYPE_SOUND/V2TIM_ELEM_TYPE_VIDEO 做分类搜索，此时会搜索出所有指定类型的消息。
交流与反馈
欢迎加入 QQ 群进行技术交流和反馈问题，QQ 群：788910197。
