# @hadoku/prefs-client 中文文档

规范地址：https://npmcn.com/package/%40hadoku/prefs-client/

版本：1\.1\.27
npm 元数据更新时间：2026-11-12T21:56:44.971Z
中文译文更新时间：2026-11-17T06:00:41.561Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40hadoku/prefs-client
原文对照：https://npmcn.com/package/%40hadoku/prefs-client/?lang=original
项目主页：https://github.com/WolffM/hadoku_site#readme
源码仓库：https://github.com/WolffM/hadoku_site

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

- 包体积（解压后）：135 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- peer 依赖：zod ^4\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-10-28T06:26:49.345Z
- 最新版本发布：2026-11-12T21:56:44.751Z
- 近 30 天下载量：8269（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

客户端 SDK 为 hadoku 统一首选项商店 。 用本地Storage caching、已解禁的写作、Zod-校验的读取以及使用Prefs()来包装/prefs/api/v1/\* 反应钩子,外加每款游戏的相配历史,收视率和领跑板(./游戏),一款再解

## 安装

```sh
npm install @hadoku/prefs-client
```

也可以使用：`pnpm add @hadoku/prefs-client`、`yarn add @hadoku/prefs-client`、`bun add @hadoku/prefs-client`

## README

# @wolffm/ prefs-客户端

客户端 SDK 为 hadoku 统一首选项商店 。 环绕 `hadoku.me/prefs/api/v1/*` 与本地 Storage 缓冲, 解开的写作, Zod - 验证读取, 和反应 `usePrefs()` 钩.

见 [`docs/planning/unified-prefs-2026-05-20.md`](https://github.com/WolffM/hadoku_site/blob/main/docs/planning/unified-prefs-2026-05-20.md) 关于建筑背景.

## 安装

```sh
pnpm add @wolffm/prefs-client zod
# React consumers also:
pnpm add react
```

## 使用量

```ts
import { z } from 'zod';
import { createPrefsClient } from '@wolffm/prefs-client';
import { usePrefs } from '@wolffm/prefs-client/react';

const TaskPrefsSchema = z.object({
  theme: z.string().optional(),
  themeMode: z.enum(['simple', 'advanced']).optional(),
  alwaysVerticalLayout: z.boolean().optional(),
});

export const taskPrefs = createPrefsClient({
  appId: 'task',
  schema: TaskPrefsSchema,
  defaults: { theme: 'light', themeMode: 'simple' },
  migrations: [
    (blob) => {
      if ('simpleMode' in blob) {
        blob.themeMode = blob.simpleMode ? 'simple' : 'advanced';
        delete blob.simpleMode;
      }
      return blob;
    },
  ],
  bootstrapToSessionStorage: { theme: 'hadoku-theme' },
});

function Settings() {
  const { prefs, save, loading } = usePrefs(taskPrefs);
  if (loading || !prefs) return null;
  return (
    <ThemeToggle
      value={prefs.theme}
      onChange={(t) => save({ theme: t }, { scope: 'device' })}
    />
  );
}
```

## 关键行为

-   **缓存**: 局部积分 `prefs-cache:{userId}:{appId}`{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}暂停 重审.
-   **写作**: 1s-已解开的PUT. 多个 `save()` 窗口内的呼叫连接到一个网络呼叫.
-   **冲突**:API-永远-Wins. 在409上,SDK采用服务器blob并重置;本地补丁被丢弃 `save()` (有明确的 `expectedVersion`)或(或) `flush()` 等待它来临的时候 `PrefsConflictError`。 。 。 .
-   **`expectedVersion`**:默认情况下,SDK发送它所看到的上个版本(在第一次读取前为0). `save(patch, { expectedVersion: n })` 发送 `n`· ; `{ expectedVersion: null }` 发件人无一胜负 。 二者即发而出而出而出.
-   **交叉标签**: 广播频道按键 `prefs:{userId}:{appId}` 传播在标签之间保存, 而无需服务器绕行 .
-   **Anon – 认证**: 调用 `client.promoteAnonPrefsToUser()` 注册后。 如果服务器已经拥有用户瞄准镜预览(先在另一个设备上签名),则服务器获胜.
-   **脏地保护**:一个背景刷新(或即将到来的跨塔布广播)从不覆盖一个保留待决/正在飞行的字段——它将服务器/远程blob与你未经证实的本地值合并。 否则,在乐观的写作与其被取消的PUT之间重新起落,显然会使变化恢复.
-   **FOUC 拖带**数字 : `bootstrapToSessionStorage` 镜像特定字段到会话Storage 这样内含 `<head>` 脚本可以在React Mounts前应用主题. 只在显式本地镜像 `save()` 默认情况下——从不读取/水合物/再生/广播-接收——所以嵌入在拥有同一种会话Storage密钥的主机下的应用程序不能仅仅用启动来击打它. 过 `mirrorBootstrapOnRead: true` 以恢复旧的每张读取的镜像,以取出一个密钥.

## 电容器(本地APK)

存储为 **自动检测**: 在本地 Capacitor 网页视图中, SDK 读取 页:1 `Capacitor.Plugins.Preferences` 全局并用于缓存; a 它使用本地Storage浏览器. 没有配置,没有导入,以及 **没有 `@capacitor/preferences` 添加到网络捆绑中的依赖性** - 探测器 是一个运行时间全局读取,所以只使用网络的消费者不会受到影响.

对土著方面的要求:

-   APK主机必须拥有 `@capacitor/preferences` 已安装( 所以电容) 注册全局插件)。 SDK不捆绑或导入.
-   APK薄荷薄荷本身 `hadoku_device_id` 在本地存储中,与 移动浏览器的——所以本地应用程序和移动Safari是两个 设计上不同的设备.

