mobile-platform-native-capabilities-integrate

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可以在不支持该功能的环境（桌面端、移动网页）中优雅降级。

此技能会引导Agent完成以下步骤：(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
```
mobile-platform-offline-validate
```
.
Picking generic Lightning Base Components — use
```
using-lightning-base-components
```
.

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

请勿将此技能用于：

LWC的移动离线检查（lwc:if、内联GraphQL、Komaci预检查违规）——请使用
```
mobile-platform-offline-validate
```
。
选择通用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移动应用、Field Service移动应用）中运行。这些功能在桌面端和移动网页中不可用；请在每次调用前通过
```
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.

Capability	Reference	一句话用途
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支付。

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。
阅读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。
阅读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移动应用或Field Service移动应用），或者该功能受到组织级设置的限制。解决方案是配置组织设置，而非修改代码。
TypeScript无法找到导入——确认LWC有权访问
```
lightning/mobileCapabilities
```
。该模块在Salesforce移动容器中全局声明；在容器外，必须单独安装类型定义。
废弃的条码方法仍可工作——是的，但新代码必须使用
```
scan()
```
和
```
dismiss()
```
。在返回给用户前，请重构Agent获取的任何示例代码。
一个组件中使用多个功能——为每个功能获取单独的实例（它们是独立的服务对象）；请勿尝试在它们之间共享状态。