# @hadoku/themes 中文文档

规范地址：https://npmcn.com/package/%40hadoku/themes/

版本：5\.14\.4
npm 元数据更新时间：2026-11-12T22:32:01.621Z
中文译文更新时间：2026-11-17T05:55:53.698Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：466 kB，70 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-10-28T06:27:53.798Z
- 最新版本发布：2026-11-12T22:32:01.253Z
- 近 30 天下载量：12511（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 58 个）

## 中文简介

16个主题配有对称,WCAG验证的代号集和完整的Tailwind v4色彩映射——光,暗,大洋,Cyberpunk,咖啡,拉文德,自然,平克,伊扎卡亚

## 安装

```sh
npm install @hadoku/themes
```

也可以使用：`pnpm add @hadoku/themes`、`yarn add @hadoku/themes`、`bun add @hadoku/themes`

## README

# @wolffm/主题

使用 CSS 自定义属性的美丽色彩主题 。 框架不可知,随时可用于任何网络项目.

## 主题

8个主题家庭(16个主题),每个主题都有光和暗的变体:

-   **光线** (默认) / **阴暗** - 清正的蓝色和白色 深夜有紫色口音
-   **海洋** 浅/暗 -- -- 深海蓝和热带珊瑚
-   **赛博朋克** 浅/暗 -- -- 有电色的霓虹堤道
-   **咖啡** 浅/暗 -- -- 浓咖啡和奶油
-   **薰衣草** 浅/暗 -- -- 柔软的紫色优雅
-   **性质** 浅/深 -- -- 由森林和地所激发的长叶绿地
-   **粉红色** 光/暗 -- -- 泡泡粉红色和霓虹光
-   **伊扎克亚** Light/Dark-被日本伊扎克雅所启发的取暖音调(基苏纳竞技胜出)

## 安装

```bash
npm install @wolffm/themes
```

## 使用量

### 导入 CSS

```javascript
import '@wolffm/themes/style.css'
```

### 使用主题工具

```typescript
import { setTheme, loadTheme, saveTheme, THEMES } from '@wolffm/themes'

// Set theme (applies immediately)
setTheme('dark')
setTheme('cyberpunk-dark')

// Save to sessionStorage and apply
saveTheme('lavender-light')

// Load saved theme on app start
const theme = loadTheme()

// Get all available themes
console.log(THEMES) // ['light', 'dark', 'coffee-light', ...]
```

### 应用到 HTML

```html
<!-- Set globally on html element -->
<html data-theme="dark">
  <!-- Or on a specific container -->
  <div data-theme="ocean-light">
    <!-- Your content -->
  </div>
</html>
```

### 第一帧前的访客主题画

一个设置的页面 `data-theme` 从捆绑的油漆 曾经没有线,然后 交换. `@wolffm/themes` 发布每个 hadoku 页的预绘脚本 位于顶端的内线 `<head>`: 它读取存储的选择( 或处理粘度) 随机黑暗主题给一个从未选择过的人), sets `data-theme` 在此之前 将决定公布为 `window.__hadokuTheme`编辑 标题 `src/theme-bootstrap.js` 记录它能解决和暴露的东西.

这一定是 **内入** 语句。 A 类 `<script src>`,模块或捆绑的脚本 在第一次涂料后运行,它打败了这一点。 采取两种方式之一:

```js
// As a string, for a build tool. Astro:
import { THEME_BOOTSTRAP } from '@wolffm/themes/theme-bootstrap'
// <script is:inline set:html={THEME_BOOTSTRAP} />
```

```js
// As the file's text, for a sync script that writes it between markers:
import { readFileSync } from 'node:fs'
import { createRequire } from 'node:module'
const path = createRequire(import.meta.url).resolve('@wolffm/themes/theme-bootstrap.js')
const source = readFileSync(path, 'utf8')
```

文本没有关闭脚本标记, 也没有 `<!--`这样它就可以进入一个 `<script>` 元素未脱逃( e)`test/theme-bootstrap.test.mjs` 执行). 这个 电话 `/session/whoami` 财务报告和审定财务报表 `/prefs/api/v1/portfolio` 通过相对的 URL,所以它的 截接设备 :`remember()`, (中文(简体) ), `adopt()`)只研究取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自. **永远不要把它复制到回扣中**: 导入它, 这样每个页面都会收到一个新的主题 有个版本的凸起.

## CSS 变量

每个主题定义47个变量(41个颜色+6个阴影). 颜色变量使用 `--color-*` 命名空间——它也是Tailwind v4的——所以它们直接映射到 公用事业。 其他东西都是空的 `--hdk-*` 避免与 尾风入内.

