搜索消息

SDK 从 1.1.0 版本开始提供本地消息搜索功能，支持在指定的单个会话中按关键字、发送者用户 ID 或时间范围搜索消息。SDK 26.7.0 及以上版本还支持按会话条件和消息条件组合搜索本地消息。消息搜索仅查询本地数据库中的消息，返回包含指定关键字或符合全部搜索条件的消息列表。

支持关键字搜索的消息：

• 内置的消息类型中文本消息（TextMessage），文件消息（FileMessage）.
• 自定义消息类型实现 getSearchableWord 也可以支持关键字搜索，需要您参考文档自行实现。详见自定义消息类型。

SDK 26.7.0 及以上版本可以直接使用 searchMessagesWithParams 方法进行跨会话搜索。较早版本可以通过以下步骤实现基于关键字的全局搜索：

1. 根据关键字搜索本地存储的全部会话，获取包含关键字的会话列表。
2. 根据返回的会话列表，逐个搜索会话中符合条件的消息。

根据关键字搜索本地会话

按关键字搜索本地存储的所有会话，获取符合条件的会话列表。请使用 searchConversationsWithResult 方法。

接口原型

TypeScript

/**
 * 根据关键字搜索本地会话。
 * @param conTypes 搜索的会话类型列表
 * @param keyword 搜索的关键字，长度范围 [1, 256]
 * @param objNameList 消息类型数组。用于搜索指定类型的消息；为空代表所有所有类型消息
 * @returns 搜索到的会话列表
 * @version 1.2.0
 */
public searchConversationsWithResult(
  typeList: List<ConversationType>,
  keyword: string,
  objNameList: List<string> | null,
): Promise<IAsyncResult<List<SearchConversationResult>>>

参数说明

参数名	类型	详细说明
typeList	List	要搜索的会话类型列表（如单聊/群聊/系统会话等）
keyword	string	搜索的关键字，长度范围 [1, 256]）
objNameList	List	消息类型数组。用于搜索指定类型的消息；为空代表所有所有类型消息

示例代码

TypeScript

let conTypeList = new List<ConversationType>();
conTypeList.add(ConversationType.Private);
conTypeList.add(ConversationType.Group);

let keyword = "关键字";

IMEngine.getInstance().searchConversationsWithResult(conTypeList, keyword, null).then(result => {
  if (EngineError.Success !== result.code) {
    // 搜索会话失败
    return;
  }
  if (!result.data) {
    // 搜索的会话内容为空
    return;
  }
  // 搜索的结果
  let searchResultList = result.data as List<SearchConversationResult>;

});

按组合条件搜索本地消息

提示

SDK 从 26.7.0 版本开始提供该接口。

您可以使用 searchMessagesWithParams 方法，按关键字、时间范围、会话条件和消息条件组合搜索本地消息。接口返回当前页的消息列表，以及符合完整搜索条件的消息总数。

接口原型

TypeScript

public searchMessagesWithParams(
  params: SearchMessageParams,
): Promise<IAsyncResult<SearchMessageListResult>>;

参数说明

参数	类型	说明
params	SearchMessageParams	搜索参数。

SearchMessageParams 属性说明

属性	类型	必填	说明
keyword	string	否	搜索关键字，最大长度为 1000 个字符。不传或传空字符串时，不按消息内容筛选。
limit	number	是	每页消息数量，最小值为 1；超过 100 时按 100 处理。
offset	number	否	分页偏移量，取值必须大于等于 0，默认值为 0。
order	Order	否	消息排序方式，默认值为 Order.Descending。
timeRange	TimeRange	否	消息发送时间范围。不传时不按时间筛选。
conversationFilter	ConversationFilter	否	会话过滤条件。不传时不按会话筛选。
messageFilter	MessageFilter	否	消息过滤条件。不传时不按消息属性筛选。

TimeRange 属性说明：

