@react-native-ohos/react-native-default-preference 1.6.0-beta.1 → 1.6.0-beta.2

package/CHANGELOG.md

@@ -1,8 +1,37 @@
-# v1.6.0-beta.1
-## 更新内容
-* 增加82版本适配的autolinking
-
-# v1.4.5-rc.1
-## 更新内容
-* 修改组织名为@react-native-ohos
-* 内置Codegen生成代码
+# CHANGELOG
+
+
+## [1.6.0-beta.2] - 2026-09
+
+### Fixed
+
+- Fix Harmony `get` returning `'default'` for missing keys; now returns `null` to match Android/iOS ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix `set` / `clear` / `clearAll` / `setMultiple` / `clearMultiple` / `setName` Promises never resolving ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix missing `flush` after `clear` / `clearAll`, which could prevent persistence ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix `clear` / `clearMultiple` not re-fetching the Preferences instance after `setName` ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix `getAll` returning a key array instead of a `{ [key: string]: string }` object ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix `getName` default value to use `bundleName_preferences` (aligned with Android) ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- Fix hung Promises on error paths in `get` / `getAll`
+
+### Changed
+
+- **Breaking (Harmony):** `getAll` now returns a key-value object instead of `string[]` ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- **Breaking (Harmony):** missing keys in `get` / `getMultiple` now return `null` instead of `'default'`  ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+- **Breaking (Harmony):** default Preferences name changed from `'defultName'` to `bundleName_preferences`  ([#23](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pull/23))
+
+### Added
+
+- Add example gate project with rnt demo and Harmony shell
+
+## [1.6.0-beta.1] - 2026-05-14
+
+### Added
+
+- Autolinking support for RNOH 0.82
+
+## [1.4.5-rc.1] - 2026-04-13
+
+### Changed
+
+- Rename npm scope to `@react-native-ohos`
+- Bundle Codegen-generated bridge code in the repository

package/COMMITTERS.md

@@ -1,7 +1,8 @@
-## Committers列表
-
-### 以下是此项目的committer人员
-
-不区分先后顺序
-
-- [xiafeng_xf_admin](https://gitee.com/xiafeng_xf_admin)
+## Committers列表
+
+### 以下是此项目的committer人员
+
+不区分先后顺序
+
+[zhu_chengcheng](https://gitcode.com/zhu_chengcheng)
+[huang_jy](https://gitcode.com/gcw_N7oHqLFR)

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2017 Kevin Leung
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2017 Kevin Leung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OAT.xml

@@ -1,69 +1,75 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- Copyright (c) 2021 Huawei Device Co., Ltd.
-     Licensed under the Apache License, Version 2.0 (the "License");
-     you may not use this file except in compliance with the License.
-     You may obtain a copy of the License at
-          http://www.apache.org/licenses/LICENSE-2.0
-     Unless required by applicable law or agreed to in writing, software
-     distributed under the License is distributed on an "AS IS" BASIS,
-     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-     See the License for the specific language governing permissions and
-     limitations under the License.
-    This is the configuration file template for OpenHarmony OSS Audit Tool, please copy it to your project root dir and modify it refer to OpenHarmony/tools_oat/README.
--->
-
-<configuration>
-    <oatconfig>
-	    <licensefile>LICENSE</licensefile>
-        <policylist>
-            <policy name="projectPolicy" desc="">
-                <policyitem type="license" name="MIT" path=".*" desc="license under the MIT"/>
-            </policy>
-            <policy name="projectPolicy" desc="">
-                <policyitem type="compatibility" name="GPL-2.0+" path=".*" desc="Process that runs independently, invoked by the X process."/>
-                <policyitem type="compatibility" name="Apache-2.0" path=".*" desc="不影响兼容性"/>
-                <policyitem type="compatibility" name="BSDStyleLicense" path=".*" desc="不影响兼容性" />
-                <policyitem type="compatibility" name="MIT" path=".*" desc="不影响兼容性" />
-                <policyitem type="compatibility" name="GPLStyleLicense" path=".*" desc="不影响兼容性" />
-            </policy>
-        </policylist>
-        <filefilterlist>
-            <filefilter name="defaultFilter" desc="Files not to check">
-
-            </filefilter>
-			<filefilter name="defaultPolicyFilter" desc="Filters for compatibility，license header policies">
-                <filteritem type="filename" name="LICENSE" desc="许可证说明文件，不添加版权头"/>
-                <filteritem type="filename" name="RNDefaultPreference.podspec" desc="工程配置文件，不添加版权头"/>
-         	    <filteritem type="filename" name="README.OpenSource" desc="许可证说明文件，不添加版权头"/>
-         	    <filteritem type="filename" name="index.d.ts" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filename" name="index.js" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="flow-typed/index.js" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/src/main/module.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/BuildProfile.ets" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/build-profile.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/hvigorfile.ts" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package-lock.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package.json5" desc="工程配置文件，不添加许可证头"/>
-
-            </filefilter>
-            <filefilter name="binaryFileTypePolicyFilter" desc="Filters for copyright header policies">
-                <filteritem type="filepath" name="harmony/react_native_default_preference.har" desc="项目打包文件"/>
-            </filefilter>
-
-            <filefilter name="copyrightPolicyFilter" desc="Filters for copyright header policies">
-                <filteritem type="filename" name="RNDefaultPreference.podspec" desc="工程配置文件，不添加版权头"/>
-         	    <filteritem type="filename" name="README.OpenSource" desc="许可证说明文件，不添加版权头"/>
-         	    <filteritem type="filename" name="index.d.ts" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filename" name="index.js" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="flow-typed/index.js" desc="需要引用的原库文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/src/main/module.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/BuildProfile.ets" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/build-profile.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/hvigorfile.ts" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package-lock.json5" desc="工程配置文件，不添加许可证头"/>
-         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package.json5" desc="工程配置文件，不添加许可证头"/>
-
-            </filefilter>
-        </filefilterlist>
-    </oatconfig>
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Copyright (c) 2021 Huawei Device Co., Ltd.
+     Licensed under the Apache License, Version 2.0 (the "License");
+     you may not use this file except in compliance with the License.
+     You may obtain a copy of the License at
+          http://www.apache.org/licenses/LICENSE-2.0
+     Unless required by applicable law or agreed to in writing, software
+     distributed under the License is distributed on an "AS IS" BASIS,
+     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+    This is the configuration file template for OpenHarmony OSS Audit Tool, please copy it to your project root dir and modify it refer to OpenHarmony/tools_oat/README.
+-->
+
+<configuration>
+    <oatconfig>
+	    <licensefile>LICENSE</licensefile>
+        <policylist>
+            <policy name="projectPolicy" desc="">
+                <policyitem type="license" name="MIT" path=".*" desc="license under the MIT"/>
+            </policy>
+            <policy name="projectPolicy" desc="">
+                <policyitem type="compatibility" name="GPL-2.0+" path=".*" desc="Process that runs independently, invoked by the X process."/>
+                <policyitem type="compatibility" name="Apache-2.0" path=".*" desc="不影响兼容性"/>
+                <policyitem type="compatibility" name="BSDStyleLicense" path=".*" desc="不影响兼容性" />
+                <policyitem type="compatibility" name="MIT" path=".*" desc="不影响兼容性" />
+                <policyitem type="compatibility" name="GPLStyleLicense" path=".*" desc="不影响兼容性" />
+            </policy>
+        </policylist>
+        <filefilterlist>
+            <filefilter name="defaultFilter" desc="Files not to check">
+
+            </filefilter>
+			<filefilter name="defaultPolicyFilter" desc="Filters for compatibility，license header policies">
+                <filteritem type="filename" name="LICENSE" desc="许可证说明文件，不添加版权头"/>
+                <filteritem type="filename" name="RNDefaultPreference.podspec" desc="工程配置文件，不添加版权头"/>
+         	    <filteritem type="filename" name="README.OpenSource" desc="许可证说明文件，不添加版权头"/>
+         	    <filteritem type="filename" name="index.d.ts" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filename" name="index.js" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="flow-typed/index.js" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/src/main/module.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/BuildProfile.ets" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/build-profile.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/hvigorfile.ts" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package-lock.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package.json5" desc="工程配置文件，不添加许可证头"/>
+                <filteritem type="filepath" name="example/*.*" desc="demo工程，不添加许可证头"/>
+            </filefilter>
+            <filefilter name="binaryFileTypePolicyFilter" desc="Filters for copyright header policies">
+                <filteritem type="filepath" name="harmony/react_native_default_preference.har" desc="项目打包文件"/>
+                <filteritem type="filepath" name="example/harmony/entry/src/main/resources/base/media/icon.png" desc="项目资源文件"/>
+                <filteritem type="filepath" name="example/rnoh-testerino-0.0.12.tgz" desc="项目资源文件"/>
+                <filteritem type="filepath" name="example/harmony/AppScope/resources/base/media/app_icon.png" desc="项目资源文件"/>
+
+
+
+            </filefilter>
+
+            <filefilter name="copyrightPolicyFilter" desc="Filters for copyright header policies">
+                <filteritem type="filename" name="RNDefaultPreference.podspec" desc="工程配置文件，不添加版权头"/>
+         	    <filteritem type="filename" name="README.OpenSource" desc="许可证说明文件，不添加版权头"/>
+         	    <filteritem type="filename" name="index.d.ts" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filename" name="index.js" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="flow-typed/index.js" desc="需要引用的原库文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/src/main/module.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/BuildProfile.ets" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/build-profile.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/hvigorfile.ts" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package-lock.json5" desc="工程配置文件，不添加许可证头"/>
+         	    <filteritem type="filepath" name="harmony/react_native_default_preference/oh-package.json5" desc="工程配置文件，不添加许可证头"/>
+                <filteritem type="filepath" name="example/*.*" desc="demo工程，不添加许可证头"/>
+            </filefilter>
+        </filefilterlist>
+    </oatconfig>
 </configuration>

package/README.OpenSource

@@ -1,11 +1,11 @@
-[
-    {
-        "Name": "react-native-default-preference",
-        "License": "MIT License",
-        "License File": "https://github.com/kevinresol/react-native-default-preference/blob/master/LICENSE",
-        "Version Number": "1.4.4",
-        "Owner" : "xiafeng@huawei.com",
-        "Upstream URL": "https://github.com/kevinresol/react-native-default-preference",
-        "Description": "Use SharedPreference (Android) and UserDefaults (iOS) with React Native over a unified interface"
-    }
+[
+    {
+        "Name": "react-native-default-preference",
+        "License": "MIT License",
+        "License File": "https://github.com/kevinresol/react-native-default-preference/blob/master/LICENSE",
+        "Version Number": "1.4.4",
+        "Owner" : "xiafeng@huawei.com",
+        "Upstream URL": "https://github.com/kevinresol/react-native-default-preference",
+        "Description": "Use SharedPreference (Android) and UserDefaults (iOS) with React Native over a unified interface"
+    }
 ]

package/README.md

@@ -1,13 +1,248 @@
-# @react-native-ohos/react-native-default-preference
-
-This project is based on [react-native-default-preference](https://github.com/kevinresol/react-native-default-preference)
-
-## Documentation
-
-[中文](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/zh-cn/react-native-default-preference.md)
-
-[English](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/en/react-native-default-preference.md)
-
-## License
-
-This library is licensed under [The MIT License (MIT)](https://github.com/kevinresol/react-native-default-preference/blob/master/LICENSE).
+> 文档模板：v0.4.2
+
+<p align="center">
+  <h1 align="center"> <code>react-native-default-preference</code> </h1>
+</p>
+
+本项目基于 [react-native-default-preference](https://github.com/kevinresol/react-native-default-preference) 开发。
+
+该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-default-preference`。版本所属关系如下：
+
+| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 |
+| ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- |
+| @react-native-ohos/react-native-default-preference | [~ 1.6.0](https://www.npmjs.com/package/@react-native-ohos/react-native-default-preference) | [Gitcode Releases](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/releases) | 0.82.* / 0.77.* / 0.72.* | partially | API12+ | 1.4.4 | [master](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/tree/master) |
+| @react-native-oh-tpl/react-native-default-preference | [<= 1.4.4-0.0.1@deprecated](https://www.npmjs.com/package/@react-native-oh-tpl/react-native-default-preference) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-default-preference/releases) | 0.72.* | 否 | API12+ | 1.4.4 | [sig](https://github.com/react-native-oh-library/react-native-default-preference) |
+
+
+## 简介
+
+本库在 React Native 中提供统一接口，用于读写 Android `SharedPreferences`、iOS `UserDefaults` 以及 HarmonyOS `@ohos.data.preferences` 用户首选项。
+
+所有数据均以字符串形式存储。如需存储复杂数据结构，请自行序列化/反序列化（例如 JSON）。
+
+## 下载安装
+
+进入到工程目录并输入以下命令：
+
+**npm**
+
+```bash
+npm install @react-native-ohos/react-native-default-preference
+```
+
+**yarn**
+
+```bash
+yarn add @react-native-ohos/react-native-default-preference
+```
+
+## Link
+
+| | 是否支持autolink | RN框架版本 |
+|--------------------------------------|----------------|-----------|
+| ~ 1.6.0 | partially | 0.82 / 0.77 / 0.72 |
+
+
+使用 AutoLink 的工程需要根据 [Autolink 框架指导文档](https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md) 配置。
+
+<details>
+  <summary>ManualLink: 此步骤为手动配置原生依赖项的指导</summary>
+
+首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 `harmony`。
+
+### 1. Overrides RN SDK
+
+为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 `oh-package.json5` 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。
+
+```json
+{
+  "overrides": {
+    "@rnoh/react-native-openharmony": "~0.82.1"
+  }
+}
+```
+
+### 2. 引入原生端代码
+
+目前有两种方法：
+
+- 通过 har 包引入（推荐）；
+- 直接链接源码。
+
+方法一：通过 har 包引入（推荐）
+
+> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。
+
+打开 `entry/oh-package.json5`，添加以下依赖：
+
+```json
+"dependencies": {
+  "@react-native-ohos/react-native-default-preference": "file:../../node_modules/@react-native-ohos/react-native-default-preference/harmony/react_native_default_preference.har"
+}
+```
+
+方法二：直接链接源码
+
+> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md)
+
+### 3. 配置 CMakeLists 和引入 DefaultPreferencePackage
+
+打开 `entry/src/main/cpp/CMakeLists.txt`，添加：
+
+```diff
++ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-default-preference/src/main/cpp" ./default_preference)
++ target_link_libraries(rnoh_app PUBLIC rnoh_default_preference)
+```
+
+打开 `entry/src/main/cpp/PackageProvider.cpp`，添加：
+
+```diff
++ #include "DefaultPreferencePackage.h"
++ std::make_shared<DefaultPreferencePackage>(ctx)
+```
+
+### 4. 在 ArkTs 侧引入 RNDefaultPreferencePackage
+
+打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加：
+
+```diff
++ import { RNDefaultPreferencePackage } from '@react-native-ohos/react-native-default-preference/ts';
+
+export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
+  return [
++   new RNDefaultPreferencePackage(ctx)
+  ];
+}
+```
+
+</details>
+
+### 运行
+
+点击右上角的 `sync` 按钮，或者在命令行终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+然后编译、运行即可。
+
+## 约束与限制
+
+### 兼容性
+
+本文档内容基于以下版本验证通过：
+
+1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
+3. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
+4. RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.120 SP7;
+
+> [!TIP] 当前三方库所有版本均已实现版本隔离，支持在 `API12+` 工程编译，及 `API12+` ROM 运行。
+
+## 使用示例
+
+下面的代码展示了这个库的基本使用场景：
+
+> [!WARNING] 使用时 import 的库名不变。
+
+```javascript
+import DefaultPreference from 'react-native-default-preference';
+
+DefaultPreference.get('my key').then((value) => {
+  console.log(value);
+});
+
+DefaultPreference.set('my key', 'my value').then(() => {
+  console.log('done');
+});
+```
+
+## 使用说明
+
+**Preferences 文件名称**
+
+- Android 默认使用 `包名_preferences`
+- HarmonyOS 默认使用 `bundleName_preferences`（与 Android 对齐）
+- 可通过 `setName` / `getName` 切换存储实例名称
+
+**Cordova Native Storage 兼容**
+
+与 cordova-plugin-native-storage 兼容时，Android 需设置相同 SharedPreferences 名称：
+
+```javascript
+import { Platform } from 'react-native';
+import DefaultPreference from 'react-native-default-preference';
+
+if (Platform.OS === 'android') {
+  DefaultPreference.setName('NativeStorage');
+}
+```
+
+本库已内置 Codegen 生成代码（`harmony/react_native_default_preference/src/main/ets/generated` 与 `src/main/cpp/generated`）。一般无需手动生成；如需重新生成，可在库根目录执行：
+
+```bash
+npm run codegen-lib
+```
+
+## 接口说明
+
+> [!TIP] "Platform" 列表示该接口在原三方库上支持的平台。
+>
+> [!TIP] "HarmonyOS Support" 列为 yes 表示 HarmonyOS 平台支持该接口；no 表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android。
+
+| 名称 | 说明 | 类型 | 必填 | Platform | HarmonyOS Support |
+| ------------- | ----------------------------- | -------- | -------- | ------------ | ----------------- |
+| get | 读取指定 key 的值；不存在时返回 `null` | function | no | Android、iOS | yes |
+| set | 写入 key-value | function | no | Android、iOS | yes |
+| clear | 删除指定 key | function | no | Android、iOS | yes |
+| getMultiple | 批量读取多个 key | function | no | Android、iOS | yes |
+| setMultiple | 批量写入多个 key-value | function | no | Android、iOS | yes |
+| clearMultiple | 批量删除多个 key | function | no | Android、iOS | yes |
+| getAll | 读取全部键值对，返回 `{ [key: string]: string }` | function | no | Android、iOS | yes |
+| clearAll | 清空全部键值对 | function | no | Android、iOS | yes |
+| getName | 获取当前 Preferences 实例名称 | function | no | Android、iOS | yes |
+| setName | 设置 Preferences 实例名称 | function | no | Android、iOS | yes |
+
+
+## 遗留问题
+
+无
+
+## 其他
+
+无
+
+## 目录结构
+
+```
+/rntpc_react-native-default-preference
+├── harmony/                              # 鸿蒙适配代码
+│   ├── react_native_default_preference.har
+│   └── react_native_default_preference/  # 鸿蒙 HAR 模块
+│       ├── Index.ets
+│       ├── ts.ets                        # ArkTS Package 导出
+│       └── src/main/
+│           ├── cpp/                      # C++ TurboModule 桥接
+│           └── ets/                      # ArkTS TurboModule 实现
+│               ├── RNDefaultPreferencePackage.ets
+│               └── RNDefaultPreferenceTurboModule.ts
+├── src/
+│   └── NativeDefaultPreference.ts        # TurboModule Codegen Spec
+├── example/                              # 示例与门禁测试工程
+├── index.js                              # JS 入口
+├── index.d.ts
+├── package.json
+├── README.md
+├── README_EN.md
+└── CHANGELOG.md
+```
+
+## 贡献代码
+
+使用过程中发现任何问题都可以提交 [Issue](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/issues)，当然，也非常欢迎提交 [PR](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/pulls) 。
+
+## 开源协议
+
+本项目基于 [The MIT License (MIT)](https://gitcode.com/CPF-RN/rntpc_react-native-default-preference/blob/master/LICENSE) ，请自由地享受和参与开源。