👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

HarmonyOS 7 新增了通过文本搜索图片的能力。对于只有一个图片集合的 Demo,调用 insertImage() 建索引,再调用 search() 查询并不复杂;真正进入业务设计后,一个很快会遇到的问题是:如果应用里同时存在旅行照片、工作图片、截图等不同图片集合,应该怎样组织索引?

textSearchImage 提供了一个很容易被忽略的参数:scope。

它不负责替我们创建系统相册,也不是一个展示层的“分类名称”。从接口形态来看,更适合把它理解为文搜图索引中的逻辑检索范围:插入图片时确定图片属于哪个 scope,搜索时指定要在哪个 scope 中查找,删除时也带上对应 scope。

这篇文章就围绕这个参数做一个最小实践:把旅行、工作、截图三组图片分别建立索引,并进一步解决“用户输入一次关键词,希望同时搜索多个分类”的问题。

华为官方将“通过文本搜索图片”列为 HarmonyOS 7(API 26)新增能力,属于 Core Vision Kit。官方 API 当前标明支持 Phone、PC/2in1 和 Tablet,接口起始版本均为 26.0.0,并且仅支持 Stage 模型。

一、scope 到底是什么?

先看 insertImage() 的接口:

insertImage(imagePath: string, scope: string): Promise<boolean>

再看搜索接口:

search(
  query: string,
  scope: string,
  topKey?: number
): Promise<Array<ImageObject>>

以及删除接口:

deleteImage(
  imagePath: string,
  scope: string
): Promise<boolean>

三个核心操作都出现了同一个 scope 参数。搜索结果中的 ImageObject 也会返回:

imagePath: string
scope: string
similarity: number

其中 similarity 的官方取值范围为 [-1, 1],值越大表示图片与查询文本的相似度越高。

这组接口已经把 scope 的用途表达得比较清楚:

scope 是图片索引的一部分,也是搜索范围的一部分。

例如:

travel
├── beach.jpg
├── mountain.jpg
└── hotel.jpg

work
├── meeting.jpg
├── whiteboard.jpg
└── architecture.jpg

screenshot
├── payment.png
├── ticket.png
└── chat.png

图片文件本身仍然位于应用可访问的沙箱路径中,而 travel、work、screenshot 用来区分它们进入文搜图数据库时所属的逻辑范围。

这里比较容易理解错:scope 不是让算法“识别这张图属于旅行还是工作”的分类模型。分类关系由应用在调用 insertImage() 时自己确定。

二、先确认 HarmonyOS 7 的接口边界

这次使用的是:

import { textSearchImage } from '@kit.CoreVisionKit';

官方当前资料确认的信息如下:

项目官方约束
KitCore Vision Kit
模块textSearchImage
起始版本26.0.0
HarmonyOSHarmonyOS 7(API 26)新增
系统能力SystemCapability.AI.Vision.VisionBase
模型仅 Stage 模型
设备Phone、PC/2in1、Tablet 26.0.0+
scope 长度1~32
query 长度1~100
topKey0~100,默认 100

官方对 scope 的参数说明写的是支持字母或数字。值得留意的是,官方 API 示例中又出现过 default_scope 这样的下划线写法。由于文字约束与示例之间存在这个细节差异,业务代码如果希望尽量规避兼容性歧义,可以优先使用纯字母、数字组成的 scope,例如:

travel
work
screenshot
album01
business02

本文的示例也采用这种命名方式。

搜索词还有一个很容易漏掉的限制:官方文档说明 query 不支持纯数字和纯字母,可以使用中文,或中文与数字、字母、符号组合。因此真正做搜索框校验时,不建议默认把任意英文字符串都直接提交给接口。

三、为什么图片库需要逻辑隔离

假设一个应用同时管理三类内容:

  • 旅行照片;
  • 工作素材;
  • 用户保存的截图。

用户搜索“海边夕阳”时,大概率只希望浏览旅行照片;搜索“会议白板”时,可以只查工作素材;搜索“付款二维码”时,则可以进入截图集合。

如果所有图片都使用一个固定的 default scope,从接口角度当然也能建立索引,但业务层就失去了一个天然的检索边界。

换成三个 scope:

class ImageScopes {
  static readonly TRAVEL: string = 'travel';
  static readonly WORK: string = 'work';
  static readonly SCREENSHOT: string = 'screenshot';
}

之后搜索范围就可以由页面直接决定:

await textSearchImage.search('海边夕阳', ImageScopes.TRAVEL, 20);

或者:

await textSearchImage.search('会议白板', ImageScopes.WORK, 20);

