API 参考 · 浏览器 Runtime

@oriatheme/runtime-dom

浏览器端外部 store、原子 DOM 应用、持久化、Bootstrap 与 View Transition。

包与运行环境

SSR 导入安全；start、Storage 和 DOM 写入只在浏览器执行。

bash

pnpm add @oriatheme/presets @oriatheme/runtime-dom

bash

npm install @oriatheme/presets @oriatheme/runtime-dom

bash

yarn add @oriatheme/presets @oriatheme/runtime-dom

bash

bun add @oriatheme/presets @oriatheme/runtime-dom

选择使用方项目已有的一种包管理器和 lockfile；示例只使用 package root export，不要从 src、dist 或 registry template 深层导入。

工厂与首屏 API

出口	签名	描述
`createOriaThemeRuntime`	`(config: OriaThemeConfig) => OriaThemeRuntime`	创建 SSR 安全存储和客户端 DOM 运行时。
`bootstrapTheme`	`(options?: BootstrapOptions) => void`	在框架安装之前应用一个有效的活动快照。
`createBootstrapScript`	`(options: BootstrapOptions) => string`	为调用者提供的快照创建一个独立的脚本。
`createBootstrapStorageScript`	`(options?) => string`	创建头部安全的 LocalStorage 引导脚本。

import { bootstrapTheme, createOriaThemeRuntime } from "@oriatheme/runtime-dom";
import { oriaPresetThemes } from "@oriatheme/presets";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
const runtime = createOriaThemeRuntime({
  presets: oriaPresetThemes,
  defaultThemeId: "oria-default",
});
runtime.start();

OriaThemeRuntime

出口	签名	描述
`start / destroy`	`() => void`	附加或释放浏览器侦听器和 DOM 所有权。
`getSnapshot / subscribe`	`() => ThemeSnapshot / (listener) => unsubscribe`	阅读或订阅外部商店。
`setTheme / setAppearance`	`(id \| mode, options?) => void`	选择现有主题或用户偏好；可以动画化明确的动作。
`createCustomTheme`	`({ theme }) => ThemeDefinition`	保留完整有效的自定义主题。
`updateCustomTheme`	`(id, patch, options?) => ThemeDefinition`	仅更新现有的自定义主题。
`duplicateTheme / removeCustomTheme`	`(id, identity) => ThemeDefinition / (id) => void`	复制预设/自定义主题或删除自定义主题。
`previewTheme`	`(theme, mode?) => PreviewHandle`	应用有效的内存中预览； dispose 恢复正式状态。
`exportTheme / importTheme`	`(id) => string / (json, options?) => ThemeDefinition`	导出已保存的主题或导入经过充分验证的自定义主题。
`reset`	`() => void`	将运行时首选项和自定义状态返回到其初始配置。

重要类型与边界

OriaThemeConfig 要求 presets 和 defaultThemeId；contract 默认 oria-standard@2，migrations 显式注册后才接受 v1 持久化主题（否则安全拒绝）。BootstrapOptions.contract 声明后只恢复完全匹配的 snapshot。ThemeSnapshot 提供 preference、resolvedMode、resolvedTheme、preset/custom 列表和 error。ThemeStorage 可替换默认持久化，ThemeChangeOptions 的 animate 只用于显式用户操作。persist appearance，绝不持久化 resolvedMode。