HarmonyOS 文搜图开发复盘：从关键词检索到结果呈现的完整闭环【鸿蒙心迹】

李游Leo

14人浏览 · 2026-09-28 20:32:58

李游Leo · 2026-09-28 20:32:58 发布

这不是一篇“把接口调通就结束”的功能记录，而是一篇从真实项目出发，把关键词检索、图片索引、结果排序、预览体验一路串起来的开发复盘。

一、这个需求看起来不难，真正难的是“搜得对”

刚接到“文搜图”这个需求时，我第一反应其实挺直接：用户输入几个词，比如“海边落日”“毕业合照”“身份证照片”，系统从本地相册里把相关图片找出来，不就行了吗？

真正开始做以后，我很快发现这个问题根本不是一个简单的列表筛选。

因为用户说的“搜图”，背后至少有三层意思。

第一层，是能不能搜到。本地图片不是数据库，很多照片根本没有现成的文字描述。如果只靠文件名，绝大多数结果都不靠谱。

第二层，是搜到的对不对。用户输入“海边落日”，系统返回一堆蓝天大海也不完全错，但用户真正要的往往是“海边 + 夕阳 + 暖色天空”的组合场景。这时候，单纯关键字命中就不够了。

第三层，是结果展示有没有产品感。如果搜索结果只是机械地堆一屏图片，用户只能自己二次判断，体验还是很割裂。好的结果页，应该让用户一眼知道：为什么是这张、它和搜索词的关系是什么、还有没有更相似的图。

也就是说，这类功能看起来入口很小，真正要做好，必须把链路拉长：

输入词怎么理解；
本地图库怎么建索引；
检索怎么召回候选集；
候选结果怎么排序；
预览页怎么把“匹配理由”讲清楚。

文章下面我就按这个顺序，把这次 PhotoFinder 的实现思路完整拆开。

二、先不要急着写搜索框，先把整条链路想明白

我后面做这类功能时，习惯先画关系图。不是为了好看，而是为了避免一开始就扎进页面细节里，结果中途发现索引、排序、展示根本没串起来。

这次的链路我最后收敛成六步：用户输入关键词 → 查询解析 → 本地图片索引 → 关键词匹配 / 语义召回 → 结果排序与过滤 → 结果展示与预览。

从图上看，这是一条很顺的流程，但里面有两个特别关键的判断。

1. “文搜图”不是纯前端功能

一开始如果只把它当成 ArkUI 搜索页去做，最后很容易做成一个 UI 完整、结果很弱的 Demo。因为真正影响结果质量的，往往不是前端组件，而是底层索引和召回策略。

2. 搜索结果不是一步到位，而是“多阶段收敛”

用户输入的词往往是模糊的。系统先做词义理解和纠错，再做多路召回，最后根据相关性和质量排序，这才比较接近真实产品的行为。

这也是我这次实现里的一个核心原则：别指望某一个步骤把所有问题都解决，而是让每一层都各自承担一部分责任。

三、本地图库不是数据库，先把索引建起来

真正动手时，最先碰到的问题就是：本地照片太“散”了。

它不像业务表，有固定字段和明确结构。一张图能用的信息，可能包括：

文件名；
拍摄时间；
位置信息；
图片宽高；
EXIF 元数据；
场景标签；
人脸、物体、颜色等衍生特征。

如果不先把这些信息整理出来，后面的搜索就没有基础。

所以我做的第一件事，不是写搜索事件，而是建立一个本地索引模块。思路很简单：第一次进入页面或首次启动时扫描图库，把用于检索的元数据提取出来，落到本地缓存里。

下面这段代码就是索引初始化的核心入口：

@Entry
@Component
struct SearchPage {
  @State queryText: string = ''
  @State results: PhotoItemData[] = []
  @State isSearching: boolean = false

  async aboutToAppear() {
    await this.buildIndex()
  }

  async buildIndex() {
    try {
      console.info('开始构建图片索引...')
      await photoIndex.buildIndex()
      console.info('Index loaded: ' + photoIndex.getCount() + ' photos')
    } catch (err) {
      console.error('构建索引失败: ' + JSON.stringify(err))
    }
  }
}

这段代码看起来不复杂，但它解决的是两个工程问题。

第一个，是搜索前置条件。很多 Demo 里，搜索按钮一点就直接查，这种实现跑得通，但真实项目里，索引是否完成、是否可用、是否需要增量更新，都是要考虑的。

第二个，是把一次性成本前置。索引建立本身有消耗，但只要把它设计成初始化阶段的一次操作，后面的查询响应就会更稳定。

索引层内部，我会把图片元数据和可检索特征统一封装成一个结构体，例如：

type PhotoItemData = {
  id: string,
  uri: string,
  title: string,
  tags: string[],
  shootTime: number,
  location?: string,
  sceneText?: string,
  width: number,
  height: number
}

这里有个很实际的经验：不要一上来就追求“全量 AI 特征”。

如果只是做一个真实可用的项目版本，先把文件名、时间、地点、基础标签、常见场景词打通，整体收益就已经很大了。后面如果要加更复杂的视觉语义能力，再逐步增强，不要一开始把系统复杂度拉得太高。

四、搜索不是模糊匹配，而是“关键词匹配 + 语义召回”

索引建好以后，接下来才轮到真正的搜索逻辑。

我最开始试过一个很直白的版本：用户输入什么，就拿这个词去做包含匹配。结果非常一般。比如“海边落日”和“落日晚霞”，明明用户意图很接近，但纯字符串匹配会把它们拆得很散。

所以后来我把搜索拆成了两层：

一层做查询解析，包括分词、同义词扩展、简单纠错；
一层做召回与排序，把关键词命中和语义相似度组合起来。

核心搜索逻辑大致是这样：

async searchPhotos() {
  const text = this.queryText.trim()
  if (text.length === 0) {
    this.results = []
    return
  }

  this.isSearching = true
  try {
    console.info(`Searching photos with query: ${text}`)
    const start = Date.now()
    const list = await photoIndex.searchPhotos(text, 50)
    this.results = list
    console.info(`Query matched ${list.length} photos, cost ${Date.now() - start} ms`)
  } catch (err) {
    console.error('搜索失败: ' + JSON.stringify(err))
    this.results = []
  } finally {
    this.isSearching = false
    console.info('Render completed')
  }
}

真正关键的不是这个入口，而是 searchPhotos() 里面做了什么。我的做法是先把词标准化，然后多路召回：

function normalizeQuery(text: string): string[] {
  const source = text.trim().replace(/\s+/g, ' ')
  const terms = source.split(' ')
  const expandMap: Record<string, string[]> = {
    '大海': ['海边', '海滩', '海岸'],
    '落日': ['日落', '夕阳', '晚霞'],
    '毕业照': ['合照', '毕业合影']
  }

  const result: string[] = []
  terms.forEach(term => {
    result.push(term)
    if (expandMap[term]) {
      result.push(...expandMap[term])
    }
  })
  return Array.from(new Set(result))
}

这套做法的好处在于，它不会把搜索压死在“一个词必须完全一致”上。

比如用户输入“海边落日”，系统可以理解成：