# @baukit/preferences-core 中文文档

规范地址：https://npmcn.com/package/%40baukit/preferences-core/

版本：0\.18\.3
npm 元数据更新时间：2026-11-07T02:35:41.303Z
中文译文更新时间：2026-11-07T18:32:34.718Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40baukit/preferences-core
原文对照：https://npmcn.com/package/%40baukit/preferences-core/?lang=original
项目主页：https://github.com/PatrickKoss/baukit#readme
源码仓库：https://github.com/PatrickKoss/baukit

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

- 包体积（解压后）：102 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-08-25T18:46:05.930Z
- 最新版本发布：2026-11-07T02:35:40.976Z
- 近 30 天下载量：8270（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

被打入首选项及其更新行为,由产品提供存储和效果.

## 安装

```sh
npm install @baukit/preferences-core
```

也可以使用：`pnpm add @baukit/preferences-core`、`yarn add @baukit/preferences-core`、`bun add @baukit/preferences-core`

## README

# `@baukit/preferences-core`

`@baukit/preferences-core` 定义输入的首选项及其更新行为。 产品提供 定义、存储适配器,以及变化引起的任何影响.

## 更新模式

每个定义都提供密钥、默认值、规范度和范围。 水利读取商店, 实现每个存储字段的常态化,并填入其定义中遗漏的字段.

默认 `optimistic` 模式使本地更新立即可见,然后将其作为补丁写入. 如果写入失败,控制器会恢复之前的可见值并记录出错. 这仍然是兼容性的默认值 .

设定 `updateMode: "serialized"` 当每次更新必须从最新承诺值开始时:

```ts
const controller = createPreferenceController({
  definitions,
  store,
  updateMode: 'serialized',
  onVisibleChange: (values) => renderPreferences(values),
});
```

串行模式一次运行一个补丁. 它保持承诺值在写入时可见 待定和返回 `SerializedPreferenceControllerState` 从 `getState()`。 。 `pendingCount` 包括活动写入和每个队列写入. `onVisibleChange` 当计数时, 也运行 更改,即使数值参数没有改变。 无法写入的已承诺值 不变。 下个补丁仍然运行并使用上一个成功的结果.

打电话 `switchIdentity` 当认证对象改变时, 将使用下一个身份存储 。 这个 控制器在开始新读取前会发布默认值 。 慢读或写旧的 身份无法将身份的偏好恢复到可见状态 属于被替换身份的副作用失败不会降落在新的身份上.

打电话 `stop()` 当任何拥有的 `onVisibleChange` 离开,比如反应提供者 卸载。 飞行中的工作仍未结束 `getState()` 保持准确; 回调刚刚停止 开火 在序列化模式下,排队的写作在不出版的情况下继续反对被捕获的商店 之后 `stop()`消费者不需要自己的挂旗 `onVisibleChange`。 。 。 .

一个身份切换器取消了为旧身份所写的队列 。 已经寄给旧的书信 存储可以结算,但它不能发布值,也不能针对新存储启动已排队的旧补丁. 已取消的队列更新和对当前飞行中成功的 stale 更新解析 身份的价值观。 一个失败的飞行商店呼叫仍然以存储错误拒绝.

电线编码器通过检查有效载荷是否拥有一个场来区分出三个状态:

-   缺席意味着一个更古老的同位素没有发送设置,所以没有补丁;
-   无效是指同伴明确清除了一个无效的设置;
-   值包含设置的解码值.

可选的 TypeScript 属性本身并不带有这种区分.

## 副作用命令

默认政策是 `after-persistence`。 区域变化、许可提示、提醒 重新排期、分析变化和网络清空功能只应在本地 写入成功 。 每个钩子都声明 `onError: "report" | "ignore"`。报告的效果错误将保留 在控制状态下,持续和明显的偏好保持不变.

一些视觉变化需要即时预览. 定义可以选择采用 `preview-with-rollback`,提供预览操作,并提供倒数。 控制器 如果预览或持久性失败,则运行回滚。 其可选 `afterPersistence` 钩子还在 只在写完之后运行.

## 移徙

现有的呼叫者不需要改变. 没有电话 `updateMode` 仍然使用乐观的能见度 并且可能会有重叠的商店写作。 目前保持自己写队列的呼叫者可以 设定 `updateMode: "serialized"`读取 `pendingCount` 从 `getState()`,并删除队列。 他们 UI在等待更新时必须期望承诺的能见度.

## 储存适配器测试

实施适应器 `PreferenceStore.read` 财务报告和审定财务报表 `PreferenceStore.patch`导入 `describePreferenceStoreContract` 从 `@baukit/preferences-core/vitest` 运行共享的虚拟 合同。 该子路径仅为无害环境管理,没有 `default` 条件,所以杰斯特不能解决它. `InMemoryPreferenceStore` 适合测试和小的流程中消费者.

`RepositoryPreferenceStore` (或 `createRepositoryPreferenceStore`) 调整一个按键的寄存器 主题 id, 即大多数产品已经存储设置行的方式 。 给它存放 和两项预测:

```ts
const store = createRepositoryPreferenceStore({
  repository: repositories.settings,
  subjectId: userId,
  toValues: (record) => ({ mode: record.theme, accent: record.accent_color }),
  toRecordPatch: (patch) => ({
    ...(patch.mode === undefined ? {} : { theme: patch.mode }),
    ...(patch.accent === undefined ? {} : { accent_color: patch.accent }),
  }),
});
```

`toRecordPatch` 必须省去补丁没有携带的密钥,所以一个未触动的首选项永远不会 写回. `read` 决定: `undefined` 当仓库返回时 `null` 或者说 `undefined` 页:1 主题,也就是使控制器回到定义默认值.

## 边界

此软件包不会生成 SQL 、 选择存储计划、 运行迁移或设置 接口。 产品仍然决定存在哪些偏好,每个范围存储在哪里,哪些用户 以及同步有效载荷如何到达服务器.

## 常见问题

### @baukit/preferences-core 是什么？

被打入首选项及其更新行为,由产品提供存储和效果\.

### 如何安装 @baukit/preferences-core？

在项目目录运行 npm install @baukit/preferences-core，或使用 pnpm add / yarn add / bun add。

### @baukit/preferences-core 支持 TypeScript 吗？

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

### @baukit/preferences-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @baukit/preferences-core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @baukit/preferences-core 可以商用吗？

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

### @baukit/preferences-core 的下载量有多少？

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

### @baukit/preferences-core 还在维护吗？

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