!10063 docs: Update nfc controller api reference.cherrypick to 3.2 beta3

Merge pull request !10063 from 张秀平/cherry-pick-1664279939

!10063 docs: Update nfc controller api reference.cherrypick to 3.2 beta3
Merge pull request !10063 from 张秀平/cherry-pick-1664279939
87838d73 · openharmony_ci · Gitee · 092ab09d · f2461155 · 87838d73
2 changed file
--- a/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md
 # 标准NFC-cardEmulation
-本模块主要用于操作及管理NFC卡模拟。
+本模块主要提供NFC卡模拟业务，包括判断支持哪种卡模拟类型，HCE卡模拟的业务实现等。
 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
 > 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
@@ -12,30 +12,49 @@
 import cardEmulation from '@ohos.nfc.cardEmulation';
 ```
+## FeatureType
+定义不同的NFC卡模拟类型。
+**系统能力**：SystemCapability.Communication.NFC.Core
+| 名称 | 默认值 | 说明 |
+| -------- | -------- | -------- |
+| HCE | 0 | HCE 卡模拟。 |
+| UICC | 1 | SIM 卡模拟。 |
+| ESE | 2      | ESE卡模拟。 |
 ## cardEmulation.isSupported
 isSupported(feature: number): boolean
-是否支持某种类型的卡模拟
+是否支持某种类型的卡模拟。
+**需要权限**：ohos.permission.NFC_CARD_EMULATION
 **系统能力**：SystemCapability.Communication.NFC.Core
+**参数：**
+| 参数名  | 类型     | 必填 | 说明                    |
+| ------- | -------- | ---- | ----------------------- |
+| feature | number | 是   | 卡模拟类型值，详细请见[FeatureType](#featuretype)枚举值。 |
 **返回值：**
  | **类型** | **说明** |
  | -------- | -------- |
-  | boolean | true:支持该类型卡模拟，&nbsp;false:不支持该类型卡模拟。 |
+  | boolean | true: 支持该类型卡模拟，&nbsp;false: 不支持该类型卡模拟。 |
 ## HceService<sup>8+</sup>
-管理HCE卡模拟。在调用HceService的接口前，需要先通过new cardEmulation.HceService()创建实例。
+提供HCE卡模拟的实现，主要包括接收对端读卡设备的APDU数据，并响应APDU数据到对端读卡设备。使用HCE相关接口前，必须先判断设备是否支持HCE卡模拟能力。
 ### startHCE<sup>8+</sup>
 startHCE(aidList: string[]): boolean
-开始使用HCE能力。
+启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。
 **需要权限**：ohos.permission.NFC_CARD_EMULATION
@@ -45,13 +64,13 @@ startHCE(aidList: string[]): boolean
 | 参数名  | 类型     | 必填 | 说明                    |
 | ------- | -------- | ---- | ----------------------- |
-| aidList | string[] | 是   | 注册进行卡模拟的aid列表 |
+| aidList | string[] | 是   | 动态注册卡模拟的AID列表。 |
 ### stopHCE<sup>8+</sup>
 stopHCE(): boolean
-停止使用HCE能力。
+停止HCE业务功能。包括退出当前应用前台优先，释放动态注册的AID列表。
 **需要权限**：ohos.permission.NFC_CARD_EMULATION
@@ -61,7 +80,7 @@ stopHCE(): boolean
 on(type: "hceCmd", callback: AsyncCallback<number[]>): void;
-在startHCE后，订阅对端设备消息。
+订阅回调，用于接收对端读卡设备发送的APDU数据。
 **需要权限**：ohos.permission.NFC_CARD_EMULATION
@@ -71,14 +90,14 @@ on(type: "hceCmd", callback: AsyncCallback<number[]>): void;
 | 参数名   | 类型                    | 必填 | 说明                                         |
 | -------- | ----------------------- | ---- | -------------------------------------------- |
-| type     | string                  | 是   | 固定填"hceCmd"字符串                         |
+| type     | string                  | 是   | 固定填"hceCmd"字符串。                         |
-| callback | AsyncCallback<number[]> | 是   | 订阅的事件回调，入参是符合APDU协议的数据数组 |
+| callback | AsyncCallback<number[]> | 是   | 订阅的事件回调，入参是符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 |
 ### sendResponse<sup>8+</sup>
 sendResponse(responseApdu: number[]): void;
-发送数据到对端设备。
+发送APDU数据到对端读卡设备。
 **需要权限**：ohos.permission.NFC_CARD_EMULATION
@@ -88,16 +107,25 @@ sendResponse(responseApdu: number[]): void;
 | 参数名       | 类型     | 必填 | 说明                                               |
 | ------------ | -------- | ---- | -------------------------------------------------- |
-| responseApdu | number[] | 是   | 准备发送到对端的数据，入参是符合APDU协议的数据数组 |
+| responseApdu | number[] | 是   | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 |
 **示例：**
 ```js
