@wolffm/ prefs-客户端
客户端 SDK 为 hadoku 统一首选项商店 。 环绕 hadoku.me/prefs/api/v1/* 与本地 Storage 缓冲, 解开的写作, Zod - 验证读取, 和反应 usePrefs() 钩.
见 docs/planning/unified-prefs-2026-05-20.md 关于建筑背景.
安装
pnpm add @wolffm/prefs-client zod
# React consumers also:
pnpm add react
使用量
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)
或者用生钥匙而不是饼干认证的本地应用程序 :
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; 不要从应用程序中写入 |
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- 组件:图片的来源及其特性.
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
}
浏览器, 登录用户本身的外观 :
import { createAvatarClient } from '@wolffm/prefs-client/avatar';
const { avatar } = await createAvatarClient().get(); // AvatarSettings
服务器,每个在房间里的人, by userId, 与服务器的服务级密钥:
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,只有个人拥有的物品.
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如果缺少其中任何一项,则失败,如果 循环动画中除了变形或不透明之外任何东西.