一、把“复制成功”的定义收窄一点

相册的文搜图界面通常会显示关键词、图片内部 ID、所在位置和标签。当用户点击“复制关键词”时，最省事的实现是把整个查询对象序列化，直接扔进系统剪贴板。这样确实容易调试，但也把本来只属于应用内部的信息带了出去。另一个常被忽略的问题是：调用复制接口发生异常时，页面还显示了“复制成功”，用户到其他应用粘贴才发现没有内容。

这篇文章不讲语义检索的模型精度，也不重复讨论搜索请求乱序。我把关注点放在一次具体的导出事务：哪些字段允许离开应用、剪贴板写入失败后如何退回到用户可理解的操作。演示项目叫 ClipLens，页面为 ClipPage.ets，任务 CL-204，关键词是“海边日落”。业务源记录里还包含本地图像标识 IMG-0184 和本地上下文标记 local-only；真正的公开文本只有“海边日落”，字段数量 1/3。

这套数据是人为构造的，不含真实用户图片或定位信息。系统剪贴板不是应用的私有数据库，写入后有可能被其他应用在系统许可的范围内访问，所以不应该把调试标识和本地元数据混入公开字符串。图像相关业务更应克制：用户要的往往只是一个可搜索词，而不是整个图片对象。

二、复制源和公开文本用两种结构

ClipLens 把相册内记录与可分享文本分开。内部对象里可以存在 photoId、locationMark，但导出层只处理一组显式允许的字段。为什么采用白名单而不是逐项黑名单？因为图像检索业务经常扩展字段，新增标签、临时路径或模型调试信息时，黑名单很容易忘记更新，白名单默认不会向外扩张。

先看一个纯业务模型。ExportFilter 是应用自己实现的类，不是华为 SDK API。它只允许单个关键词，先去掉两端空格，再通过长度规则限制误操作；空内容直接拒绝，不触发任何系统剪贴板调用。画面中的“公开字段 1/3”指的是三个源字段中只允许一个对外，而不是识别准确率。

export interface ClipSource {
  keyword: string;
  photoId: string;
  locationMark: string;
}

export class ExportFilter {
  filterText(source: ClipSource): string {
    const value = source.keyword.trim();
    if (value.length === 0 || value.length > 24) {
      throw new Error('INVALID_PUBLIC_TEXT');
    }
    return value;
  }
}

const demoSource: ClipSource = {
  keyword: '海边日落',
  photoId: 'IMG-0184',
  locationMark: 'local-only'
};

这里只做最基本的文本过滤，不是完整脱敏系统。例如原始关键词本身就写着真实姓名或精确地址时，白名单也未必安全；真实业务需要根据数据来源、隐私分级和用户意图进一步确认。输入长度限制 24 是 Demo 自定义的“允许字符上限”，并非系统剪贴板要求。示意 HiLog 里的 size=24 指这一条配置上限，不能误读成“海边日落”在 UTF-8 下占用了 24 字节。

三、Pasteboard 只负责写，不替业务保证安全

华为的剪贴板指南给出了 pasteboard.createData、getSystemPasteboard 和异步 setData 的组合。它们解决的是如何把受支持的数据类型交给系统，并不会检查我们是否泄露了不该公开的字段。ClipLens 只构造 MIMETYPE_TEXT_PLAIN，不夹带 HTML、文件 URI 或图片地址，也没有通过系统读回接口做“成功校验”。

这里有两层考虑。第一层是减少写入对象的种类：只复制经审查的文本，预览内容与传入 createData 的内容相同。第二层是用 Promise 的完成与失败决定 UI 的反馈；点击按钮不等于写入成功。尤其从 API 12 开始，系统对剪贴板读取加强了权限约束，不能为了显示一个绿色勾，就擅自读取系统剪贴板并绕开系统隐私交互。

下面代码只解决系统写入这一步。setData 是官方接口，copyState、fallbackText 和过滤类都是 ClipLens 自己的页面状态。失败分支明确保留可手动处理的公开文本，而不自动重试无限次。

import { pasteboard } from '@kit.BasicServicesKit';

@State keyword: string = '海边日落';
@State taskId: string = 'CL-204';
@State copyState: string = 'IDLE';
@State fallbackText: string = '';
private filter: ExportFilter = new ExportFilter();

private async exportToClipboard(): Promise<void> {
  let publicText: string;
  try {
    publicText = this.filter.filterText(demoSource);
  } catch (error) {
    this.copyState = 'INVALID';
    return;
  }
  this.copyState = 'WRITING';
  try {
    const data = pasteboard.createData(
      pasteboard.MIMETYPE_TEXT_PLAIN, publicText);
    await pasteboard.getSystemPasteboard().setData(data);
    this.copyState = 'COPIED';
    console.info('[ClipLens] CL-204 state=COPIED');
  } catch (error) {
    this.copyState = 'FAILED';
    this.fallbackText = publicText;
    console.error('[ClipLens] CL-204 state=FAILED');
  }
}