这种设计还有一个好处:业务页面不需要先拿到全部文搜图结果,再根据自己的相册字段进行第二次过滤。检索范围在调用 search() 时已经明确。

四、建立旅行、工作、截图三个图片集合

在真正插图之前,需要先初始化文搜图分析器:

import { textSearchImage } from '@kit.CoreVisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initImageSearch(): Promise<boolean> {
  try {
    const result = await textSearchImage.init();
    hilog.info(0x0000, 'ImageSearch', `init result: ${result}`);
    return result;
  } catch (error) {
    const err = error as BusinessError;
    hilog.error(
      0x0000,
      'ImageSearch',
      `init failed, code=${err.code}, message=${err.message}`
    );
    return false;
  }
}

init() 返回 Promise<boolean>。官方同时给出了对应的 release(),用于释放文本搜索图片分析器服务。

然后定义三组 scope:

class ImageScopes {
  static readonly TRAVEL: string = 'travel';
  static readonly WORK: string = 'work';
  static readonly SCREENSHOT: string = 'screenshot';

  static readonly ALL: string[] = [
    ImageScopes.TRAVEL,
    ImageScopes.WORK,
    ImageScopes.SCREENSHOT
  ];
}

这里只把 scope 当作稳定的业务常量,而不是在各个页面直接手写字符串。

实际项目里这是一个很小但很有价值的约束。否则插入时写成 screenshot,删除时写成 screenshots,接口层面看到的已经是两个不同的输入值。

五、insertImage 时把分类写进 scope

官方定义:

insertImage(imagePath: string, scope: string): Promise<boolean>

imagePath 要求是图片沙箱路径,长度范围为 1~128。官方还明确列出了 1013100001 错误:图片路径或者图片尺寸不满足要求时可能出现该错误。

可以在业务层封装一层:

async function addImageToIndex(
  imagePath: string,
  scope: string
): Promise<boolean> {
  try {
    const result = await textSearchImage.insertImage(imagePath, scope);

    hilog.info(
      0x0000,
      'ImageSearch',
      `insert result=${result}, scope=${scope}`
    );

    return result;
  } catch (error) {
    const err = error as BusinessError;

    hilog.error(
      0x0000,
      'ImageSearch',
      `insert failed, code=${err.code}, message=${err.message}`
    );

    return false;
  }
}

假设图片已经被业务正确保存到应用可访问的沙箱路径中,建立索引时分别指定 scope:

await addImageToIndex(travelImagePath, ImageScopes.TRAVEL);
await addImageToIndex(workImagePath, ImageScopes.WORK);
await addImageToIndex(screenshotImagePath, ImageScopes.SCREENSHOT);

真正需要关注的是:图片文件的业务分类和 textSearchImage 索引中的 scope 要保持同步。

例如用户把一张图片从“工作”分类移动到“旅行”,应用不能只改自己的数据库字段,却继续让旧的文搜图索引停留在 work 中。

这已经不是 UI 分类问题,而是索引一致性问题。

六、在指定 scope 中搜索

如果页面当前就是“旅行相册”,搜索最简单:

async function searchTravelImages(
  query: string
): Promise<textSearchImage.ImageObject[]> {
  try {
    return await textSearchImage.search(
      query,
      ImageScopes.TRAVEL,
      20
    );
  } catch (error) {
    const err = error as BusinessError;

    hilog.error(
      0x0000,
      'ImageSearch',
      `search failed, code=${err.code}, message=${err.message}`
    );

    return [];
  }
}

例如:

const results = await searchTravelImages('海边的日落');

results.forEach((item) => {
  hilog.info(
    0x0000,
    'ImageSearch',
    `path=${item.imagePath}, scope=${item.scope}, similarity=${item.similarity}`
  );
});

这里的 topKey = 20 表示在满足匹配条件的情况下,最多返回 20 张图片。官方允许的范围是整数 0~100,默认值为 100。

七、一个关键词怎样同时搜索三个 scope

这是 scope 设计里最值得单独讲的地方。

search() 的参数不是:

search(query, scopes)

而是:

search(query, scope, topKey?)

也就是说,官方接口单次调用只提供一个 scope 参数。

因此,如果产品需要一个“全部图片”入口,希望用户输入一次“海边的日落”,同时检索旅行、工作、截图三个集合,就不应该虚构一个数组参数,而应在应用层完成多 scope 聚合。

可以写成:

async function searchAcrossScopes(
  query: string,
  scopes: string[],
  topKey: number = 20
): Promise<textSearchImage.ImageObject[]> {
  let merged: textSearchImage.ImageObject[] = [];

  for (const scope of scopes) {
    const results = await textSearchImage.search(
      query,
      scope,
      topKey
    );

    merged = merged.concat(results);
  }

  merged.sort((a, b) => b.similarity - a.similarity);

  return merged.slice(0, topKey);
}