您仍可以通过一个明确的适配器(或在测试中强制1)来覆盖 `createPrefsClient({ storage })`。 。 。 . `detectStorage()` 财务报告和审定财务报表 `capacitorStorage()` 如果您想要自行解析适配器,则导出.

## 标题-模式(服务对服务,无饼干)

过 `userKey` 当没有 `hadoku_session` 要骑的饼干(例如CLI) 或者用生钥匙而不是饼干认证的本地应用程序 :

```ts
const client = createPrefsClient({
  appId: 'task-mobile',
  schema: TaskPrefsSchema,
  userKey: process.env.HADOKU_API_KEY,
  // storage auto-detects Capacitor; pass an explicit adapter only to override
});
```

## 平台行数( O)`@wolffm/prefs-client/platform`(中文(简体) )

属于没有单一应用程序的行. 导入定义,而不是重制应用程序, 范围与计划,所以第二个需要设置的应用程序会找到第一行而不是 发明它自己的.

| 行数 | 字段 | 范围 | 拥有者 |
| --- | --- | --- | --- |
| `games` (单位:千美元)`GAMES_ROW`(中文(简体) ) | `muted`, (中文(简体) ), `volume` (0.1项) | 设备 | 每款大写游戏: 主音, 高于游戏本身的关卡 |
| `portfolio` | `theme` | 设备 | `@wolffm/themes`; 不要从应用程序中写入 |

```ts
import { createPrefsClient } from '@wolffm/prefs-client';
import { GAMES_ROW, GAMES_DEFAULTS } from '@wolffm/prefs-client/platform';

const games = createPrefsClient({ ...GAMES_ROW, defaults: GAMES_DEFAULTS });
await games.save({ muted: true }, { scope: GAMES_ROW.scope });
```

这里的剖面图不是一行:它是 `./avatar` 下面,它的倒置是 守望会角色.

## 阿凡达人( O)`@wolffm/prefs-client/avatar`(中文(简体) )

由用户在机队设置中选择的每个有色人种用户一个解析的变形符弹出 (单位:千美元)`ConnectedSettings`, @wolffm/ task-ui- 组件:图片的来源及其特性.

```ts
interface ResolvedAvatar {
  source: 'sprite' | 'discord' | 'steam' | 'upload'; // what the picture is
  url?: string; // present exactly when source !== 'sprite': square https image, >= 184px
  sprite?: string; // the person's character, WHATEVER the source; absent = your default
}
```

浏览器, 登录用户本身的外观 :

```ts
import { createAvatarClient } from '@wolffm/prefs-client/avatar';
const { avatar } = await createAvatarClient().get(); // AvatarSettings
```

服务器,每个在房间里的人, by userId, 与服务器的服务级密钥:

```ts
import { resolveAvatars } from '@wolffm/prefs-client/avatar';
const byUser = await resolveAvatars(
  { serviceKey: process.env.SERVICE_KEY! },
  userIds
);
// every requested id is present; unknown users resolve to { source: 'sprite', name: null }
byUser[id].name; // their live display name, or null for an unknown or closed account
```