> **我用哪个代号来表示X?** → [`THEME_USAGE_GUIDE.md`](https://npmcn.com/package/%40hadoku/themes/THEME_USAGE_GUIDE.md)。 。 。 . 这是在写任何风格之前读取(和指点代理)的医生.

### 颜色——5个语义家庭×6个令牌

每个家庭都有一套相同的 矩是点: 对称猜想总是对的.

|  | 填满 | 梯度/压入 | 锡特 | 悬浮上方 | 填充时的文本 | 关于锡的文本 |
| --- | --- | --- | --- | --- | --- | --- |
| `primary` | `--color-primary` | `-dark` | `-bg` | `-hover` | `--color-on-primary` | `--color-on-primary-bg` |
| `success` | `--color-success` | `-dark` | `-bg` | `-hover` | `--color-on-success` | `--color-on-success-bg` |
| `warning` | `--color-warning` | `-dark` | `-bg` | `-hover` | `--color-on-warning` | `--color-on-warning-bg` |
| `danger` | `--color-danger` | `-dark` | `-bg` | `-hover` | `--color-on-danger` | `--color-on-danger-bg` |
| `neutral` | `--color-neutral` | `-dark` | `-bg` | `-hover` | `--color-on-neutral` | `--color-on-neutral-bg` |

### 颜色——结构

-   `--color-text` (+ 数) `-secondary`, (中文(简体) ), `-tertiary`, (中文(简体) ), `-muted`(中文(简体) )
-   `--color-border` (+ 数) `-light`(中文(简体) )
-   `--color-bg` (+ 数) `-card`, (中文(简体) ), `-alt`, (中文(简体) ), `-hover`, (中文(简体) ), `-overlay`(中文(简体) )

每个 `on-*` 双子被校验为 : 4.5: 1 相对于每个主题的表面 `scripts/check-contrast.mjs`。 。 。 .

### 类型

-   `--font-family`
-   `--hdk-text-*` (xs, sm, md, base, lg) - 字体大小
-   `--font-weight-*` (正常,半粗体,粗体)
-   `--line-height-*` (正常,放松)

### 间距

-   `--hdk-space-*` (xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl)

### 版式

-   `--hdk-radius` (+ sm, lg 变体) - 边框半径
-   `--hdk-shadow-*` (sm, md, lg, 聚焦, 聚焦- sm, 聚焦- alt)

### 过渡

-   `--transition-fast`
-   `--transition-smooth`

### 用法示例

```css
.my-button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  padding: var(--hdk-space-md) var(--hdk-space-xl);
  border-radius: var(--hdk-radius);
  font-size: var(--hdk-text-base);
  box-shadow: var(--hdk-shadow-sm);
  transition: var(--transition-fast);
}

.my-button:hover {
  background: var(--color-primary-dark);
  box-shadow: var(--hdk-shadow-md);
}
```

## 尾风 v4 兼容性

此软件包使用命名空格 CSS 变量(`--hdk-*`)来避免与Tailwind v4的内部变量相撞.

### 为甚么取名相?

Tailwind v4 内部使用 CSS 自定义属性 :

-   `--spacing-*` 权限 `max-w-md`, (中文(简体) ), `p-4`, (中文(简体) ), `gap-*`等 (中文(简体) ).
-   `--radius-*` 权限 `rounded-md`, (中文(简体) ), `rounded-lg`等 (中文(简体) ).
-   `--font-size-*` 权限 `text-sm`, (中文(简体) ), `text-base`等 (中文(简体) ).
-   `--shadow-*` 权限 `shadow-sm`, (中文(简体) ), `shadow-md`等 (中文(简体) ).

没有命名间隔, 主题变量像 `--spacing-md: 8px` 将打破 `max-w-md` (从28rem改为8px).

### 变量映射

| 旧名( v1. x) | 新名称( v2. x) |
| --- | --- |
| `--spacing-md` | `--hdk-space-md` |
| `--font-size-sm` | `--hdk-text-sm` |
| `--border-radius` | `--hdk-radius` |
| `--shadow-sm` | `--hdk-shadow-sm` |
| `--shadow-modal` | `--hdk-shadow-lg` |

### 尾风集成

3个进口,没有手写 `@theme` 块 :

```css
@import '@wolffm/themes/style.css'; /* 1. tokens — MUST be unlayered */
@import 'tailwindcss'; /* 2. Tailwind */
@import '@wolffm/themes/tailwind-colors.css'; /* 3. all 41 colours */
@import '@wolffm/themes/tailwind-integration.css'; /* 4. radius/shadow/type (optional) */
```

你现在得到 `bg-primary`, (中文(简体) ), `text-on-primary`, (中文(简体) ), `bg-success-bg`, (中文(简体) ), `text-on-danger-bg`, (中文(简体) ), `border-border`, (中文(简体) ), `bg-bg-card` 每一个标志,作为一个效用.

**永远不要手卷 `@theme` 颜色块.** 本地拷贝就是漂移 此软件包的存在是为了防止; `tailwind-colors.css` 从 `style.css` 如果两者意见不一,CI就会失败.

**步骤1必须保持不下层.** 尾风各喷出 `@theme` 进入 `@layer theme` 作为 `:root { --x: var(--x) }`,这是自我优惠和 自行无效。 它解决仅仅因为 `style.css` 声明如下: 任何级联层外的属性, 和无层取胜。 导入它 `layer(...)` 和所有41个颜色 沉默地变成 `transparent`。 。 。 .

`tailwind-integration.css` (步骤4)是单独和可选的——它地图 `--hdk-*` 半径/ 阴影/ 类型进入 `rounded-*`, (中文(简体) ), `shadow-*`, (中文(简体) ), `text-*`。 。 。 .

### V1.x的迁移

在您的 CSS 中搜索并替换 :

```
var(--spacing-       →  var(--hdk-space-
var(--font-size-     →  var(--hdk-text-
var(--border-radius  →  var(--hdk-radius
var(--shadow-        →  var(--hdk-shadow-
var(--shadow-modal)  →  var(--hdk-shadow-lg)
```

## 反应集成

### 使用 `useTheme` Hook (建议)

```tsx
import { useTheme, THEME_FAMILIES, THEME_ICON_MAP } from '@wolffm/themes'
import { ConnectedThemePicker } from '@wolffm/task-ui-components'
import '@wolffm/themes/style.css'
import '@wolffm/task-ui-components/theme-picker.css'

function App() {
  const { theme, setTheme } = useTheme()

  return (
    <ConnectedThemePicker
      themeFamilies={THEME_FAMILIES}
      currentTheme={theme}
      onThemeChange={setTheme}
      getThemeIcon={theme => {
        const Icon = THEME_ICON_MAP[theme]
        return Icon ? <Icon /> : null
      }}
    />
  )
}
```

### 手动反应集成

```tsx
import { useEffect, useState } from 'react'
import { loadTheme, setTheme, THEMES, type Theme } from '@wolffm/themes'
import '@wolffm/themes/style.css'

function App() {
  const [theme, setThemeState] = useState<Theme>('light')

  useEffect(() => {
    const savedTheme = loadTheme()
    setThemeState(savedTheme)
  }, [])

  const handleThemeChange = (newTheme: Theme) => {
    setTheme(newTheme)
    setThemeState(newTheme)
  }

  return (
    <select value={theme} onChange={e => handleThemeChange(e.target.value as Theme)}>
      {THEMES.map(t => (
        <option key={t} value={t}>
          {t}
        </option>
      ))}
    </select>
  )
}
```

## 框架实例

### 阴道

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { loadTheme, setTheme, THEMES, type Theme } from '@wolffm/themes'
import '@wolffm/themes/style.css'

const theme = ref<Theme>('light')

onMounted(() => {
  theme.value = loadTheme()
})

const handleThemeChange = (newTheme: Theme) => {
  setTheme(newTheme)
  theme.value = newTheme
}
</script>

<template>
  <select v-model="theme" @change="handleThemeChange(theme)">
    <option v-for="t in THEMES" :key="t" :value="t">{{ t }}</option>
  </select>
</template>
```

### 香草联署材料

```javascript
import { loadTheme, setTheme, THEMES } from '@wolffm/themes'
import '@wolffm/themes/style.css'

// Load saved theme on page load
document.addEventListener('DOMContentLoaded', () => {
  loadTheme()

  // Theme switcher
  const select = document.getElementById('theme-select')
  THEMES.forEach(theme => {
    const option = document.createElement('option')
    option.value = theme
    option.textContent = theme
    select.appendChild(option)
  })

  select.addEventListener('change', e => {
    setTheme(e.target.value)
  })
})
```

## 主题编辑器

主办地点 **[https://hadoku.me/ 任务/编辑\*](https://hadoku.me/task/editor*)\* (服务级别及以上)。 选一个主题, 拖动滑动器,而该应用程序的真正组件会重新显示颜色; **保存** 承诺 改为 `main` 以新的版本出版.**

-   **每一个标志** ——亮度/饱和度/hue/不透明滑块(OKLCH,故作 亮度阶梯看起来甚至横穿花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花
-   **每组** ——地表,文字和每个语义家族可一并转移
-   **合同** - 同样的支票 `lint:css` 运行( r)`scripts/lib/contract.mjs`, (中文(简体) ), 导出为 `@wolffm/themes/contract`),活;一个失败块保存和 执行前保存路径再检查
-   **舒适** ——AA看不到的咨询仪表:页面闪光,卡-vs-页面 分隔、边界可见度、文本严酷度以及是否 `success` 编号 : `warning` 编号 : `danger` 仍然读作意义

编辑是 `@wolffm/task/editor` (弧/编辑/在还原根中);其 保存路径 `worker/src/routes/theme-editor.ts`在本地, `pnpm run dev:api` 加号 `vite` 服务于 `/editor.html` 以纪念吉特胡卜为对象 永远不要碰真正的回放.

## API 参考

### 反应公用事业(在v1.1.3+中新建)

#### `useTheme(): { theme: Theme, setTheme: (theme: Theme) => void }`

状态主题管理反应钩. 自动保存到会话Storage并同步跨标签.

```tsx
const { theme, setTheme } = useTheme()
```

#### `THEME_FAMILIES: ThemeFamily[]`

预配置了所有8个有图标和标签的主题家族的阵列. 使用方式 `ThemePicker` 或者说 `ConnectedThemePicker` 组件从 `@wolffm/task-ui-components`。 。 。 .

```tsx
import { THEME_FAMILIES } from '@wolffm/themes'
// Each family includes: lightTheme, darkTheme, lightLabel, darkLabel, lightIcon, darkIcon
```

#### `THEME_ICON_MAP: Record<Theme, IconComponent>`

主题名称地图到它们相应的图标组件.

```tsx
import { THEME_ICON_MAP } from '@wolffm/themes'
const Icon = THEME_ICON_MAP['cyberpunk-dark']
```

### 核心职能

#### `setTheme(theme: Theme): void`

立即应用主题 。 设定 `data-theme` 属性 `<html>` 键.

#### `getTheme(): Theme`

获取当前活动主题 .

#### `saveTheme(theme: Theme): void`

将主题保存到会话Storage并应用它 .

#### `loadTheme(): Theme`

从会话Storage上装入所保存的主题, 应用它, 并返回主题名称 。 尊重浏览器 `prefers-color-scheme` 如果未保存主题, 则优先选择 。 如果没有选择, 返回“ 光 ” .

#### `initTheme(): Theme`

方便功能. 与 `loadTheme()`。 。 。 .

#### `clearTheme(): void`

删除已保存的主题并重置为"光" .

### 类型

```typescript
type Theme =
  | 'light'
  | 'dark'
  | 'ocean-light'
  | 'ocean-dark'
  | 'cyberpunk-light'
  | 'cyberpunk-dark'
  | 'coffee-light'
  | 'coffee-dark'
  | 'lavender-light'
  | 'lavender-dark'
  | 'nature-light'
  | 'nature-dark'
  | 'pink-light'
  | 'pink-dark'
  | 'izakaya-light'
  | 'izakaya-dark'

const THEMES: readonly Theme[]
```

## 浏览器支持

在所有支持的现代浏览器中工作:

-   CSS 自定义属性( CSS 变量)
-   ES2022 模块
-   会话集

## 许可证

麻省理工学院

## 作者

沃尔夫M - [GitHub 图像](https://github.com/WolffM)

## 相关软件包

-   [@ wolffm/ 任务](https://github.com/WolffM/hadoku-task) - 使用这些主题的任务管理微前端

## 常见问题

### @hadoku/themes 是什么？

16个主题配有对称,WCAG验证的代号集和完整的Tailwind v4色彩映射——光,暗,大洋,Cyberpunk,咖啡,拉文德,自然,平克,伊扎卡亚

### 如何安装 @hadoku/themes？

在项目目录运行 npm install @hadoku/themes，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hadoku-check-icons、hadoku-codemod-icons，可以用 npx hadoku-check-icons 直接运行。

### @hadoku/themes 支持 TypeScript 吗？

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

### @hadoku/themes 支持 ESM 还是 CommonJS？

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

### @hadoku/themes 可以商用吗？

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

### @hadoku/themes 的下载量有多少？

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

### @hadoku/themes 还在维护吗？

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

