using-mobile-native-capabilities

使用移动端原生功能

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

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

何时使用此技能

• 用户要求编写使用下方索引中列出的设备功能的 LWC。
• 用户提到 lightning/mobileCapabilities、“移动功能”或“Nimbus”。
• 用户想了解有哪些移动端原生 API，或哪种 API 适合其功能需求。

请勿在以下情况下使用此技能：

• 对 LWC 进行移动端离线审查（lwc:if、内联 GraphQL、Komaci 预加载违规）——请使用 reviewing-lwc-mobile-offline。
• 选择通用 Lightning 基础组件——请使用 using-lightning-base-components。

前提条件

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

功能索引

功能	参考资料	用途简介
App Review	App Review	提示用户撰写原生应用内评价。
AR Space Capture	AR Space Capture	使用 AR 捕获实体空间的 3D 扫描。
Barcode Scanner	Barcode Scanner	使用相机读取 QR / UPC / EAN / Code-128 等码。
Biometrics	Biometrics	通过 Face ID / 指纹进行身份验证。
Calendar	Calendar	读取或创建设备日历中的事件。
Contacts	Contacts	读取或创建设备通讯录中的条目。
Document Scanner	Document Scanner	使用相机和边缘检测扫描纸质文档。
Geofencing	Geofencing	当设备越过地理边界时触发逻辑。
Location	Location	读取 GPS 坐标并监视位置更新。
NFC	NFC	读取或写入 NFC 标签。
Payments	Payments	使用 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 收到的任何示例代码前，都要先重构。
• 在一个组件中使用多项功能 — 为每项功能分别获取实例（它们是彼此独立的服务对象）；不要尝试在它们之间共享状态。