属性	类型	必填	说明
startTime	number	否	开始时间，毫秒时间戳，包含该时间点，取值必须大于等于 0。不传时从时间轴起点开始搜索。
endTime	number	否	结束时间，毫秒时间戳，包含该时间点。不传或传非正数时使用当前时间。归一化后的 endTime 必须大于等于 startTime。

ConversationFilter 属性说明：

属性	类型	必填	说明
conversationTypes	Array<ConversationType>	否	有效的会话类型列表。传空数组时不按会话类型筛选。
targetIds	Array<string>	否	会话 ID 列表，最多 20 项，每项长度范围为 [1, 64]。传空数组时不按会话 ID 筛选。
channelIds	Array<string>	否	频道 ID 列表，最多 10 项，每项最大长度为 20。空字符串表示匹配频道 ID 为空的会话；传空数组时不按频道筛选。

MessageFilter 属性说明：

属性	类型	必填	说明
senderIds	Array<string>	否	消息发送者 ID 列表，最多 20 项，每项长度范围为 [1, 64]。传空数组时不按发送者筛选。
objectNames	Array<string>	否	消息类型列表，每项长度范围为 [1, 128]，最多前 300 项参与查询。传空数组时不按消息类型筛选。

返回结果说明

属性	类型	说明
messages	List<Message>	当前页的消息列表。
matchCount	number	符合完整搜索条件的消息总数，不受 offset 和 limit 影响。

搜索结果为零条时，接口仍会返回 SearchMessageListResult，其中 messages 为空列表，matchCount 为 0。

示例代码

TypeScript

let params: SearchMessageParams = {
  keyword: "关键字",
  limit: 10,
  offset: 0,
  order: Order.Descending,
  timeRange: {
    startTime: Date.now() - 24 * 60 * 60 * 1000,
    endTime: Date.now()
  },
  conversationFilter: {
    conversationTypes: [ConversationType.Private, ConversationType.Group],
    targetIds: ["targetId1", "targetId2"],
    channelIds: ["channelId"]
  },
  messageFilter: {
    senderIds: ["userId"],
    objectNames: [TextMessageObjectName]
  }
};

IMEngine.getInstance().searchMessagesWithParams(params).then(result => {
  if (EngineError.Success !== result.code) {
    // 搜索消息失败
    return;
  }
  if (!result.data) {
    // 未返回搜索结果数据
    return;
  }

  let searchResult = result.data as SearchMessageListResult;
  let messages = searchResult.messages;
  let matchCount = searchResult.matchCount;
});

在指定单个会话中搜索

获取包含关键词的会话列表后，可以搜索指定单个会话中符合条件的消息。

根据关键字搜索消息

您可以在本地存储中根据关键字搜索指定会话中的消息，支持搜索指定时间点之前的历史消息记录。回调中分页返回包含指定关键字的消息列表。

接口原型

TypeScript

public searchMessages(conId: ConversationIdentifier, keyword: string, objNameList: List<string> | null, startTime: number, count: number): Promise<IAsyncResult<List<Message>>>;

参数说明

参数	类型	说明
conId	ConversationIdentifier	会话标识。
keyword	string	搜索的关键字。
objectNames	string 集合	消息类型列表，用于搜索指定类型的消息；为空代表所有所有类型消息。
startTime	number	查询记录的起始时间，毫秒时间戳。传 0 时从最新消息开始搜索。非 0 时从该时间往前搜索。
count	number	每页的数量，每页数量建议最多 100 条。传 0 时返回所有搜索到的消息。

示例代码

TypeScript

let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "会话 ID";

let keyword = "需要搜索的关键字";
let objNameList = new List<string>();
objNameList.add(TextMessageObjectName);

let startTime = Date.now();
let count = 10;


IMEngine.getInstance().searchMessages(conId, keyword, objNameList, startTime, count).then(result => {
  if (EngineError.Success !== result.code) {
    // 搜索消息失败
    return;
  }
  if (!result.data) {
    // 搜索消息为空
    return;
  }
  // 搜索到的消息
  let msgList = result.data as List<Message>;

});

根据关键字搜索指定时间段的消息

