using-mobile-native-capabilities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Mobile Native Capabilities

使用移动原生功能

The

lightning/mobileCapabilities

module exposes a set of factory functions that return service objects for native device features (barcode scanning, biometrics, location, etc.). Each service extends a common BaseCapability with an

isAvailable()

method, so an LWC can degrade gracefully on surfaces where the capability is not present (desktop, mobile web).

This skill routes an agent through (1) picking the right capability, (2) loading the authoritative type definitions, and (3) wiring the service into an LWC with the correct availability gating, error handling, and deprecation-aware API choice.

lightning/mobileCapabilities

模块提供了一组工厂函数，可返回针对设备原生功能（条形码扫描、生物识别、定位等）的服务对象。每个服务都继承自通用的BaseCapability，并包含

isAvailable()

方法，因此LWC可以在不支持该功能的环境（桌面端、移动网页）中优雅降级。

本技能会引导开发者完成以下步骤：(1) 选择合适的功能，(2) 加载权威的类型定义，(3) 将服务集成到LWC中，并实现正确的可用性校验、错误处理以及兼容弃用规则的API选择。

When to Use This Skill

何时使用本技能

User asks for an LWC that uses a device capability listed in the index below.
User mentions
```
lightning/mobileCapabilities
```
, "mobile capability", or "Nimbus" by name.
User wants to know which mobile native APIs are available, or which one fits their feature.

Do NOT use this skill for:

Mobile-offline review of an LWC (lwc:if, inline GraphQL, Komaci-priming violations) — use
```
reviewing-lwc-mobile-offline
```
.
Picking generic Lightning Base Components — use
```
using-lightning-base-components
```
.

用户请求开发使用以下索引中列出的设备功能的LWC时。
用户提及
```
lightning/mobileCapabilities
```
、"mobile capability"或"Nimbus"时。
用户想了解可用的移动原生API，或哪种API适合其功能需求时。

请勿将本技能用于：

LWC的移动离线评审（lwc:if、内联GraphQL、Komaci预检查违规）——请使用
```
reviewing-lwc-mobile-offline
```
技能。
选择通用Lightning基础组件——请使用
```
using-lightning-base-components
```
技能。

Prerequisites

前置条件

Knowledge that the LWC will run inside a supported mobile container (Salesforce Mobile App, Field Service Mobile App). These capabilities are unavailable on desktop and mobile web; gate every call behind
```
isAvailable()
```
.
Familiarity with the
```
lightning/mobileCapabilities
```
module declaration (see mobile-capabilities).

了解LWC将在受支持的移动容器（Salesforce移动应用、现场服务移动应用）中运行。这些功能在桌面端和移动网页中不可用；需在每次调用前通过
```
isAvailable()
```
进行校验。
熟悉
```
lightning/mobileCapabilities
```
模块的声明（详见mobile-capabilities）。

Capability Index

功能索引

Capability	Reference	One-line use
App Review	App Review	Prompt the user for a native in-app review.
AR Space Capture	AR Space Capture	Capture a 3D scan of a physical space using AR.
Barcode Scanner	Barcode Scanner	Read QR / UPC / EAN / Code-128 / etc. from the camera.
Biometrics	Biometrics	Authenticate via Face ID / fingerprint.
Calendar	Calendar	Read or create events on the device calendar.
Contacts	Contacts	Read or create entries in the device address book.
Document Scanner	Document Scanner	Scan paper documents using the camera with edge detection.
Geofencing	Geofencing	Trigger logic when the device crosses a geographic boundary.
Location	Location	Read GPS coordinates and watch for updates.
NFC	NFC	Read or write NFC tags.
Payments	Payments	Take an Apple Pay / Google Pay payment.

功能	参考文档	一句话用途
应用评分	App Review	提示用户进行原生应用内评分。
AR空间捕捉	AR Space Capture	使用AR技术捕捉物理空间的3D扫描数据。
条形码扫描	Barcode Scanner	通过摄像头读取QR/UPC/EAN/Code-128等格式的条形码。
生物识别	Biometrics	通过Face ID/指纹进行身份验证。
日历	Calendar	读取或创建设备日历中的事件。
联系人	Contacts	读取或创建设备通讯录中的条目。
文档扫描	Document Scanner	通过摄像头扫描纸质文档并进行边缘检测。
地理围栏	Geofencing	当设备跨越地理边界时触发逻辑。
定位	Location	读取GPS坐标并监听更新。
NFC	NFC	读取或写入NFC标签。
支付	Payments	处理Apple Pay/Google Pay支付。

