# @facilitronworks/react-native-windows-sync-kv 中文文档

规范地址：https://npmcn.com/package/%40facilitronworks/react-native-windows-sync-kv/

版本：0\.1\.0-pre\.1
npm 元数据更新时间：2026-07-21T13:36:58.466Z
中文译文更新时间：2026-11-14T08:14:57.306Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40facilitronworks/react-native-windows-sync-kv
原文对照：https://npmcn.com/package/%40facilitronworks/react-native-windows-sync-kv/?lang=original
项目主页：https://github.com/FacilitronWorks/react-native-windows-sync-kv#readme
源码仓库：https://github.com/FacilitronWorks/react-native-windows-sync-kv

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：45.8 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react-native \>=0\.76\.0，react-native-windows \>=0\.76\.0
- 首次发布：2026-07-18T14:56:05.191Z
- 最新版本发布：2026-07-21T13:36:58.284Z
- 近 30 天下载量：4270（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

同步,持续键/值存储 React Endern Windows (新架构)——原始的RNW没有. 文件通过应用程序Data备份. 本地的Folder通过REACT SYNC METHOD接触到JS,所以读取回取值,而不是承诺.

## 安装

```sh
npm install @facilitronworks/react-native-windows-sync-kv
```

也可以使用：`pnpm add @facilitronworks/react-native-windows-sync-kv`、`yarn add @facilitronworks/react-native-windows-sync-kv`、`bun add @facilitronworks/react-native-windows-sync-kv`

## README

# @facilitronworks/ react-native-windows-sync-kv (英语)

**同步、 有持久性的密钥/ 值存储, 用于 React Endern Windows** 在新架构(Fabric / Constitution)上——存储原始的RNW没有.

> **状况:释放前`0.1.0-pre.1`) (中文(简体) ).** C++的实现取自一款货运出品的Windows应用软件(RNW 0.83.2,Windows-on-ARM和x64),它是四个独立的JS软件包背后的存储引擎". Windows shims (英语).
> 
> **这里所证实的是:** 见 [核查状况](https://npmcn.com/package/%40facilitronworks/react-native-windows-sync-kv/#readme-verification-status). 阅读它之前取决于这个.

## 为什么会这样

反应原生窗口船 **没有同步,JS可访问的持久商店**不是一个缓慢的,一个也没有。 每个选项要么同步要么缺失:

| 软件包 | 窗口状态 |
| --- | --- |
| `@react-native-async-storage/async-storage` | 顾名思义—— `await` 每个读取. |
| `react-native-mmkv` 页:1 | 硝基/内生; **无窗口构建**。使 MMKV 值值的同步 API 不可用. |
| `react-native-encrypted-storage` | 没有 Windows 执行 . |
| `expo-secure-store` | 没有 Windows 执行 . |

缝隙最深 **离线第一应用程序**MMKV编程模式 - `const token = storage.getString('token')` 返回一个 _价值_ 在模块装入时间,而不是一个承诺——就是让屏幕在第一幅油漆上充电,而不是在后期闪出并填入一勾。 移植到Windows上,这个代码不仅运行得更慢;它不会运行.

此模块提供缺失的原始: a `REACT_SYNC_METHOD`\- 基于商店 阻断JS线 微秒 并手拿回值.

在从应用程序中提取的,这个单一的本地模块背起Windows shims用于 **全部四个** 上方的软件包——每个软件包都将其密钥放入同一个商店.

## 如何运作

-   从JSON取出一个水分 `ApplicationData.LocalFolder\SyncKV.json` 变成记忆 `std::unordered_map` **一次**,懒惰地,在第一次访问(mirroring MMKV的mmap-hydrate-once模型)时,通过同步 `std::ifstream`。 。 。 .
-   服务从地图上读取和书写 零声速.
-   跳出( 300 ms squiet phile) 写到背景线上 `.tmp` 财务报告和审定财务报表 `MoveFileExW(..., MOVEFILE_REPLACE_EXISTING)` ——"杀" 中写只能腐蚀临时文件,从不真实.
-   `clearAll()` 冲出 **同步**,所以登出/清洗 立即持久.

### 此编码的终身陷阱

这是值得阅读的部分 即使你写自己的.

创建并销毁反应模块实例 **每个反应实例** 每个地铁都重新装入了你的眼泪 明显的设计(地图、变种、条件变量作为实例成员;脱开的工人线条捕捉) `this`)在重新装入时产生无用后:孤儿工人不断读写被放出的例子. 它以随机的赫尔墨斯访问违规和故障快克的形式,在三个截然不同的崩溃签名中呈现出来,并且越来越糟糕的是,存储的数据越多——即它看起来除了一个终生错误之外什么也一样.