您可以将关键字搜索的范围限制在指定时间段内。回调中分页返回包含指定关键字和时间段要求的消息列表。

接口原型

TypeScript

public earchMessagesInTimeRange(conId: ConversationIdentifier, keyword: string, option: ISearchMessageInTimeRangeOption): Promise<IAsyncResult<List<Message>>>;

参数说明

limit 参数控制返回的搜索结果数量，取值范围为 [1-100]。超过 100 默认使用最大值 100。

参数	类型	说明
conId	ConversationIdentifier	会话标识
keyword	String	搜索的关键字
option	ISearchMessageInTimeRangeOption	搜素配置

示例代码

TypeScript

let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "会话 ID";

let keyword = "需要搜索的关键字";

let option: ISearchMessageInTimeRangeOption = {
  startTime: Date.now() - 24 * 60 * 60 * 1000,
  endTime: Date.now(),
  offset: 0,
  limit: 10
}

IMEngine.getInstance().searchMessagesInTimeRange(conId, keyword, option).then(result => {
  if (EngineError.Success !== result.code) {
    // 搜索消息失败
    result;
  }
  if (!result.data) {
    // 搜素消息为空
    return;
  }
  // 搜索的消息列表
  let msgList = result.data as List<Message>;
});

根据用户 ID 搜索消息

您可以在本地存储中根据搜索来自指定用户 userId 的消息，支持搜索指定时间点之前的历史消息记录。回调中分页返回包含符合条件的消息列表。

接口原型

TypeScript

public searchMessagesByUser(conId: ConversationIdentifier, userId: string, startTime: number, count: number): Promise<IAsyncResult<List<Message>>>;

参数说明

参数	类型	说明
conId	ConversationIdentifier	会话标识
userId	string	要查询的用户 ID。
startTime	number	查询记录的起始时间，毫秒时间戳。传 0 时从最新消息开始搜索。非 0 时从该时间往前搜索。
count	number	返回的搜索结果数量。最大值为 100。超过 100 时默认返回 100 条。

示例代码

TypeScript

let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "会话 ID";

let userId = "用户 ID";

let startTime = Date.now();
let count = 10;

IMEngine.getInstance().searchMessagesByUser(conId, userId, startTime, count).then(result => {
  if (EngineError.Success !== result.code) {
    // 搜索消息失败
    result;
  }
  if (!result.data) {
    // 搜素消息为空
    return;
  }
  // 搜索的消息列表
  let msgList = result.data as List<Message>;
});

根据用户 ID 数组搜索消息

提示

SDK 1.3.0 版本后支持该方法。

您可以在本地存储中根据搜索来自指定用户 userId 数组的消息，支持搜索指定时间点之前的历史消息记录。回调中分页返回包含符合条件的消息列表。

接口原型

TypeScript

public searchMessagesByUsers(conId: ConversationIdentifier, sendIds: Array<string>, objNameArray: Array<string> | null, startTime: number, count: number, order: Order): Promise<IAsyncResult<List<Message>>>;

参数说明

参数	类型	说明
conId	ConversationIdentifier	会话标识
userIdArray	string 数组	要查询的用户 ID 数组。
startTime	number	查询记录的起始时间，毫秒时间戳。传 0 时从最新消息开始搜索。非 0 时从该时间往前搜索。
count	number	返回的搜索结果数量。最大值为 100。超过 100 时默认返回 100 条。
order	Order	查询的顺序

示例代码

TypeScript

let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

 let userIdArray = ["UserId1","UserId2"];

 let objNameArray: Array<string> | null = null;

 let startTime = Date.now();
 let count = 10;
 let order = Order.Ascending;

 IMEngine.getInstance().searchMessagesByUsers(conId, userIdArray, objNameArray, startTime, count, order).then(result => {
   if (EngineError.Success !== result.code) {
     // 失败
     return;
   }
   if (!result.data) {
     // 数据为空
     return;
   }
   // 搜索到的消息列表
   let msgList = result.data as List<Message>;
 })