应用开发者

开发快速开始

在 React、Vue 或原生 Web 应用中用公开包启动 Runtime，并让现有组件立即响应主题。

安装与你的框架匹配的包

在使用方项目中只从 npm 安装公开包，并沿用项目已有的包管理器和 lockfile。

bash

# React
pnpm add @oriatheme/presets @oriatheme/runtime-dom @oriatheme/react

# Vue 3
pnpm add @oriatheme/presets @oriatheme/runtime-dom @oriatheme/vue

# Framework-free web
pnpm add @oriatheme/presets @oriatheme/runtime-dom

在挂载前恢复，再让 Runtime 接管

先运行 Bootstrap 恢复上次成功保存的快照，再在框架挂载时启动完整 Runtime。它会重新校验状态、处理 system 外观并原子写入变量。

React

tsx

import { createRoot } from "react-dom/client";
import { OriaThemeProvider, useOriaTheme } from "@oriatheme/react";
import { oriaPresetThemes } from "@oriatheme/presets";
import { bootstrapTheme } from "@oriatheme/runtime-dom";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });

function Controls() {
  const { setTheme, setAppearance } = useOriaTheme();
  return <>
    <button onClick={() => setTheme("oria-ocean")}>Ocean</button>
    <button onClick={() => setAppearance("dark")}>Dark</button>
  </>;
}

createRoot(document.querySelector("#root")!).render(
  <OriaThemeProvider config={{ presets: oriaPresetThemes, defaultThemeId: "oria-default" }}>
    <Controls />
  </OriaThemeProvider>,
);

Vue

import { createApp } from "vue";
import { createOriaTheme } from "@oriatheme/vue";
import { oriaPresetThemes } from "@oriatheme/presets";
import { bootstrapTheme } from "@oriatheme/runtime-dom";
import App from "./App.vue";

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
createApp(App)
  .use(createOriaTheme({ presets: oriaPresetThemes, defaultThemeId: "oria-default" }))
  .mount("#app");

原生 Web

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

bootstrapTheme({ contract: { name: "oria-standard", version: 2 } });
const runtime = createOriaThemeRuntime({
  presets: oriaPresetThemes,
  defaultThemeId: "oria-default",
});
runtime.start();
runtime.setTheme("oria-ocean");
runtime.setAppearance("system");
// Call runtime.destroy() when the app is removed.

在示例应用中查看完整集成

三个官方示例与本文的代码一一对应，可直接在 GitHub 浏览或克隆运行。

React + Vite

React 示例应用

Provider 接入、Token gallery 与按需本地编辑器。

Vue 3 + Vite

Vue 示例应用

Plugin 接入，与 React 共用同一 Runtime 状态机。

Next.js App Router

Next.js 示例应用

SSR 默认 CSS、首屏 Bootstrap 与按需编辑器。

确认结果

html 获得 data-oria-theme、data-oria-mode 和正确的 color-scheme。
切换主题时，颜色、圆角、阴影等变量会一起更新。
持久化的是 light、dark 或 system 偏好，绝不是 resolvedMode。

接下来：让组件使用语义 Token