这个舱载的固定装置: **所有可变状态都生活在故意被泄露的流程-寿命单子中**,而且每个过程都存在一个精确的工人线程,无论React实例重载了多少次. 一个被泄露的单子无法缠绕;操作系统会在过程死亡时将其还原.

### 在此编码的其他约束

-   **RNW 同步方法无法返回 `void`** —— 说 `ModuleSyncMethodInfo` 需要一个 `TResult`。这就是为什么 `set` 编号 : `remove` 编号 : `clearAll` 返回时 `bool`。 。 。 .
-   每个方法都是 `noexcept` 根据同步方法合同,所以 **每一个分配体是 `try`\- 包装**A级 `bad_alloc` 逃脱a `noexcept` 函数快速失败进程,而多MB值使该程序可以达到.
-   书写保持同步( 不) `REACT_METHOD`具体地说 `set()` 紧接着是 `getString()` 观察新的价值.

## 安装

```sh
npm install @facilitronworks/react-native-windows-sync-kv
# or: yarn add @facilitronworks/react-native-windows-sync-kv
```

然后自动连接和重建:

```sh
npx react-native autolink-windows
npx react-native run-windows
```

自动链接源代码 `#include <winrt/RNWSyncKv.h>` 财务报告和审定财务报表 `packageProviders.Append(winrt::RNWSyncKv::ReactPackageProvider())` 从 `<RootNamespace>` 输入 `.vcxproj`。 。 。 . **大都会重载将无法取回一个新的本土模块——你必须重建.**

没有 `WinMain` 需要接线: 此模块没有主机窗口依赖性 .

## 使用量

```ts
import {
  getString, set, remove, contains, getAllKeys, clearAll, createStore,
} from '@facilitronworks/react-native-windows-sync-kv';

set('token', 'abc');
getString('token');   // 'abc'  — a value, not a promise
contains('token');    // true
getAllKeys();         // ['token']
remove('token');
clearAll();           // wipes everything, flushes synchronously
```

命名空间商店, 当多个逻辑商店共享一个本地块时 :

```ts
const prefs = createStore('prefs');
prefs.set('darkMode', true);
prefs.getBoolean('darkMode');  // true
prefs.getString('missing');    // undefined  (not '')
prefs.clearAll();              // only clears the 'prefs.' namespace
```

注意故意的区别: 平地 `getString()` 返回时 `''` 丢失的密钥(原始本地合同) `createStore(...).getString()` 返回时 `undefined`,匹配反应-内生-mmkv表面.

### 闪出另一个软件包

典型的用途是 `.windows.ts` 平台扩展,将另一个软件包的API再导出到此商店上方,例如用于 `react-native-mmkv`数字 :

```ts
// mmkvStorage.windows.ts
import { createStore } from '@facilitronworks/react-native-windows-sync-kv';
export const storage = createStore('mmkv');
```

## 你会撞上陷阱

