From f0a2ab72c35befb440186056b1959b2fb2e1a603 Mon Sep 17 00:00:00 2001 From: liangzhenhua Date: Mon, 8 Dec 2025 10:05:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=94=B9react-native-touch-id?= =?UTF-8?q?=20=E4=B8=89=E6=96=B9=E5=BA=93=E4=B8=AD=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: liangzhenhua --- en/react-native-touch-id.md | 73 ++++++++++++++++++++++---------- zh-cn/react-native-touch-id.md | 76 ++++++++++++++++++++++++---------- 2 files changed, 105 insertions(+), 44 deletions(-) diff --git a/en/react-native-touch-id.md b/en/react-native-touch-id.md index 7ef64213..89f2cde6 100644 --- a/en/react-native-touch-id.md +++ b/en/react-native-touch-id.md @@ -14,15 +14,16 @@ > [!TIP] [GitHub address](https://github.com/react-native-oh-library/react-native-touch-id) -## Installation and Usage -Please refer to the Releases page of the third-party library for the corresponding version information +The repository for this third-party library has been migrated to Gitcode, and it now supports direct download from npm. The new package name is: `@react-native-ohos/react-native-touch-id`. The specific version relationships are as follows: + +| Version | Package Name | Repository | Release |Supported RN Version | +| ------------------------------ | ---------------- | ------------------- | ------------------- | -------------------- | +| <= 4.4.1-0.0.3@deprecated | @react-native-oh-tpl/react-native-touch-id | [Github](https://github.com/react-native-oh-library/react-native-touch-id) | [Github Releases](https://github.com/react-native-oh-library/react-native-touch-id/releases) | 0.72 | +| 4.4.2 | @react-native-ohos/react-native-touch-id | [GitCode](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id) | [GitCode Releases]() | 0.72 | +| 4.5.0 | @react-native-ohos/react-native-touch-id | [GitCode](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id) | [GitCode Releases]() | 0.77 | -| Third-party Library Version | Release Information | Supported RN Version | -|-------| ------------------------------------------------------------ | ---------- | -| <= 4.4.1-0.0.3@deprecated | [@react-native-oh-tpl/react-native-touch-id Releases(deprecated)](https://github.com/react-native-oh-library/react-native-touch-id/releases) | 0.72 | -| 4.4.2 | [@react-native-ohos/react-native-touch-id Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/releases) | 0.72 | -| 4.5.0 | [@react-native-ohos/react-native-touch-id Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/releases) | 0.77 | +## Installation and Usage For older versions not published on npm, please refer to the [Installation Guide](/en/tgz-usage-en.md) to install the tgz package. @@ -36,6 +37,11 @@ Go to the project directory and execute the following instruction: ```bash npm install @react-native-ohos/react-native-touch-id ``` +If an error occurs during compilation indicating that the source library needs to be imported, you can run the following command + +```bash +npm install --force +``` #### **yarn** @@ -43,6 +49,7 @@ npm install @react-native-ohos/react-native-touch-id yarn add @react-native-ohos/react-native-touch-id ``` + The following code shows the basic use scenario of the repository: @@ -270,6 +277,27 @@ In your `module.json5` | ---- | ----------- | ---- | -------- | -------- | ------------------ | | isSupported | Whether touchid is supported | function | yes | ios/andriod | yes | | authenticate | Verify touchid | function | yes | ios/andriod | yes | +## API Parameters Introduction +### authenticate(reason?: string, config?: AuthenticateConfig); +* **reason**: A string providing a clear reason for requesting authentication +* **config**: A configuration object for more detailed dialog settings + * **AuthenticateConfig**: + | Name | Description | Type | Required | Platform | HarmonyOS Support | + | ---- | ----------- | ---- | -------- | -------- | ------------------ | + | title | **Android only** - Title of the confirmation dialog | string | no | ios/android | yes | + | imageColor | **Android only** - Color of the fingerprint image | string | no | ios/android | no | + | imageErrorColor | **Android only** - Color of the fingerprint image after a failed attempt | string | no | ios/android | no | + | sensorDescription | **Android only** - Text displayed next to the fingerprint image | string | no | ios/android | no | + | sensorErrorDescription | **Android only** - Text displayed next to the fingerprint image after a failed attempt | string | no | ios/android | no | + | cancelText | **Android only** - Cancel button text | string | no | ios/android | yes | + | fallbackLabel | **iOS only** - By default shows "Show Password" label. If set to empty string, the label will be invisible | string | no | ios/android | no | + | passcodeFallback | **iOS only** - Defaults to false. If set to true, will allow fallback to passcode | boolean | no | ios/android | no | +### isSupported(config?: IsSupportedConfig): `Promise`; +* **config** - Returns a `Promise` that rejects if TouchID is not supported. On iOS, resolves to a `biometryType` string with value `FaceID` or `TouchID` + * **IsSupportedConfig**: + | Name | Description | Type | Required | Platform | HarmonyOS Support | + | ---- | ----------- | ---- | -------- | -------- | ------------------ | + | unifiedErrors| Returns unified error messages | boolean | no | ios/android | yes | ## Properties > [!TIP] The **Platform** column indicates the platform where the properties are supported in the original third-party library. @@ -280,22 +308,25 @@ In your `module.json5` | Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | -| Touch ID Error | Permission verification failed | string | no | harmonry | yes | -| Touch ID Error | Incorrect parameters | string | no | harmonry | yes | -| Touch ID Error | Authentication failed | string | no | harmonry | yes | -| Touch ID Error | The operation is canceled | string | no | harmonry | yes | -| Touch ID Error | The operation is time-out | string | no | harmonry | yes | -| Touch ID Error | The authentication type is not supported | string | no | harmonry | yes | -| Touch ID Error | The authentication trust level is not supported | string | no | harmonry | yes | -| Touch ID Error | The authentication task is busy | string | no | harmonry | yes | -| Touch ID Error | The authenticator is locked | string | no | harmonry | yes | -| Touch ID Error | General operation error | string | no | harmonry | no | -| Touch ID Error | The authentication type is not supported | string | no | harmonry | yes | -| Touch ID Error | The type of credential has not been enrolled | string | no | harmonry | yes | -| Touch ID Error | The authentication is canceled from widget's navigation button | string | no | harmonry | yes | -| Touch ID Error | Indicates that current authentication failed because of PIN expired | string | no | harmonry | yes | +| 201 | Permission verification failed | string | no | harmonry | yes | +| 401 | Incorrect parameters | string | no | harmonry | no | +| 12500001 | Authentication failed | string | no | harmonry | yes | +| 12500002 | General operation error | string | no | harmonry | no | +| 12500003 | The operation is canceled | string | no | harmonry | yes | +| 12500004 | The operation is time-out | string | no | harmonry | no | +| 12500005 | The authentication type is not supported | string | no | harmonry | no | +| 12500006 | The authentication trust level is not supported | string | no | harmonry | no | +| 12500007 | The authentication task is busy | string | no | harmonry | no | +| 12500009 | The authenticator is locked | string | no | harmonry | yes | +| 12500010 | The type of credential has not been enrolled | string | no | harmonry | yes | +| 12500011 | The authentication is canceled from widget's navigation button | string | no | harmonry | yes | +| 12500013 | Indicates that current authentication failed because of PIN expired | string | no | harmonry | no | + ## Known Issues +- [ ] The config parameter is partially supported.[issue#13](https://github.com/react-native-oh-library/react-native-touch-id/issues/13) +- [ ] Error is partially supported.[issue#12](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/issues/12) + ## Others ## License diff --git a/zh-cn/react-native-touch-id.md b/zh-cn/react-native-touch-id.md index a5cb5b26..3ddecee5 100644 --- a/zh-cn/react-native-touch-id.md +++ b/zh-cn/react-native-touch-id.md @@ -14,15 +14,15 @@ > [!TIP] [Github 地址](https://github.com/react-native-oh-library/react-native-touch-id) -## 安装与使用 +该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-touch-id`，具体版本所属关系如下： -请到三方库的 Releases 发布地址查看配套的版本信息： +| Version | Package Name | Repository | Release |Supported RN Version | +| ------------------------------ | ---------------- | ------------------- | ------------------- | -------------------- | +| <= 4.4.1-0.0.3@deprecated | @react-native-oh-tpl/react-native-touch-id | [Github](https://github.com/react-native-oh-library/react-native-touch-id) | [Github Releases](https://github.com/react-native-oh-library/react-native-touch-id/releases) | 0.72 | +| 4.4.2 | @react-native-ohos/react-native-touch-id | [GitCode](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id) | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/releases) | 0.72 | +| 4.5.0 | @react-native-ohos/react-native-touch-id | [GitCode](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id) | [GitCode Releases]() | 0.77 | -| 三方库版本 | 发布信息 | 支持RN版本 | -|-------| ------------------------------------------------------------ | ---------- | -| <= 4.4.1-0.0.3@deprecated | [@react-native-oh-tpl/react-native-touch-id Releases(deprecated)](https://github.com/react-native-oh-library/react-native-touch-id/releases) | 0.72 | -| 4.4.2 | [@react-native-ohos/react-native-touch-id Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/releases) | 0.72 | -| 4.5.0 | [@react-native-ohos/react-native-touch-id Releases](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/releases) | 0.77 | +## 安装与使用 对于未发布到npm的旧版本，请参考[安装指南](/zh-cn/tgz-usage.md)安装tgz包。 @@ -36,6 +36,11 @@ npm install @react-native-ohos/react-native-touch-id ``` +如果在编译时报错为需引入源库，可以运行如下指令 + +```bash +npm install --force +``` #### **yarn** ```bash @@ -269,8 +274,30 @@ In your `module.json5` | Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | -| isSupported | Whether touchid is supported | function | yes | ios/andriod | yes | -| authenticate | Verify touchid | function | yes | ios/andriod | yes | +| isSupported | 是否支持 Touch ID | function | yes | ios/andriod | yes | +| authenticate | 验证 Touch ID | function | yes | ios/andriod | yes | + +## API 参数介绍 +### authenticate(reason?: string, config?: AuthenticateConfig); +* **reason**: 提供请求身份验证的明确原因的字符串 +* **config**: 用于更详细对话框设置的配置对象 + * **AuthenticateConfig**: + | Name | Description | Type | Required | Platform | HarmonyOS Support | + | ---- | ----------- | ---- | -------- | -------- | ------------------ | + | title | **仅Android** - 确认对话框的标题 | string | no | ios/andriod | yes | + | imageColor | **仅Android** - 指纹图像的颜色 | string | no | ios/andriod | no | + | imageErrorColor | **仅Android** - 尝试失败后指纹图像的颜色 | string | no | ios/andriod | no | + | sensorDescription | **仅Android** - 指纹图像旁边显示的文字 | string | no | ios/andriod | no | + | sensorErrorDescription | **仅Android** - 尝试失败后指纹图像旁边显示的文字 | string | no | ios/andriod | no | + | cancelText | **仅Android** - 取消按钮文字 | string | no | ios/andriod | yes | + | fallbackLabel | **仅iOS** - 默认显示"显示密码"标签。如果设置为空字符串，标签将不可见 | string | no | ios/andriod | no | + | passcodeFallback | **仅iOS** - 默认设置为false。如果设置为true，将允许使用键盘密码 | boolean | no | ios/andriod | no | +### isSupported(config?: IsSupportedConfig): `Promise`; +* **config** - 返回一个`Promise`，如果TouchID不支持则会拒绝。在iOS上会解析为一个`biometryType`字符串，值为`FaceID`或`TouchID` + * **IsSupportedConfig**: + | Name | Description | Type | Required | Platform | HarmonyOS Support | + | ---- | ----------- | ---- | -------- | -------- | ------------------ | + | unifiedErrors| 返回统一的错误信息 |boolean| no | ios/andriod | yes | ## 属性 > [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 @@ -281,22 +308,25 @@ In your `module.json5` | Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | -| Touch ID Error | Permission verification failed | string | no | harmonry | yes | -| Touch ID Error | Incorrect parameters | string | no | harmonry | yes | -| Touch ID Error | Authentication failed | string | no | harmonry | yes | -| Touch ID Error | The operation is canceled | string | no | harmonry | yes | -| Touch ID Error | The operation is time-out | string | no | harmonry | yes | -| Touch ID Error | The authentication type is not supported | string | no | harmonry | yes | -| Touch ID Error | The authentication trust level is not supported | string | no | harmonry | yes | -| Touch ID Error | The authentication task is busy | string | no | harmonry | yes | -| Touch ID Error | The authenticator is locked | string | no | harmonry | yes | -| Touch ID Error | General operation error | string | no | harmonry | no | -| Touch ID Error | The authentication type is not supported | string | no | harmonry | yes | -| Touch ID Error | The type of credential has not been enrolled | string | no | harmonry | yes | -| Touch ID Error | The authentication is canceled from widget's navigation button | string | no | harmonry | yes | -| Touch ID Error | Indicates that current authentication failed because of PIN expired | string | no | harmonry | yes | +| 201 | Permission verification failed | string | no | harmonry | yes | +| 401 | Incorrect parameters | string | no | harmonry | no | +| 12500001 | Authentication failed | string | no | harmonry | yes | +| 12500002 | General operation error | string | no | harmonry | no | +| 12500003 | The operation is canceled | string | no | harmonry | yes | +| 12500004 | The operation is time-out | string | no | harmonry | no | +| 12500005 | The authentication type is not supported | string | no | harmonry | no | +| 12500006 | The authentication trust level is not supported | string | no | harmonry | no | +| 12500007 | The authentication task is busy | string | no | harmonry | no | +| 12500009 | The authenticator is locked | string | no | harmonry | yes | +| 12500010 | The type of credential has not been enrolled | string | no | harmonry | yes | +| 12500011 | The authentication is canceled from widget's navigation button | string | no | harmonry | yes | +| 12500013 | Indicates that current authentication failed because of PIN expired | string | no | harmonry | no | + ## 遗留问题 +- [ ] config参数部分支持.[issue#13](https://github.com/react-native-oh-library/react-native-touch-id/issues/13) +- [ ] error部分触发。[issue#12](https://gitcode.com/openharmony-sig/rntpc_react-native-touch-id/issues/12) + ## 其他 ## 开源协议 -- Gitee