mobile-platform-native-capabilities-integrate

使用移动原生功能

lightning/mobileCapabilities 模块提供一组工厂函数，用于返回原生设备功能（条码扫描、生物识别、位置等）的服务对象。每项服务都扩展了通用的 BaseCapability，并提供 isAvailable() 方法，因此 LWC 可以在不支持该功能的平台（桌面端、移动 Web）上优雅降级。

本技能会引导 Agent 完成以下步骤：(1) 选择合适的功能；(2) 加载权威类型定义；(3) 将服务接入 LWC，并正确处理可用性判断、错误处理以及弃用感知的 API 选择。

使用本技能的时机

• 用户要求创建使用下方索引中某项设备功能的 LWC。
• 用户提到 lightning/mobileCapabilities、“移动功能”或“Nimbus”。
• 用户想了解有哪些移动原生 API 可用，或想知道哪项 API 适合其功能需求。

以下情况不要使用本技能：

• 对 LWC 进行移动离线审查（lwc:if、内联 GraphQL、Komaci 预热违规）——请使用 mobile-platform-offline-validate。
• 选择或设置通用 Lightning 基础组件 / SLDS 蓝图的样式——请使用 design-systems-slds-apply。

前提条件

• 确认 LWC 将在受支持的移动容器（Salesforce Mobile App、Field Service Mobile App）中运行。这些功能在桌面端和移动 Web 上不可用；每次调用前都必须通过 isAvailable() 进行判断。
• 熟悉 lightning/mobileCapabilities 模块声明（请参阅 mobile-capabilities）。

功能索引

功能	参考文档	用途简介
应用评价	应用评价	提示用户为原生应用内体验撰写评价。
AR 空间采集	AR 空间采集	使用 AR 对实体空间进行 3D 扫描。
条码扫描器	条码扫描器	使用摄像头读取 QR / UPC / EAN / Code-128 等码。
生物识别	生物识别	通过 Face ID / 指纹进行身份验证。
日历	日历	读取或在设备日历中创建事件。
联系人	联系人	读取或在设备通讯录中创建条目。
文档扫描器	文档扫描器	使用摄像头扫描纸质文档并检测边缘。
地理围栏	地理围栏	在设备跨越地理边界时触发逻辑。
位置	位置	读取 GPS 坐标并监听更新。
NFC	NFC	读取或写入 NFC 标签。
支付	支付	使用 Apple Pay / Google Pay 收款。

工作流

步骤 1 — 确定功能

将用户提出的功能需求对应到功能索引中的一行。如果需求涉及多个功能（例如“扫描条码并将其保存到联系人”），则分别规划每项功能——每项功能都有一个工厂函数。

步骤 2 — 加载共享参考和特定能力的参考

在每个会话中只需阅读以下两个共享参考一次——它们适用于所有能力，不会在各能力文件中重复：

• BaseCapability — 包含 isAvailable() 的通用接口，每项服务都会扩展该接口。
• mobile-capabilities — lightning/mobileCapabilities 模块声明，展示所有重新导出的服务。

然后，打开上表中对应能力的参考文件。每份特定能力参考都包含该服务专属的 TypeScript API（工厂函数、服务接口、选项类型、结果类型、错误类型），并假设上述两个共享参考已在上下文中。

不要凭记忆推断 API——请阅读参考文件。服务会不断演进，某些方法已明确标记为 @deprecated，并建议改用更新的替代方法。

步骤 3 — 在 LWC 中接入服务

对于每项能力：

1. 从 lightning/mobileCapabilities 导入工厂函数：

   import { getBarcodeScanner } from 'lightning/mobileCapabilities';
   

2. 获取实例：const scanner = getBarcodeScanner();
3. 在调用前通过 isAvailable() 进行检查：

   if (!scanner.isAvailable()) {
     // graceful fallback or user message
     return;
   }
   

4. 调用未弃用的入口点。多个服务会将旧方法标记为 @deprecated，同时提供推荐方法——请始终优先使用参考文件中的推荐方法。
5. 使用 try/catch 包装 Promise，并处理服务提供的类型化失败代码（例如 BarcodeScannerFailureCode、LocationServiceFailureCode）。用户取消、权限被拒绝和服务不可用是不同的 UX 状态。

步骤 4 — 向用户展示失败情况

每项服务都定义了自己的失败代码枚举。请将代码转换为用户可采取行动的提示：对于 USER_DENIED_PERMISSION，应提示用户授予权限；对于 USER_DISABLED_PERMISSION，必须引导用户前往 OS 设置；对于 SERVICE_NOT_ENABLED，应将其作为开发者可见错误，而不是展示给用户。

步骤 5 — 仅使用受支持的功能

只有当 LWC 在受支持的 Salesforce 移动应用内运行时，才能使用移动能力。如果同一组件在桌面端或移动 Web 中呈现，工厂仍会返回对象，但 isAvailable() 会返回 false。切勿假定功能可用——每次调用前都要进行检查。

示例

示例 —“扫描条形码并将其写入字段”

1. 对应能力：条形码扫描器。
2. 阅读 Barcode Scanner。
3. 使用 scan(options)（不要使用已弃用的 beginCapture / resumeCapture / endCapture 方法组合）。
4. 在选项中，将 barcodeTypes 设置为所需的条码制式（默认值为所有受支持的类型），并将 enableMultiScan: false 设为单次读取。
5. 成功时，将 result[0].value 写入绑定字段。失败时，根据 BarcodeScannerFailureCode 检查 error.code。

示例 —“为订单总额收取 Apple Pay 付款”

1. 对应能力：Payments。
2. 阅读 Payments。
3. 通过 isAvailable() 进行检查。
4. 按照参考文件构建付款请求对象。
5. 成功时，将交易 ID 呈现给调用流程。失败时，分别处理用户取消和付款失败的情况。

验证清单

• 每次调用能力前都先检查 isAvailable()。
• 使用未弃用的入口点（条形码扫描不要使用 beginCapture / resumeCapture / endCapture 等方法）。
• 每条拒绝路径都映射到类型化失败代码枚举。
• 导入来源为 lightning/mobileCapabilities，而非私有路径。
• 不假定该能力可在桌面端或移动 Web 中运行。

故障排除

• 在真实设备上，isAvailable() 返回 false — 设备运行的是不受支持的应用界面（不是 Salesforce Mobile 或 Field Service Mobile），或者该服务受组织级设置限制。解决方法是配置组织，而不是修改代码。
• TypeScript 找不到导入项 — 确认 LWC 可以访问 lightning/mobileCapabilities。在 Salesforce 移动容器中，该模块是全局声明的；在其他环境中，必须单独安装类型定义。
• 已弃用的条码方法仍然可用 — 是的，但新代码必须使用 scan() 和 dismiss()。在返回 Agent 收到的任何示例代码前，都要先重构。
• 在一个组件中使用多项功能 — 为每项功能分别获取实例（它们是彼此独立的服务对象）；不要尝试在它们之间共享状态。