调用时:

const results = await searchAcrossScopes(
  '有山有湖的风景',
  ImageScopes.ALL,
  20
);

这里要区分两件事:

按 scope 检索是 Core Vision Kit 提供的能力;循环搜索多个 scope、合并结果、按 similarity 排序,是应用自己的业务逻辑。

不能把后者描述成 textSearchImage 原生支持“多个 scope 一次查询”。

这里还存在一个容易忽略的问题。假设我们要求最终最多显示 20 条,为了避免三个 scope 各返回 20 条后直接显示 60 条,示例最后又做了一次:

return merged.slice(0, topKey);

于是 topKey 在这里变成“最终聚合结果的上限”。

八、不同业务模块的 scope 怎么规划

scope 最大长度只有 32,且官方参数约束写明支持字母或数字,因此它更适合作为稳定的机器标识,而不是用户可编辑的相册标题。

例如用户可能把相册标题从:

2026 北京出差

改成:

北京项目

如果直接把展示名称作为 scope,改名之后就会面临索引迁移。

更合适的设计是:

业务含义展示名称scope
旅行图片我的旅行travel
工作图片工作资料work
截图手机截图screenshot

对于更复杂的应用,可以把 scope 定义为业务域,而不是具体页面:

travel
work
receipt
document
screenshot
favorite

这里需要提前明确一个边界:scope 只是一个字符串参数,官方接口没有暴露“创建 scope”“重命名 scope”“查询所有 scope”之类的管理 API。

所以 scope 体系最好由应用自己维护,而不是等索引建立之后再反推业务分类。

九、删除图片时,别只删文件

官方提供:

deleteImage(
  imagePath: string,
  scope: string
): Promise<boolean>

它用于从文搜图数据库中删除对应图片记录。

可以继续沿用前面的封装:

async function removeImageFromIndex(
  imagePath: string,
  scope: string
): Promise<boolean> {
  try {
    return await textSearchImage.deleteImage(
      imagePath,
      scope
    );
  } catch (error) {
    const err = error as BusinessError;

    hilog.error(
      0x0000,
      'ImageSearch',
      `delete failed, code=${err.code}, message=${err.message}`
    );

    return false;
  }
}

例如删除旅行相册中的图片索引:

await removeImageFromIndex(
  imagePath,
  ImageScopes.TRAVEL
);

从接口设计上看,这也解释了为什么工程中应该保存:

业务图片记录
    ↓
imagePath
scope
    ↓
textSearchImage 索引

至少要能够在业务图片被删除、迁移或者重新分类时,知道应该操作哪个索引记录。

十、clearData 不是“清空某个相册”

textSearchImage 还提供:

clearData(): Promise<boolean>

但它的语义不是:

clearScope("travel")

而是清除数据库中的所有数据。

官方尤其建议在模型能力更新后执行该操作。insertImage() 和 search() 都可能返回 1013100003,其含义是能力已经更新,需要先调用 clearData(),成功后再重新执行此前操作。

例如可以单独识别:

function isModelUpdated(error: BusinessError): boolean {
  return error.code === 1013100003;
}

碰到这个错误时,更合理的索引维护流程是:

收到 1013100003
        ↓
调用 clearData()
        ↓
文搜图数据库全部索引被清空
        ↓
根据应用自己的图片记录重新建立索引

这里不要把 clearData() 当成删除一个相册的快捷方法。

如果只想删除 travel 分类,而官方当前又没有提供 clearScope(scope) 这样的接口,那么应用只能根据自己维护的图片清单,对该 scope 下的图片逐条执行 deleteImage(imagePath, scope)。

这一点会直接影响数据层设计:应用自己的图片元数据不能只依赖 textSearchImage 数据库。

十一、实际工程中的索引维护

把 Demo 做到 insertImage() 和 search() 并不难,真正需要设计的是“业务数据发生变化以后,索引如何保持一致”。

可以把索引生命周期分成四类事件。

1. 新增图片

图片进入应用沙箱并完成业务分类之后:

保存业务记录
→ 确定 scope
→ insertImage(imagePath, scope)

2. 删除图片

不要只删除实际文件。

建议业务顺序至少考虑:

定位 imagePath + scope
→ deleteImage()
→ 更新应用自己的图片记录
→ 再处理实际文件生命周期

具体事务与失败补偿策略需要由应用自己的数据层决定,textSearchImage 本身并没有提供业务事务接口。

3. 图片换分类

例如:

work → travel

从现有 API 形态来看,没有“修改 scope”的接口。