-   **值为字符串.** 将其它东西按顺序排列`createStore` 强迫布尔和数字通过 `String()` 并剖析他们。 上盘格式是字符串=字符串的平坦的JSON对象;在水合物上跳过手版文件中的非字符串JSON值.
-   **`getString()` 无法区分“ missing”和“ missing” `''`。 。 。 .** 使用 `contains()` -或者说 `createStore`这对你有好处.
-   **这堵住了JS线条.** 每把按键存储兆字节,在渲染道上读取它们就会被显示为相克. 这是一个偏好/会话商店,不是数据库.
-   **未加密 .** `LocalFolder\SyncKV.json` 在磁盘上是普通的JSON。 闪电 `expo-secure-store` 或者说 `react-native-encrypted-storage` 在它给你 _API 密码_,而不是他们的 _安全保证_。在此不添加加密(例如 DPAPI) .
-   **该商店是全流程的,没有分割.** 两个图书馆选择相同的密钥相撞. 通过命名空间 `createStore`。 。 。 .
-   **从源头建楼需要先恢复 NuGet** (单位:千美元)`msbuild -restore`) (中文(简体) ). 没有它,CppWinRT目标 从来没有加载, `.idl` 文件流经经典 `midl.exe` 改为 `midlrt`和每个 `namespace` 声明失败 `MIDL2025`。 。 。 .

## 核查状况

**已验证**,在这个精确的包装来源上:

-   被包装的窗体编译. 通过 a 自动链接 `portal:` 依赖消费的RNW 0.83.2 新成品应用,并为 **ARM64 调试**,生产 `RNWSyncKv.dll`, (中文(简体) ), `RNWSyncKv.winmd` 财务报告和审定财务报表 `RNWSyncKv.lib`。 。 。 .
-   `autolink-windows` 解析软件包并同时发送包含和 `ReactPackageProvider` 登记.

**未核实** - 不假定其中任何一项:

-   **DLL 的运行时行为 _这个_ 项目.** 来源是生产-在它的原应用中被证实,但此回波所生产的二进制没有在设备上被执行:没有进行读取/写入/持久性/再装入测试.
-   **x64, Win32, 和发行** 配置 只有ARM64调试器建成.
-   这个 `src/index.ts` **JS层是这个套件的新款** 并且没有从生产应用中被取出(它通过自己的每包shims称为"原生模块"). 输入检查; 尚未运行 .
-   没有实例应用,没有自动化测试,没有CI.
-   同一应用程序共享一个多个进程/程序下的行为 `LocalFolder` 是未定义和未经检验的——最多最后一位作家获胜.

## 更改日志

-   **0.1.0-前1节** ——后置存储文件现在 `SyncKV.json` (曾经是) `RNWSyncKv.json`),因此采用现有 `SyncKV.json` ; 供从树上模块迁移的消费者使用.
-   **0.1.0 - 预0** ——初步预发.

## 许可证

麻省理工学院

## 常见问题

### @facilitronworks/react-native-windows-sync-kv 是什么？

同步,持续键/值存储 React Endern Windows \(新架构\)——原始的RNW没有\. 文件通过应用程序Data备份\. 本地的Folder通过REACT SYNC METHOD接触到JS,所以读取回取值,而不是承诺\.

### 如何安装 @facilitronworks/react-native-windows-sync-kv？

在项目目录运行 npm install @facilitronworks/react-native-windows-sync-kv，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react-native（\>=0\.76\.0）、react-native-windows（\>=0\.76\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @facilitronworks/react-native-windows-sync-kv 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @facilitronworks/react-native-windows-sync-kv 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @facilitronworks/react-native-windows-sync-kv 可以商用吗？

@facilitronworks/react-native-windows-sync-kv 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @facilitronworks/react-native-windows-sync-kv 的下载量有多少？

根据 npm 官方下载统计，@facilitronworks/react-native-windows-sync-kv 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,270 次，日均约 142 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @facilitronworks/react-native-windows-sync-kv 还在维护吗？

最新版本 0\.1\.0-pre\.1 发布于 2026/07/21（3 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。