SDKsFlutter

搜索消息

在 Flutter SDK 已同步的本地消息中按关键词与会话条件搜索。

在当前客户端本地已同步的消息数据库中，按关键词、会话、消息类型以及时间范围进行检索。群聊检索时必须使用对应的 conversationID，而非发送消息时的 groupID。

若业务入口仅持有用户 ID 或群组 ID，需先通过生成会话 ID换取对应的会话 ID；若需进行全局跨会话搜索，将 conversationID 传 null 即可。

搜索范围仅限于 SDK 已同步至本地沙盒数据库的消息记录。服务端的全局全量全文索引检索属于业务云端能力，可由业务后端搜索服务返回对应的会话与消息 ID，再由客户端定位拉取。

创建搜索查询

keywordList 接收关键词列表，但当前只使用一个关键词。搜索框提交前应去掉首尾空格并过滤空值。

final keyword = input.trim();
if (keyword.isNotEmpty) {
  final result = await OpenIM.iMManager.messageManager.searchLocalMessages(
    conversationID: conversationID,
    keywordList: [keyword],
    messageTypeList: [MessageType.text, MessageType.atText],
    pageIndex: 1,
    count: 20,
  );
  renderSearchResult(result);
}

高级搜索

搜索接口还支持按消息类型列表与时间区间进行复合条件筛选：

final result = await OpenIM.iMManager.messageManager.searchLocalMessages(
  conversationID: conversationID,
  keywordList: ['release'],
  messageTypeList: [MessageType.text],
  searchTimePosition: searchTimePosition,
  searchTimePeriod: searchTimePeriod,
  pageIndex: 1,
  count: 20,
);

若需允许搜索图片、文件或自定义消息，可将对应的 MessageType 数值常量添加至 messageTypeList 中；传入空列表表示不限制消息类型。

参数说明

参数	类型	是否必填	说明
`conversationID`	`String?`	否	指定搜索的会话 ID；传 `null` 表示搜索本地所有会话。
`keywordList`	`List<String>`	否	搜索关键词列表；建议传入经空白过滤后的关键词。当前匹配首个非空关键词。
`keywordListMatchType`	`int`	否	多关键词匹配策略，默认为 `0`。
`senderUserIDList`	`List<String>`	否	发送者筛选列表，默认为空列表。
`messageTypeList`	`List<int>`	否	待检索的消息类型常量列表（如 `MessageType.text`），为空表示不限类型。
`searchTimePosition`	`int`	否	搜索起始时间戳（秒），默认为 `0` 表示从当前时刻起算。
`searchTimePeriod`	`int`	否	向过去回溯搜索的时间范围（秒），默认为 `0` 表示不限时间。
`pageIndex`	`int`	否	分页页码，从 `1` 开始，默认为 `1`。
`count`	`int`	否	每页拉取的匹配条数，默认为 `40`。

返回结果

Future 成功返回搜索结果对象（SearchResult），各字段均可能为 nullable：

字段	类型	说明
`totalCount`	`int?`	满足搜索条件的消息总数量。
`searchResultItems`	`List<SearchResultItems>?`	按会话归类组织的搜索结果条目列表。
`findResultItems`	`List<SearchResultItems>?`	精确匹配查找结果列表，本接口主要读取 `searchResultItems`。

每个 SearchResultItems 对象聚合对应会话的搜索命中情况：

字段	类型	说明
`conversationID`	`String?`	命中消息所属会话 ID。
`conversationType`	`int?`	会话类型。
`showName`	`String?`	会话展示名称。
`faceURL`	`String?`	会话头像 URL。
`messageCount`	`int?`	该会话中命中的消息总数。
`messageList`	`List<Message>?`	本分页中命中并加载的消息列表。

分页加载下一页时，应保持各项筛选条件不变，仅递增 pageIndex；当搜索关键词或筛选条件变动时，应清空既有结果并重置 pageIndex = 1。多结果列表合并时应使用 conversationID 与消息的非空 clientMsgID 去重。

搜索操作建立静态数据快照，不会触发消息事件通知。

处理搜索结果变化

搜索命中的消息可能在页面打开后被撤回、删除，或由新的同步数据补充。应使用接收消息、删除消息和撤回消息中的统一监听器更新结果，检索逻辑专注于数据筛选与分页展示，避免在各搜索组件中重复注册消息监听。

跳转到命中消息时，使用结果项的 conversationID 和消息的 clientMsgID 定位。需要展示前后文时，按按 ID 定位消息分别读取较旧与较新的消息。

需要显示当前时刻的搜索结果时，可以用相同条件重新执行查询。搜索 Future、后续消息事件和重新查询是三条独立路径。

创建搜索查询

高级搜索

参数说明

返回结果

处理搜索结果变化

相关页面