用户说“从相册导入几张照片，之后能用文字找到”，听起来像一条简单的按钮流程。但图库选择、照片去重和语义索引其实是三道不同的边界。图库选择器负责把用户明确选中的资源交给应用；导入层负责判定哪些资源已经接收；真正的文搜图还需要标签或者模型产生可检索的语义特征。把这三步糊成一个“导入成功”，等到用户点撤销、重复导入或者退出页面，状态就很难解释。这里做一个范围刻意收窄的 Demo，名称为 PickerQueue，页面叫 ImportQueuePage。本轮导入编号 PQ-041，演示图库返回 2 个 URI，其中 1 个在本地队列已有映射，新接收 1 个，结果为 picked=2 / added=1 / duplicate=1，阶段 WAIT_INDEX。这组数值是方便复核的固定模拟输入，不声称是系统图库真实运行记录；后续模型推理不在本文实现范围内。## 一、先限定选择器的责任官方 Media Library Kit 的 photoAccessHelper.PhotoViewPicker 能让应用通过系统选择界面取得用户挑选资源的 URI。它不意味着应用获得了读取整座相册的通行证，也不应该为了做“单次选图”就在清单里申请全库读取权限。用户授权的是本次选择行为，拿到 URI 后，应用仍要考虑可访问时效、异常、文件迁移以及后续处理时是否需要复制到自己的沙箱。对于文搜图应用，这一点尤其重要。很多产品会在首次启动时展示一个空搜索框，用户以为点击“添加图片”后立刻能够使用自然语言检索。实际情况是，选中照片与完成索引之间可能隔着解码、缩略图生成、标签提取、嵌入计算和存储事务。即使页面已经出现缩略图，也只能说明某个展示路径有数据，不等于后台索引已可查询。本文不设计新的模型 API，而是把导入层做成一个可验证的接口契约：选择器交付 URI 列表；导入器基于当前队列形成接收计划；用户可以撤销尚未提交的批次；索引完成后另一个模块再回填可搜索状态。这样后续更换模型时，不需要改动图库访问协议。### 1. 用批次计划替代“选完就写数据库”第一个代码片段只处理纯 ArkTS 数据，不依赖系统相册。existingUris 代表当前会话中已经接收的资源标识，planImport 不修改它；先获得计划，再决定是否提交。这里选择 URI 判重，是一个保守而低成本的演示规则，并不是内容哈希判重。ts// common/ImportPlan.ets：生成可撤销的导入计划export interface ImportPlan { batchId: string; picked: number; added: string[]; duplicates: number;}export function planImport( batchId: string, pickedUris: string[], existingUris: string[]): ImportPlan { const seen: Set<string> = new Set<string>(existingUris); const added: string[] = []; let duplicates: number = 0; for (const uri of pickedUris) { if (seen.has(uri)) { duplicates += 1; continue; } seen.add(uri); added.push(uri); } return { batchId, picked: pickedUris.length, added, duplicates };}````seen` 会在本次循环中更新，所以即使返回数组自身出现重复项，也不会向新增队列插入两份。更常见的场景是某张旧照片在两次选择中被再次选中。不过 URI 可能随授权范围、资源位置或提供方式变化；同一张图也可能有不同 URI。因此这里的“重复”只能解释为当前策略下的 URI 重复，不是文件内容完全一致。正式版需要在有权读取并复制文件后，再计算内容指纹，同时控制大图哈希的内存与耗时。## 二、选择器可以等待，业务世代号不能丢真正麻烦的不是用户没有选图片，而是点击“添加图片”以后立刻按了“撤销本次”，系统选择界面随后才返回。若回调里不做任何代际判断，刚被撤销的导入就可能重新写回页面。我们不能假设应用能通过一个自定义按钮关闭所有系统对话框；更可靠的是让迟到结果失去提交资格。接下来把系统 picker 接进页面。官方示例采用 `photoAccessHelper.PhotoSelectOptions`、`PhotoViewMIMETypes.IMAGE_TYPE`、`PhotoViewPicker.select()` 和 `PhotoSelectResult.photoUris`。为了使示例尽量独立，这里直接导入 Media Library Kit，不使用未经核实的第三方选择器。代码中的异常分支只更新 UI 状态，不把用户取消选图当作应用崩溃。ts// pages/ImportQueuePage.ets：系统图库选择和批次世代门禁import { photoAccessHelper } from ‘@kit.MediaLibraryKit’;import { BusinessError } from ‘@kit.BasicServicesKit’;import { planImport, ImportPlan } from ‘…/common/ImportPlan’;@Entry@Componentstruct ImportQueuePage { @State stage: string = ‘IDLE’; @State batchId: string = ‘PQ-041’; @State picked: number = 0; @State added: number = 0; @State duplicates: number = 0; private generation: number = 0; private savedUris: string[] = []; // Demo 已接收队列；实际请持久化 async pickPhotos(): Promise { const token = ++this.generation; this.stage = ‘PICKING’; const options = new photoAccessHelper.PhotoSelectOptions(); options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; options.maxSelectNumber = 9; try { const picker = new photoAccessHelper.PhotoViewPicker(); const result: photoAccessHelper.PhotoSelectResult = await picker.select(options); if (token !== this.generation) { return; } // 撤销后的迟到结果无效 const plan: ImportPlan = planImport(this.batchId, result.photoUris, this.savedUris); this.picked = plan.picked; this.added = plan.added.length; this.duplicates = plan.duplicates; this.stage = ‘WAIT_INDEX’; // 这里并未启动语义模型 } catch (err) { if (token !== this.generation) { return; } const e = err as BusinessError; this.stage = ‘IDLE’; console.error(PickerQueue select failed: ${e.code}); } } build() { Column({ space: 12 }) { Text(‘PickerQueue’).fontSize(26) Text(批次 ${this.batchId} · ${this.stage}) Button(‘添加图片’).onClick(() => { this.pickPhotos(); }) Button(‘撤销本次’).onClick(() => { this.generation += 1; this.stage = ‘IDLE’; }) Text(选择 ${this.picked} / 新增 ${this.added} / 重复 ${this.duplicates}) }.padding(20).width(‘100%’) }}这里故意没有在 `pickPhotos()` 末尾立即修改 `savedUris`，因为下一步应当提供用户确认和持久化事务。如果简单地在收到结果时写入本地索引，撤销按钮只清空可见数字，后台文件仍可能留下。这份示例的“撤销”是撤销未提交计划，不是删除已经入库的所有文件。`generation` 是应用自己的整数，不是 Media Library Kit 的任务 ID；它只用于忽略迟到返回，不能中断系统 picker，也不能替代数据库事务。![](https://i-blog.csdnimg.cn/direct/ca492cf2e93844e188f9ae34288bc25e.png)这张 DevEco 风格图按约定展示 `ImportQueuePage.ets` 中的 `pickPhotos`、`generation` 和 `WAIT_INDEX`。底部对应的演示日志为 `PickerQueue PQ-041 picked=2 added=1 duplicate=1 state=WAIT_INDEX`，它代表用固定夹具推导的状态，不是图库授权完成的实测证据。图中右侧是导入队列页面，实际 App 可以选择网格或列表，只要数据含义一致即可。## 三、先画一张状态表，再决定怎么展示照片假设队列里已有照片 `PIC-041`，其 URI 记为 `uri-A`；选择器本次返回 `[uri-A, uri-B]`。`planImport()` 给出的计划应是：收到 2 条，URI 命中重复 1 条，新增 URI `uri-B` 一条；新增记录可以在提交时分配 `PIC-042`。如果 UI 显示“本轮新增 2 条”，说明它跳过了已有队列。如果 UI 一直停在“处理中”，要确认是否把计划等待索引的 `WAIT_INDEX` 当成推理中的 `RUNNING`。这里把视觉展示与实际提交分开。`PIC-041` 是已存在的队列条目，`PIC-042` 是拟加入的条目；两张卡片都可显示缩略图，但“可搜索”只应该由索引模块在提交成功后设置。用户不应该因为看到了照片缩略图，就被告知“语义索引已完成”。在本文的演示页面上，状态显示“待索引”，不是百分比进度，也没有虚构完成耗时。如果用户在选择器返回前点“撤销本次”，递增 `generation` 之后，无论结果随后成功还是失败，只要 token 不一致，当前方法都不应提交它。若撤销发生在计划生成之后、实际持久化之前，就应该丢弃该计划；若已经写入沙箱和数据库，则需使用独立的回滚流程清理新增记录，不能依赖简单的 `generation` 自增完成。这个时序区别建议在调试日志里明确记录。![](https://i-blog.csdnimg.cn/direct/c4e3c39b6f1c45ecb75e7253966f9d99.png)手机演示图展示批次 `PQ-041` 和状态 `WAIT_INDEX`：本轮选择 2、新增 1、重复 1，下方标出已存在的 `PIC-041` 与待接收的 `PIC-042`。它使用的是演示图块而非用户私人相册，顶部状态栏也不是来自真机系统。它重点解释“已经进入导入队列，但没有完成文搜图索引”，和开发界面里的选择器代码相互补充。### 1. 一段可直接加入单元测试的纯函数夹具测试没有必要每次都拉起真实图库。先用纯函数让边界结果可重复，再留一个平台集成用例检查 picker 的权限与返回行为。下列夹具刻意使用占位 URI：它们仅用于业务算法测试，不能交给系统文件接口读取。ts// test/ImportPlanCase.ets：纯业务示意断言，不读用户照片import { planImport, ImportPlan } from ‘…/common/ImportPlan’;const planned: ImportPlan = planImport( ‘PQ-041’, [‘uri-A’, ‘uri-B’], [‘uri-A’]);if (planned.picked !== 2 || planned.added.length !== 1 || planned.duplicates !== 1 || planned.added[0] !== ‘uri-B’) { throw new Error(‘PQ-041 fixture mismatch’);}console.info(‘PickerQueue PQ-041 picked=2 added=1 duplicate=1 state=WAIT_INDEX’);```这段代码只有一个可验证的推断：传入这三个字符串时，计数应该如此。它没有验证 Picker 是否能在目标设备拉起，也无法验证沙箱 URI 的后续读权限。把两类测试拆开有实际好处：业务去重失败时，不会把问题错误归因于用户相册授权；平台接口失败时，也能看见纯函数层是否仍满足预期。## 四、入口、撤销与索引三条路需要各自兜底导入完成以后，工程还欠三件事。第一，正式使用时应把选择器得到的可读资源按平台推荐方式安全地复制到应用沙箱，处理 URI 不可达、文件损坏、存储空间不足和重复提交。第二，队列提交需要持久化事务，给每张照片分配本地 ID，记录 URI 与内容指纹策略，避免应用被杀后出现“界面显示已导入，索引却没有条目”。第三，要在索引后台任务里增加取消和恢复协议，明确推理中、索引已完成、索引失败等状态。本文没有使用未经证实的语义模型 API，因此不把 WAIT_INDEX 写成搜索成功。还要避免一个权限误区：选择器模式下可以针对用户选择的资源开展访问，不代表拥有后台遍历全相册的权限。若产品需求升级为持续扫描、跨会话访问或者读取其他照片，需要重新评估授权方式、隐私说明与平台允许的权限路径。PhotoViewPicker 的返回值是资源入口，不等于对文件生命周期和所有读写操作的永久承诺。一个可执行的测试清单是：取消系统选择器、不选图片返回、重复选择旧资源、一次选择多张、快速点两次添加、选择后立刻撤销、页面退出再返回，以及异常 URI 读取失败。每条都应观察批次号、世代号、已有 URI 集合和索引提交记录。不能仅凭“成功弹出系统图库”判断文搜图导入链路已经做完。PickerQueue 这次的结论因此刻意克制：先把批次视为可撤销计划，用 URI 做会话级去重，用状态标签坦白区分“选择完成”和“语义索引可用”。这种设计不会解决所有检索质量问题，却能让接下来真正接入嵌入模型、图像标签和本地向量库时，数据出处与撤销语义都可以追溯。官方依据：- PhotoViewPicker 选取图片示例：https://developer.huawei.com/consumer/cn/doc/doccenter-dev-faq/faqs-arkui-688- Media Library Kit 中 PhotoPicker 访问：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-v5/component-guidelines-photoviewpicker-V5- 官方云存储文档中的 PhotoViewPicker 与沙箱复制示例：https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/cloudfoundation-storage-upload-file> 说明：文内图库返回值、条目 ID、批次、日志和配图均为模拟素材；本文不宣称完成 DevEco Studio 编译、真机相册读取、模型推理或者审核实测。