**名字也来自这里.** 一个服务器只存储用户IDENTY MODEL R12和名称 人们,无论在线与否,当它显示: `resolveAvatars(...)[id].name`永远不留副本. prefs-api每次隔离最多一分钟读一次登记册,所以重命名显示在 分钟后,一个被删除的账户停止命名。 超过HTTP了 `POST /prefs/api/v1/_avatar/resolve` `{ userIds }` 服务级 `X-User-Key`。 。 。 .

成像程序的规则:

-   **`url` → `<img src>`**,没有其它:从服务器端获取,从代理端获取. 设定 `referrerpolicy="no-referrer"`。一个 URL 可以停止工作( 更改 Discord 图片, 管理器) 删除 : `error`倒回宝石.
-   **`sprite`** 即使图片是 Discord 化身, 也是字符: 游戏使用它作为 块及其颜色。 拥有该艺术的应用程序会构建其URL(watchparte拥有艺术修改; 公众 `GET /watchparty/api/characters` 清单。 没有就用你自己的默认.
-   不要使用Steam的或Discord的标志,也不暗示要认可该应用.
-   决心加入和重新连接;变相者很少改变. `resolveAvatars` 超过100个身份证.
-   源选择,字符选择,链接(`linkInPopup`: 无页面导航、上传和 删除所有在设置弹出时发生 。 别自建.

## 阿凡达化妆品`@wolffm/prefs-client/cosmetics`(中文(简体) )

一个人穿什么 与他们的相貌:一个名字 **效果**,名称 **渐变**,名称 **字体**,一个 阿凡达 **覆盖** (一个人可以移动、转动和调整大小的图像,或被画出环形或发光),以及 **消息** 为他们的聊天线透露。 物品是赚取或赠与的,从未购买;每分槽一个. 人们在环境流行的相机对话框中装备他们. 每个有决心的阿凡达都带着 旧为 `cosmetics` (单位:千美元)`ResolvedAvatar.cosmetics`,只有个人拥有的物品.

```ts
import {
  ensureCosmeticsStyles,
  colourStyle,
  nameHtml,
  avatarHtml,
  messageHtml,
} from '@wolffm/prefs-client/cosmetics';

ensureCosmeticsStyles(); // once: the stylesheet, and the clean-up that ends a message reveal
const worn = person.cosmetics; // from resolveAvatars() or the owner's settings
row.style.cssText = colourStyle(character.color); // every text colour derives from this
row.innerHTML =
  avatarHtml({ src: pictureUrl, size: 40, worn }) +
  nameHtml(person.name, worn) +
  messageHtml(text, live ? worn : undefined); // reveal only messages arriving live
```

一项应用的规则使得它们:

-   **颜色来自字符.** 把角色的颜色放进去 `--hc-base` 排行图 (单位:千美元)`colourStyle`) (中文(简体) ). 从不给名字效果或渐变它自己的颜色.
-   **只播放现场信息**,从历史或回滚负载。 揭示的结尾是纯文本.
-   **暂停屏幕关闭的内容**: 切换 `hc-idle` 在行中隐藏一个交叉区观察员报告.
-   **留有铺放地.** 覆盖可能达到它上面的三分之一大小 和每方四分之一`PLACEMENT_ZONE`不要剪掉阿凡达的盒子.
-   图像和字体从 `/cosmetics/` (站点名) `public/cosmetics`; 字体 只有在有人戴时才下载.
-   添加项目: `COSMETICS` 内 `cosmetics-contract.ts`,其CSS在 `cosmetics.ts`,在 `public/cosmetics/art/`。 。 。 . `test/cosmetics.test.ts` 如果缺少其中任何一项,则失败,如果 循环动画中除了变形或不透明之外任何东西.

## 常见问题

### @hadoku/prefs-client 是什么？

客户端 SDK 为 hadoku 统一首选项商店 。 用本地Storage caching、已解禁的写作、Zod-校验的读取以及使用Prefs\(\)来包装/prefs/api/v1/\* 反应钩子,外加每款游戏的相配历史,收视率和领跑板\(\./游戏\),一款再解

### 如何安装 @hadoku/prefs-client？

在项目目录运行 npm install @hadoku/prefs-client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hadoku/prefs-client 支持 TypeScript 吗？

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

### @hadoku/prefs-client 支持 ESM 还是 CommonJS？

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

### @hadoku/prefs-client 需要什么版本的 Node\.js？

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

### @hadoku/prefs-client 可以商用吗？

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

### @hadoku/prefs-client 的下载量有多少？

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

### @hadoku/prefs-client 还在维护吗？

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