成功状态只表示 setData 的 Promise 已完成，不是目标应用一定能粘贴，不保证后续系统剪贴板不会被其他内容覆盖。写入动作由用户主动点击发起，避免搜索联想每次变化就覆盖剪贴板。生产实现还需要针对按钮短时间重复点击做忙碌态处理，本例页面在 WRITING 期间不再接受第二次导出。

四、失败回退不是悄悄多复制一次

想象用户已经点了复制，但由于系统忙碌、数据冲突或其他运行环境原因，setData 返回失败。最差的做法有两种：一是继续显示绿色“完成”，二是自动连续重试，直到成功。前者误导用户，后者可能反复覆盖用户后来复制的内容。对于需要可预期行为的工具页面，失败时宁可把可公开文本保留在本页，展示“请手动选择复制”，也不强行承诺系统下一秒一定能接受。

在这个分支中，文本框只显示 fallbackText，内容已经通过同一条白名单规则。任何业务 ID 和上下文标记都不能进入回退区域。页面离开时，要清除仅用于展示的临时文本和忙碌状态；但不能随意清空系统剪贴板，否则会删除用户后来在其他应用复制的内容。剪贴板属于系统共享资源，页面自己的生命周期没有理由替全系统做清理。

下方用最小 UI 逻辑表示两种反馈。正常路径是预览“海边日落”与绿色 COPIED；异常路径则显示失败原因和可选中的公开文本。输入框只是提供用户主动选择的回退载体，不宣称可以替系统完成二次复制。

Column({ space: 12 }) {
  Text('导出预览：海边日落');
  if (this.copyState === 'COPIED') {
    Text('COPIED · 已提交到系统剪贴板');
  } else if (this.copyState === 'FAILED') {
    Text('写入失败，请手动选择下方公开文本');
    TextInput({ text: this.fallbackText })
      .width('100%');
  } else if (this.copyState === 'WRITING') {
    Text('正在写入，请稍候');
  }
  Button('复制公开文本')
    .enabled(this.copyState !== 'WRITING')
    .onClick(() => this.exportToClipboard());
}

对异步生命周期还要多做一次自查。若 setData 尚未完成用户就退出页面，Promise 仍可能返回，不能继续写旧页面的 @State。正式工程应在页面退出时把当前回调代次标记为无效，并阻止对已销毁组件的状态写回；这不意味着系统剪贴板操作自动取消，也不意味着已经复制的数据会自行消失。页面的 UI 有效期与系统调用完成时机是两件不同的事。

五、用一条固定演示链路核对文字和配图

本轮统一的示例顺序是：09:45:20，CL-204 计算允许导出的字段比例 1/3；09:45:22，系统写入在假定的成功路径下返回，随后状态进入 COPIED。模拟器里显示 CL-204、输入词“海边日落”、内部 IMG-0184 / local-only 不导出；纯手机页面展示相同的词、字段分组及 COPIED，不显示开发调试任务号，是刻意区分开发诊断数据与对用户展示的信息。

请注意，HiLog 的 setData=OK 是构造的成功演示文本，不是我实际运行应用后采集的日志。本地素材也没有连接系统剪贴板。真正测试时应分别构造空关键词、超过24字符的关键词、重复点击、应用退场、系统剪贴板冲突、目标应用无法粘贴等情况，记录“接口返回”“页面呈现”“目标应用能否读取”三个独立结论。不能仅凭 Toast 消失就推导复制成功。

项目边界也需要诚实写清：这里没有调用文搜图语义模型，检索结果中的图片 ID 与定位标记只是用于展示导出前后的字段隔离；图片、URI、HTML 等其他数据类型需要重新设计权限、序列化和目标端消费策略。尤其对图片文件 URI，不能把文件路径当成永久公开资源。单一纯文本例子无法直接替换复杂跨应用分享协议。

六、工程结论：兜底路径也要遵守公开字段契约

这次的重点不是教会 setData 的两行调用，而是把一次用户可见的“复制”拆成可验证的链路：源字段 → 白名单过滤 → 公开预览 → 异步系统写入 → 失败时的手动回退。当所有出口使用同一个 publicText，就不会出现正常写入删了内部 ID、异常回退却意外带出整个对象的问题。

如果以后把 ClipLens 接到真正的文本识图或检索服务，我会优先补三件事：公开字段分级审查、写入期间的重复触发控制、页面退出后的回调代次保护。它们都属于应用侧工程策略，不需要声称系统剪贴板提供了自动脱敏、跨设备强一致或写入回滚功能。文章中的代码基于已核对的官方 Pasteboard 接口组织，但没有进行 DevEco 编译、真实设备复制或跨应用粘贴测试，界面与日志全部属于示意。

参考资料：华为 HarmonyOS《使用剪贴板进行复制粘贴》（2025-03-17）；华为《长按复制地址》场景示例（2026-09-10）；华为《剪贴板错误码》参考。前者用于核对写入接口与 API 12 起的读取约束，后者用于理解可能出现的错误路径；它们不代表本 Demo 已完成系统调用验证。