Workflow

工作流程

Step 1 — Identify the capability

步骤1 — 确定所需功能

Map the user's feature ask to one row of the capability index. If the ask spans multiple capabilities (e.g. "scan a barcode and store it on a contact"), plan for each capability separately — there is one factory function per capability.

将用户的功能需求映射到功能索引中的对应条目。如果需求涉及多个功能（例如“扫描条形码并存储到联系人中”），请为每个功能分别规划——每个功能对应一个工厂函数。

Step 2 — Load the shared and capability-specific references

步骤2 — 加载通用和功能特定的参考文档

Read these two shared references once per session — they apply to every capability and are not duplicated in the per-capability files:

BaseCapability — the common interface with
```
isAvailable()
```
that every service extends.
mobile-capabilities — the
```
lightning/mobileCapabilities
```
module declaration showing every re-exported service.

Then open the capability's reference file from the table above. Each per-capability reference contains the service-specific TypeScript API (factory function, service interface, options types, result types, error types) and assumes the two shared references above are already in context.

Do not infer the API from memory — read it. The services evolve and some methods are explicitly

@deprecated

in favor of newer alternatives.

每个会话中需一次性阅读以下两份通用参考文档——它们适用于所有功能，不会在各功能的专属文档中重复：

BaseCapability — 所有服务都继承的通用接口，包含
```
isAvailable()
```
方法。
mobile-capabilities —
```
lightning/mobileCapabilities
```
模块的声明，展示了所有重新导出的服务。

然后打开上表中对应功能的参考文档。每份功能专属文档包含该服务特定的TypeScript API（工厂函数、服务接口、选项类型、结果类型、错误类型），并默认已了解上述两份通用参考文档的内容。

请勿凭记忆推断API——请查阅文档。服务会不断演进，部分方法已被明确标记为

@deprecated

，以推荐使用更新的替代方法。

Step 3 — Wire the service into the LWC

步骤3 — 将服务集成到LWC中

For each capability:

Import the factory from

lightning/mobileCapabilities

import { getBarcodeScanner } from 'lightning/mobileCapabilities';

Get an instance:
```
const scanner = getBarcodeScanner();
```

Gate the call behind

isAvailable()

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

Call the non-deprecated entry point. Several services keep older methods marked
```
@deprecated
```
alongside the recommended one — always prefer the recommended method in the reference.
Wrap the promise in
```
try/catch
```
and handle the typed failure codes the service exposes (e.g.
```
BarcodeScannerFailureCode
```
,
```
LocationServiceFailureCode
```
). User-cancelled vs. permission-denied vs. service-unavailable are distinct UX states.

针对每个功能：

从

lightning/mobileCapabilities

导入工厂函数：

import { getBarcodeScanner } from 'lightning/mobileCapabilities';

获取实例：
```
const scanner = getBarcodeScanner();
```

通过

isAvailable()

校验可用性：

if (!scanner.isAvailable()) {
  // 优雅降级或提示用户
  return;
}

调用非弃用的入口方法。部分服务会保留标记为
```
@deprecated
```
的旧方法，同时提供推荐的新方法——请始终使用参考文档中推荐的方法。
将Promise包裹在
```
try/catch
```
中，并处理服务暴露的类型化错误码（例如
```
BarcodeScannerFailureCode
```
、
```
LocationServiceFailureCode
```
）。用户取消、权限拒绝和服务不可用是不同的UX状态，需分别处理。

Step 4 — Surface failure modes to the user

步骤4 — 向用户展示错误状态

Each service defines its own failure-code enum. Translate codes into user-actionable messages: a

USER_DENIED_PERMISSION

should ask the user to grant permission; a

USER_DISABLED_PERMISSION

must direct them to the OS settings; a

SERVICE_NOT_ENABLED

should be a developer-visible error, not shown to the user.

每个服务都定义了自己的错误码枚举。请将错误码转换为用户可操作的提示信息：

USER_DENIED_PERMISSION

应提示用户授予权限；

USER_DISABLED_PERMISSION

必须引导用户前往系统设置；

SERVICE_NOT_ENABLED

应仅展示给开发者，不向普通用户显示。

Step 5 — Stay inside the supported surface

步骤5 — 仅在支持的环境中使用