+import cardEmulation from '@ohos.nfc.cardEmulation';
+var isHceSupported = cardEmulation.isSupported(cardEmulation.FeatureType.HCE);
+if (!isHceSupported) {
+    console.log('this device is not supported for HCE, ignore it.');
+    return;
+}
+// device supports HCE, transimit APDU with remote nfc reader.
 var hceService = new cardEmulation.HceService();
 hceService.startHCE([
    "F0010203040506", "A0000000041010"
-])
+]);
-hceService.stopHCE();
 hceService.on("hceCmd", (err, res) => {
    if(err.data === 0) {
        console.log('callback => Operation hceCmd succeeded. Data: ' + JSON.stringify(res));
@@ -108,16 +136,8 @@ hceService.on("hceCmd", (err, res) => {
        console.log('callback => Operation hceCmd failed. Cause: ' + err.data);
    }
 })
-```
-## FeatureType
-表示NFC支持的卡模拟类型枚举。
+// stop HCE when the application exit the nfc card emulation.
+hceService.stopHCE();
-**系统能力**：SystemCapability.Communication.NFC.Core
+```
-| 名称 | 默认值 | 说明 |
-| -------- | -------- | -------- |
-| HCE | 0 | 该常量用于检查是否支持 HCE 卡模拟。 |
-| UICC | 1 | 该常量用于检查是否支持 SIM 卡模拟。 |
-| ESE | 2      | 该常量用于检查是否支持ESE卡模拟。 |
--- a/zh-cn/application-dev/reference/apis/js-apis-nfcController.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-nfcController.md
 # 标准NFC
-本模块主要用于操作及管理NFC。
+本模块主要用于管理NFC状态，包括打开和关闭NFC，读取NFC的状态等。
 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
 > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
@@ -12,12 +12,24 @@
 import controller from '@ohos.nfc.controller';
 ```
+## NfcState
+定义不同的NFC状态值。
+**系统能力**：SystemCapability.Communication.NFC.Core
+| 名称 | 默认值 | 说明 |
+| -------- | -------- | -------- |
+| STATE_OFF | 1 | NFC已关闭状态。 |
+| STATE_TURNING_ON | 2 | NFC正在打开状态。 |
+| STATE_ON | 3      | NFC已打开状态。 |
+| STATE_TURNING_OFF | 4      | NFC正在关闭状态。 |
 ## controller.isNfcAvailable
 isNfcAvailable(): boolean
-查询是否有NFC功能
+查询设备是否有NFC能力。
 **系统能力**：SystemCapability.Communication.NFC.Core
@@ -25,7 +37,7 @@ isNfcAvailable(): boolean
 | **类型** | **说明** |
 | -------- | -------- |
-| boolean | true:有NFC功能，&nbsp;false:无NFC功能。 |
+| boolean | true: 设备具备NFC能力，&nbsp;false: 设备不具备NFC能力。 |
 ## controller.openNfc
@@ -42,7 +54,7 @@ openNfc(): boolean
 | **类型** | **说明** |
 | -------- | -------- |
-| boolean | true:打开NFC成功，&nbsp;false:打开NFC失败。 |
+| boolean | true: 打开NFC成功，&nbsp;false: 打开NFC失败。 |
 ## controller.closeNfc
@@ -58,7 +70,7 @@ closeNfc(): boolean
 | **类型** | **说明**                                    |
 | -------- | ------------------------------------------- |
-| boolean  | true:关闭NFC成功，&nbsp;false:关闭NFC失败。 |
+| boolean  | true: 关闭NFC成功，&nbsp;false: 关闭NFC失败。 |
 ## controller.isNfcOpen
@@ -72,11 +84,11 @@ isNfcOpen(): boolean
 | **类型** | **说明**                            |
 | -------- | ----------------------------------- |
-| boolean  | true:NFC打开，&nbsp;false:NFC关闭。 |
+| boolean  | true: NFC是打开的，&nbsp;false: NFC是关闭的。 |
 ## controller.getNfcState
-getNfcState(): NfcState
+getNfcState(): [NfcState](#nfcstate)
 查询NFC状态。
@@ -86,13 +98,13 @@ getNfcState(): NfcState
 | **类型** | **说明**               |
 | -------- | ---------------------- |
-| NfcState | 详细请见NfcState枚举值 |
+| [NfcState](#nfcstate) | NFC状态值，详细请见[NfcState](#nfcstate)枚举值。 |
 ## controller.on('nfcStateChange')
-on(type: "nfcStateChange", callback: Callback&lt;NfcState&gt;): void
+on(type: "nfcStateChange", callback: Callback&lt;[NfcState](#nfcstate)&gt;): void
-注册NFC开关状态事件。
+注册NFC开关状态事件，通过Callback方式获取NFC状态的变化通知。
 **系统能力**：SystemCapability.Communication.NFC.Core
@@ -100,16 +112,16 @@ on(type: "nfcStateChange", callback: Callback&lt;NfcState&gt;): void
  | **参数名** | **类型** | **必填** | **说明** |
  | -------- | -------- | -------- | -------- |
-  | type | string | 是 | 固定填"nfcStateChange"字符串 |
+  | type | string | 是 | 固定填"nfcStateChange"字符串。 |
-  | callback | Callback&lt;NfcState&gt; | 是 | 状态改变回调函数。 |
+  | callback | Callback&lt;[NfcState](#nfcstate)&gt; | 是 | NFC状态改变通知的回调函数。 |
 ## controller.off('nfcStateChange')
-off(type: "nfcStateChange", callback?: Callback&lt;NfcState&gt;): void
+off(type: "nfcStateChange", callback?: Callback&lt;[NfcState](#nfcstate)&gt;): void
-取消NFC开关状态事件的注册。
+取消NFC开关状态事件的注册，取消后NFC状态变化时，就不会再收到Callback的通知。
 **系统能力**：SystemCapability.Communication.NFC.Core
@@ -117,36 +129,38 @@ off(type: "nfcStateChange", callback?: Callback&lt;NfcState&gt;): void
  | **参数名** | **类型** | **必填** | **说明** |
  | -------- | -------- | -------- | -------- |
-  | type | string | 是 | 固定填"nfcStateChange"字符串 |
+  | type | string | 是 | 固定填"nfcStateChange"字符串。 |
-| callback | Callback&lt;NfcState&gt; | 否 | 状态改变回调函数。如果callback不填，将“去注册”该事件关联的所有回调函数。 |
+| callback | Callback&lt;[NfcState](#nfcstate)&gt; | 否 | NFC状态改变回调函数，可以空缺不填。 |
 **示例**
  ```js
-  import nfcController from '@ohos.nfcController';
+  import controller from '@ohos.nfc.controller';
-  var NFC_STATE_NOTIFY = "nfcStateChange";
+  // callback key definition
+  var NFC_STATE_CALLBACK_KEY = "nfcStateChange";
-  var recvNfcStateNotifyFunc = result => {
-      console.info("nfc state receive state: " + result);
+  // register callback to receive the nfc state changed notification
+  controller.on(NFC_STATE_CALLBACK_KEY, (err, nfcState)=> {
+    if (err) {
+        console.log("controller on callback err: " + err);
+    } else {
+        console.log("controller on callback nfcState: " + nfcState);
+    }
+  });
+  // open nfc, require permission: ohos.permission.MANAGE_SECURE_SETTINGS
+  if (!controller.isNfcOpen()) {
+    var ret = controller.openNfc();
+    console.log("controller openNfc ret: " + ret);
  }
-  // 注册事件
-  nfcController.on(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc);
-  // 解注册事件
-  nfcController.off(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc);
-  ```
-## NfcState
-表示NFC状态的枚举。
-**系统能力**：SystemCapability.Communication.NFC.Core
+  // close nfc, require permission: ohos.permission.MANAGE_SECURE_SETTINGS
+  if (controller.isNfcOpen()) {
+    var ret = controller.closeNfc();
+    console.log("controller closeNfc ret: " + ret);
+  }
-| 名称 | 默认值 | 说明 |
+  // unregister callback
-| -------- | -------- | -------- |
+  controller.off(NFC_STATE_CALLBACK_KEY);
-| STATE_OFF | 1 | NFC关闭状态 |
+  ```
-| STATE_TURNING_ON | 2 | NFC正在打开状态 |
-| STATE_ON | 3      | NFC打开状态 |
-| STATE_TURNING_OFF | 4      | NFC正在关闭状态 |