因此可以按“删除旧索引 + 插入新索引”的思路维护:

async function moveImageScope(
  imagePath: string,
  oldScope: string,
  newScope: string
): Promise<boolean> {
  const deleted = await textSearchImage.deleteImage(
    imagePath,
    oldScope
  );

  if (!deleted) {
    return false;
  }

  return await textSearchImage.insertImage(
    imagePath,
    newScope
  );
}

这里同样不能把它描述成 Core Vision Kit 提供了 moveScope();这是根据官方已有的删除、插入接口组织出的业务操作。

4. 模型能力发生更新

收到官方定义的 1013100003 后:

clearData
→ 从应用数据库读取图片
→ 根据持久化的 scope 重新 insertImage

这也是为什么建议业务数据库至少保存“哪张图片应该属于哪个逻辑集合”。

十二、几个比较容易理解错的地方

scope 不是系统相册

travel、work、screenshot 是文搜图接口的作用域字符串。

本文用“相册”来帮助表达业务场景,并不代表调用 insertImage() 就会在系统图库里创建三个真实相册。

一个 scope 不等于一个搜索模型

三个 scope 共享的是同一个 textSearchImage 能力。

它们的作用在这里是划定索引和搜索范围,而不是分别训练三套模型。

官方公开 API 中也没有要求开发者自己训练模型。

search 一次只能明确传一个 scope

这是本文最关键的接口边界。

想做:

全部图片

需要应用分别搜索若干 scope,再聚合结果。

想做:

只看截图

则直接:

textSearchImage.search(
  query,
  ImageScopes.SCREENSHOT,
  20
);

scope 不适合直接使用用户输入名称

一方面存在长度与字符约束,另一方面用户可以随时给相册改名。

因此更建议:

展示层名称:2026 日本旅行
索引 scope:travel

而不是把 UI 文本直接绑定到索引结构。

clearData 的粒度是整个数据库

目前公开接口只有:

clearData()

并没有:

clearData(scope)

因此它更适合模型能力更新后的整体重建,而不是普通相册删除逻辑。

十三、实际项目可以按这个顺序排查

文搜图没有达到预期时,可以先按照接口约束逐层检查:

  1. 先确认系统版本。 textSearchImage 起始版本是 26.0.0,并属于 HarmonyOS 7(API 26)新增能力。
  2. 确认设备类型。 当前官方 API 页面标注 Phone、PC/2in1、Tablet 26.0.0+。
  3. 确认工程采用 Stage 模型。
  4. 确认已经调用 init(),并检查返回值。
  5. 确认 imagePath 是接口要求的图片沙箱路径。
  6. 核对 insert、search、delete 使用的 scope 是否一致。
  7. 检查 scope 长度以及字符设计。
  8. 检查 query 是否符合 1~100 字符限制,同时避免纯数字、纯字母查询词。
  9. 确认 topKey 位于 0~100。
  10. 捕获 BusinessError,特别关注 1013100001、1013100002、1013100003。
  11. 遇到 1013100003 时,按官方要求清空索引,再通过业务数据重新建立。

如果是“某个分类搜不到、全部搜索却表现异常”,还可以继续检查应用自己的多 scope 聚合逻辑,而不是马上把问题归到模型本身。

开发经验总结

textSearchImage 的 API 数量不多,但 scope 决定了图片索引以后是否容易管理。

这次最小实践可以整理成四个工程结论。

第一,scope 应该被当成稳定的索引分区键,而不是页面显示名称。 travel、work、screenshot 这类稳定标识比动态相册标题更适合。

第二,插入、搜索和删除要使用同一套 scope 规则。 scope 最好集中定义,不要散落在页面字符串中。

第三,多 scope 搜索目前需要应用层组合。 search() 一次只接受一个 scope;同时搜索多个业务分类时,应分别查询,再根据 similarity 合并排序,而不是假设 API 存在数组形式的 scope。

第四,业务数据库与 AI 索引要分开管理。 特别是 clearData() 会清除全部文搜图数据,而模型更新错误 1013100003 又明确要求执行清理。因此应用必须有能力根据自己的图片数据重新构建索引。

文搜图真正进入业务以后,最值得提前设计的往往不是搜索框,而是索引生命周期:图片什么时候插入、删除、换分类,模型更新之后又怎样恢复。把这套关系先设计清楚,scope 才不只是一个随手填写的字符串。

如果正在设计更复杂的图片管理业务,还可以继续考虑一个问题:scope 应该按照“相册”划分,还是按照“业务域”划分? 对需要长期维护和重建索引的应用来说,这个决定往往比页面上有几个分类按钮更重要。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