Mobile capabilities are available only when the LWC runs inside a supported Salesforce mobile app. If the same component is rendered on desktop or mobile web, the factory will still return an object but

isAvailable()

will return

false

. Never assume availability — gate every call.

移动功能仅在LWC运行于受支持的Salesforce移动应用中时可用。如果同一组件在桌面端或移动网页中渲染，工厂函数仍会返回对象，但

isAvailable()

会返回

false

。请勿假设功能可用——每次调用前都必须进行校验。

Examples

示例

Example — "Scan a barcode and write it into a field"

示例 — "扫描条形码并写入字段"

Map to: Barcode Scanner.
Read Barcode Scanner.

Use

scan(options)

(not the deprecated

beginCapture

resumeCapture

endCapture

triple).

In options, set the
```
barcodeTypes
```
to the symbologies needed (default is all supported types) and
```
enableMultiScan: false
```
for a single read.
On resolve, write
```
result[0].value
```
to the bound field. On reject, inspect
```
error.code
```
against
```
BarcodeScannerFailureCode
```
.

对应功能：条形码扫描。
查阅Barcode Scanner文档。

使用

scan(options)

方法（而非已弃用的

beginCapture

resumeCapture

endCapture

组合）。

在选项中，将
```
barcodeTypes
```
设置为所需的条码格式（默认支持所有类型），并设置
```
enableMultiScan: false
```
以实现单次读取。
调用成功时，将
```
result[0].value
```
写入绑定字段；调用失败时，根据
```
BarcodeScannerFailureCode
```
枚举检查
```
error.code
```
。

Example — "Take an Apple Pay payment for an order total"

示例 — "针对订单总额发起Apple Pay支付"

Map to: Payments.
Read Payments.
Gate on
```
isAvailable()
```
.
Build the payment request object per the reference.
On resolve, surface the transaction id to the calling flow. On reject, handle user-cancelled and payment-failed paths separately.

对应功能：支付。
查阅Payments文档。
通过
```
isAvailable()
```
校验可用性。
根据参考文档构建支付请求对象。
调用成功时，向调用流程返回交易ID；调用失败时，分别处理用户取消和支付失败的场景。

Verification Checklist

验证清单

Every capability call is preceded by
```
isAvailable()
```
.
The non-deprecated entry point is used (no
```
beginCapture
```
/
```
resumeCapture
```
/
```
endCapture
```
for barcode, etc.).
Each rejection path is mapped to the typed failure code enum.
Imports come from
```
lightning/mobileCapabilities
```
, not from a private path.
No assumption that the capability runs on desktop or mobile web.

所有功能调用前都已通过
```
isAvailable()
```
校验。
使用了非弃用的入口方法（例如条形码功能未使用
```
beginCapture
```
/
```
resumeCapture
```
/
```
endCapture
```
）。
每个错误路径都已映射到对应的类型化错误码枚举。
导入来自
```
lightning/mobileCapabilities
```
，而非私有路径。
未假设功能可在桌面端或移动网页中运行。

Troubleshooting

故障排查

isAvailable()
returns
false
on a real device — the device is running an unsupported app surface (not Salesforce Mobile or Field Service Mobile), or the service is gated by an org-level setting. The fix is org configuration, not code.
TypeScript can't find the import — confirm the LWC has access to
```
lightning/mobileCapabilities
```
. The module is declared globally inside Salesforce mobile containers; outside that, the types must be installed separately.
Deprecated barcode methods still work — yes, but new code must use
```
scan()
```
and
```
dismiss()
```
. Refactor any sample code the agent received before returning it.
Multiple capabilities in one component — get separate instances per capability (they are independent service objects); do not try to share state between them.

真实设备上
isAvailable()
返回
false
——设备运行的是不支持的应用环境（非Salesforce移动应用或现场服务移动应用），或该功能受组织级设置限制。解决方案是配置组织设置，而非修改代码。
TypeScript无法找到导入——确认LWC可访问
```
lightning/mobileCapabilities
```
。该模块在Salesforce移动容器中全局声明；在容器外使用时，需单独安装类型定义。
已弃用的条形码方法仍可工作——是的，但新代码必须使用
```
scan()
```
和
```
dismiss()
```
。在返回示例代码前，请重构所有收到的旧代码。
单个组件中使用多个功能——为每个功能获取独立的实例（它们是独立的服务对象）；请勿尝试在它们之间共享状态。