# @duskmoon-dev/core 中文文档

规范地址：https://npmcn.com/package/%40duskmoon-dev/core/

版本：1\.21\.5
npm 元数据更新时间：2026-11-11T17:15:45.269Z
中文译文更新时间：2026-11-13T00:42:52.835Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：5.7 MB，295 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：tailwindcss ^4\.0\.0
- 首次发布：2025-10-26T12:38:20.679Z
- 最新版本发布：2026-11-11T17:15:44.496Z
- 近 30 天下载量：38922（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 67 个）

## 中文简介

Dusk MoonUI - 有材料设计 3 颜色系统和组件样式的 Tailwind CSS v4 插件

## 安装

```sh
npm install @duskmoon-dev/core
```

也可以使用：`pnpm add @duskmoon-dev/core`、`yarn add @duskmoon-dev/core`、`bun add @duskmoon-dev/core`

## README

# @duskmoon-dev/core (日语)

> DuskMoonUI - 一个有材料设计 3 色彩系统和 49 个组件样式的 Tailwind CSS v4 插件

[![npm version](https://img.shields.io/npm/v/@duskmoon-dev/core.svg)](https://www.npmjs.com/package/@duskmoon-dev/core) [![npm downloads](https://img.shields.io/npm/dm/@duskmoon-dev/core.svg)](https://www.npmjs.com/package/@duskmoon-dev/core) [![bundle size](https://img.shields.io/bundlephobia/minzip/@duskmoon-dev/core)](https://bundlephobia.com/package/@duskmoon-dev/core) [![license](https://img.shields.io/npm/l/@duskmoon-dev/core.svg)](https://github.com/duskmoon-dev/duskmoonui/blob/main/LICENSE)

## 特征

-   🎨 **三色系统** - 有自动内容颜色的初级、二级和三级品牌颜色
-   🌓 **内建主题** - 已准备好使用的阳光(光)和月光(暗)主题
-   📦 **55+ 材料设计 3 个颜色符号** - 具有OKLCH格式的完整的MD3颜色系统
-   🧩 **49个UI组件** - 完成结构一致的组件库
-   🚀 **零运行时间联署材料** - 纯 CSS 有 CSS 自定义属性用于主题切换
-   ♿ **默认可访问** - WCAG AA符合比比(4.5:1最低)
-   🎯 **尾风 v4 本地** - 纯CSS使用 `@import`,没有 JavaScript 配置
-   📦 **小捆绑** - 低于7KB克齐普

## 安装

```bash
# Using Bun (recommended)
bun add @duskmoon-dev/core tailwindcss@^4.0.0

# Using npm
npm install @duskmoon-dev/core tailwindcss@^4.0.0

# Using pnpm
pnpm add @duskmoon-dev/core tailwindcss@^4.0.0
```

## 土著重叠原则

-   工具提示只使用 HTML Popover API : `popover="hint"`, (中文(简体) ), `interestfor`浏览器 `:popover-open` 状态.
-   模块和对话框只使用 HTML `<dialog>`打开 `command="show-modal"` 编号 : `commandfor` 或者说 `showModal()`并关闭 与本地命令, `close()`,或 `method="dialog"`。浏览器管理背景、惰性、键盘焦点和逃逸.

遗留的Div标记, `.modal-open`, (中文(简体) ), `.modal-toggle`,并且不再支持 URL-目标能见度。 将外出元素迁移到 `<dialog>` 并使用本地的开放/关闭行动; `.modal-box` 并保留修改格式.

## 快速启动

### 1\. 在您的CSS中添加 Dusk MoonUI

#### 备选案文A:支助和服务 `@import` (建议)

```css
/* src/styles.css */
@import "tailwindcss";
@import "@duskmoon-dev/core";
```

#### 备选案文B:尾风 `@plugin` 指令

```css
/* src/styles.css */
@import "tailwindcss";
@plugin "@duskmoon-dev/core/plugin";
```

这个 `@plugin` 方法将物质设计 3 个颜色符号直接输入到 Tailwind 的主题中,从而能够像 `bg-primary`, (中文(简体) ), `text-on-surface`等 (中文(简体) ). 当您需要 Tailwind- aware 彩色工具时使用此功能, 并附带组件样式 .

### 2\. 将主题属性添加到您的 HTML

```html
<html data-theme="sunshine">
  <body>
    <button class="btn btn-primary">Click me</button>
  </body>
</html>
```

### 3\. 使用彩色公用事业

```html
<!-- Brand colors -->
<div class="bg-primary text-primary-content">Primary</div>
<div class="bg-secondary text-secondary-content">Secondary</div>
<div class="bg-tertiary text-tertiary-content">Tertiary</div>

<!-- Surface colors -->
<div class="bg-surface text-on-surface">Surface</div>
<div class="bg-surface-container">Container</div>

<!-- Semantic colors -->
<div class="bg-success text-success-content">Success</div>
<div class="bg-error text-error-content">Error</div>
```

## 主题切换

通过更改主题切换 `data-theme` 属性 - 不需要 JavaScript :

```html
<!-- Light theme -->
<html data-theme="sunshine">

<!-- Dark theme -->
<html data-theme="moonlight">
```

主题切换是即时的并使用纯 CSS 自定义属性.

## 构成部分

@duskmoon-dev/core 包括: **50+ 组件** 按类别:

### 核心组成部分(6)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 按钮 | `.btn`, (中文(简体) ), `.btn-primary`, (中文(简体) ), `.btn-secondary`, (中文(简体) ), `.btn-outline`, (中文(简体) ), `.btn-ghost` | 有变体、大小和状态的按钮 |
| 纸牌 | `.card`, (中文(简体) ), `.card-body`, (中文(简体) ), `.card-title`, (中文(简体) ), `.card-bordered` | 装有信头和动作的内容容器 |
| 投入 | `.input`, (中文(简体) ), `.input-bordered`, (中文(简体) ), `.input-primary` | 有大小和状态的文本输入 |
| 表单 | `.form-control`, (中文(简体) ), `.label`, (中文(简体) ), `.checkbox`, (中文(简体) ), `.radio`, (中文(简体) ), `.toggle`, (中文(简体) ), `.select`, (中文(简体) ), `.textarea` | 形式要素和布局 |
| 导航 | `.navbar`, (中文(简体) ), `.megamenu`, (中文(简体) ), `.menu`, (中文(简体) ), `.link`, (中文(简体) ), `.breadcrumbs`, (中文(简体) ), `.tabs`, (中文(简体) ), `.pagination`, (中文(简体) ), `.dropdown` | 导航模式 |
| 模式 | `dialog.modal`, (中文(简体) ), `.modal-box`, (中文(简体) ), `.modal-action` | 本地 HTML 对话框覆盖 |

### 数据显示(5)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 有远见 | `.avatar`, (中文(简体) ), `.avatar-sm`, (中文(简体) ), `.avatar-lg`, (中文(简体) ), `.avatar-group` | 有大小和组的用户外观 |
| 徽标 | `.badge`, (中文(简体) ), `.badge-primary`, (中文(简体) ), `.badge-outline`, (中文(简体) ), `.badge-dot` | 状况指标和标签 |
| 芯片 | `.chip`, (中文(简体) ), `.chip-primary`, (中文(简体) ), `.chip-outlined`, (中文(简体) ), `.chip-closeable` | 交互式标签 |
| 列表 | `.list`, (中文(简体) ), `.list-item`, (中文(简体) ), `.list-bordered`, (中文(简体) ), `.list-hoverable` | 垂直项目列表 |
| 图表 | `.table`, (中文(简体) ), `.table-zebra`, (中文(简体) ), `.table-hover`, (中文(简体) ), `.table-bordered` | 数据表 |

### 数据项(6)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 自动完成 | `.autocomplete`, (中文(简体) ), `.autocomplete-dropdown`, (中文(简体) ), `.autocomplete-option` | 可搜索的下拉 |
| 摘取日期者 | `.datepicker`, (中文(简体) ), `.datepicker-dropdown`, (中文(简体) ), `.datepicker-day` | 选择日期 |
| 文件上传 | `.file-upload`, (中文(简体) ), `.file-upload-dropzone`, (中文(简体) ), `.file-upload-item` | 拖放文件上传 |
| 评级 | `.rating`, (中文(简体) ), `.rating-item`, (中文(简体) ), `.rating-half` | 明星收视率 |
| 幻灯片 | `.slider`, (中文(简体) ), `.slider-thumb`, (中文(简体) ), `.slider-track` | 范围输入 |
| 切换 | `.switch`, (中文(简体) ), `.switch-track`, (中文(简体) ), `.switch-thumb` | 切换开关 |

### 反馈(7)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 警报 | `.alert`, (中文(简体) ), `.alert-info`, (中文(简体) ), `.alert-success`, (中文(简体) ), `.alert-warning`, (中文(简体) ), `.alert-error` | 提醒消息 |
| 对话框 | `.dialog`, (中文(简体) ), `.dialog-header`, (中文(简体) ), `.dialog-body`, (中文(简体) ), `.dialog-footer` | 确认对话框 |
| 进展 | `.progress`, (中文(简体) ), `.progress-bar`, (中文(简体) ), `.progress-circular` | 进度指标 |
| 斯凯莱通 | `.skeleton`, (中文(简体) ), `.skeleton-text`, (中文(简体) ), `.skeleton-circle`, (中文(简体) ), `.skeleton-wave` | 正在装入占位符 |
| 纸条 | `.snackbar`, (中文(简体) ), `.snackbar-message`, (中文(简体) ), `.snackbar-action` | 简短通知 |
| 土司 | `.toast`, (中文(简体) ), `.toast-container`, (中文(简体) ), `.toast-info`, (中文(简体) ), `.toast-success` | 托拉斯通知 |
| 工具提示 | `.tooltip[popover]`, (中文(简体) ), `.tooltip-top`, (中文(简体) ), `.tooltip-bottom` | 提示弹出器( H)`interestfor`(中文(简体) ) |

### 版式(2)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 应用程序栏 | `.appbar`, (中文(简体) ), `.appbar-title`, (中文(简体) ), `.appbar-nav`, (中文(简体) ), `.appbar-actions` | 顶端应用程序栏 |
| 分隔符 | `.divider`, (中文(简体) ), `.divider-vertical`, (中文(简体) ), `.divider-text` | 内容分隔符 |

### 导航(5)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 下行导航( Dock) | `.bottom-nav`, (中文(简体) ), `.bottom-nav-item`, (中文(简体) ), `.bottom-nav-indicator` | 移动导航 |
| 绘图器 | `.drawer`, (中文(简体) ), `.drawer-content`, (中文(简体) ), `.drawer-nav-item` | 侧向导航 |
| 链接 | `.link`, (中文(简体) ), `.link-hover`, (中文(简体) ), `.link-primary`, (中文(简体) ), `.link-neutral` | 原生文本链接 |
| 巨变 | `.megamenu`, (中文(简体) ), `.megamenu-trigger`, (中文(简体) ), `.megamenu-panel`, (中文(简体) ), `.megamenu-grid` | 分组网站导航 |
| 阶梯( 梯子) | `.stepper`, (中文(简体) ), `.stepper-step`, (中文(简体) ), `.stepper-indicator` | 多步骤进程 |

### 地表(4)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 手风琴 | `.accordion`, (中文(简体) ), `.accordion-item`, (中文(简体) ), `.accordion-header`, (中文(简体) ), `.accordion-content` | 可扩展面板 |
| 底页 | `.bottomsheet`, (中文(简体) ), `.bottomsheet-handle`, (中文(简体) ), `.bottomsheet-content` | 移动表 |
| 折叠 | `.collapse`, (中文(简体) ), `.collapse-content`, (中文(简体) ), `.collapse-toggle` | 可折叠的内容 |
| 过量 | `.popover[popover]`, (中文(简体) ), `.popover-body`, (中文(简体) ), `.popover-arrow` | 浮动内容( Popover API) |

### 杂项(1)

| 构成部分 | 类 | 说明 |
| --- | --- | --- |
| 时间线 | `.timeline`, (中文(简体) ), `.timeline-item`, (中文(简体) ), `.timeline-marker` | 活动时间表 |

## 构成部分实例

### 按钮

```html
<button class="btn">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-tertiary">Tertiary</button>
<button class="btn btn-outline">Outline</button>
<button class="btn btn-ghost">Ghost</button>

<!-- Sizes -->
<button class="btn btn-xs">Extra small</button>
<button class="btn btn-sm">Small</button>
<button class="btn btn-lg">Large</button>
```

### 纸牌

```html
<div class="card">
  <div class="card-body">
    <h2 class="card-title">Card title</h2>
    <p>Card content goes here.</p>
    <div class="card-actions">
      <button class="btn btn-primary">Action</button>
    </div>
  </div>
</div>
```

### 有远见

```html
<div class="avatar">
  <img src="user.jpg" alt="User" />
</div>
<div class="avatar avatar-lg avatar-rounded">
  <img src="user.jpg" alt="User" />
</div>
<div class="avatar-group">
  <div class="avatar"><img src="user1.jpg" /></div>
  <div class="avatar"><img src="user2.jpg" /></div>
  <div class="avatar"><img src="user3.jpg" /></div>
</div>
```

### 警报

```html
<div class="alert alert-info">
  <span class="alert-icon">ℹ</span>
  <span class="alert-message">Information message</span>
</div>
<div class="alert alert-success">Success!</div>
<div class="alert alert-warning">Warning!</div>
<div class="alert alert-error">Error!</div>
```

### 进展

```html
<!-- Linear -->
<div class="progress">
  <div class="progress-bar" style="width: 60%"></div>
</div>

<!-- Indeterminate -->
<div class="progress progress-indeterminate">
  <div class="progress-bar"></div>
</div>

<!-- Circular -->
<div class="progress-circular">
  <svg><circle class="progress-circular-track" /><circle class="progress-circular-bar" /></svg>
</div>
```

### 土司

```html
<div class="toast-container toast-container-top-right">
  <div class="toast toast-success show">
    <span class="toast-icon">✓</span>
    <div class="toast-content">
      <span class="toast-title">Success</span>
      <span class="toast-message">Your changes have been saved.</span>
    </div>
    <button class="toast-close">×</button>
  </div>
</div>
```

### 步进

```html
<div class="stepper">
  <div class="stepper-step completed">
    <div class="stepper-indicator">1</div>
    <span class="stepper-title">Step 1</span>
  </div>
  <div class="stepper-step active">
    <div class="stepper-indicator">2</div>
    <span class="stepper-title">Step 2</span>
  </div>
  <div class="stepper-step">
    <div class="stepper-indicator">3</div>
    <span class="stepper-title">Step 3</span>
  </div>
</div>
```

## 颜色系统

DuskMoonUI v2.0 使用OKLCH的颜色格式来进行感知而统一的色彩操控.

### 品牌颜色( 12个符号)

使用 `on-primary-container`, (中文(简体) ), `on-secondary-container`,以及 `on-tertiary-container` 对于表面的有色文字。 亮亮的角色颜色是填充: 对 `primary` 与 `primary-content`比如说。 相同的前地规则适用于语义角色. 部件保持这些用途的分离/文本控制仍可读取,而不改变主题调色板。 对于重音文本, 使用 `light-dark(var(--color-accent-content), var(--color-accent))` 主题 `color-scheme`。 。 。 .

-   `primary`, (中文(简体) ), `primary-content`, (中文(简体) ), `primary-container`, (中文(简体) ), `on-primary-container`
-   `secondary`, (中文(简体) ), `secondary-content`, (中文(简体) ), `secondary-container`, (中文(简体) ), `on-secondary-container`
-   `tertiary`, (中文(简体) ), `tertiary-content`, (中文(简体) ), `tertiary-container`, (中文(简体) ), `on-tertiary-container`

> **说明**数字 : `-focus` 符号在 v2.0 中被删除。 使用 `color-mix()` 相反:
> 
> ```css
> .btn:hover {
>   background-color: color-mix(in oklch, var(--color-primary), black 10%);
> }
> ```

### 表面颜色( 10个符号)

-   `surface`, (中文(简体) ), `surface-dim`, (中文(简体) ), `surface-bright`
-   `surface-container-lowest`, (中文(简体) ), `surface-container-low`, (中文(简体) ), `surface-container`, (中文(简体) ), `surface-container-high`, (中文(简体) ), `surface-container-highest`
-   `on-surface`, (中文(简体) ), `on-surface-variant`

### 语义颜色( 12个符号)

-   `info`, (中文(简体) ), `info-content`, (中文(简体) ), `info-container`, (中文(简体) ), `on-info-container`
-   `success`, (中文(简体) ), `success-content`, (中文(简体) ), `success-container`, (中文(简体) ), `on-success-container`
-   `warning`, (中文(简体) ), `warning-content`, (中文(简体) ), `warning-container`, (中文(简体) ), `on-warning-container`
-   `error`, (中文(简体) ), `error-content`, (中文(简体) ), `error-container`, (中文(简体) ), `on-error-container`

### 中立颜色( 10个符号)

-   `base-100` 结束 `base-900`
-   `base-content`

### 外观颜色(2个符号)

-   `outline`, (中文(简体) ), `outline-variant`

## 自定义主题

使用 OKLCH 格式定义自定义主题 :

```css
[data-theme="custom"] {
  color-scheme: light;

  /* OKLCH format: oklch(L% C H) */
  /* L = Lightness (0-100%), C = Chroma (0-0.4), H = Hue (0-360) */
  --color-primary: oklch(65% 0.18 255);
  --color-primary-content: oklch(100% 0 0);
  --color-secondary: oklch(60% 0.18 300);
  --color-secondary-content: oklch(100% 0 0);
  --color-tertiary: oklch(70% 0.15 80);
  --color-tertiary-content: oklch(20% 0 0);

  /* Base colors */
  --color-base-100: oklch(100% 0 0);
  --color-base-200: oklch(98% 0.01 85);
  --color-base-300: oklch(96% 0.01 85);
  --color-base-content: oklch(27% 0.02 260);

  /* Add remaining tokens... */
}
```

### OKLCH 颜色值

| 色调 | 颜色 |
| --- | --- |
| 0/360 (韩语) | 粉红色 |
| 30个 | 红色 |
| 第55条 | 橙红色 |
| 80个 | 黄色 |
| 145 (中文(简体) ) | 绿色 |
| 第185条 | 提尔 |
| 235 (韩语) | 蓝色 |
| 255 (英语) | 因迪戈语Name |
| 三百块 | 紫色 |

## 无障碍

所有组成部分包括:

-   **键盘导航** - 配有重点指标的完全键盘支持
-   **屏幕阅读器支持** - 适当的ARIA属性和语义HTML
-   **颜色对比** - WCAG AA遵守(最低4.5:1)
-   **减少动议** - 敬礼 `prefers-reduced-motion` 偏好

## 所需资源

-   尾风 CSS v4. 0.0 或后期
-   有 OKLCH 和 OKLCH 的现代浏览器 `color-mix()` 支持:
    -   Chrome 111 + (2023年3月)
    -   萨法里15.4+(2022年3月)
    -   Firefox 113+ (2023年5月) (英语)
    -   边缘111+(2023年3月)
-   全局浏览器支持:~92%

## 发展

```bash
# Install dependencies
bun install

# Build the package
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

# Run tests
bun run test
bun run test:visual
bun run test:integration
bun run test:a11y
```

## V1.x的迁移

v2.0.0 引入 OKLCH 颜色格式( 突破更改 ):

### 颜色格式变化

**(v1.x - HSL) 之前**数字 :

```css
/* Theme values stored as HSL components */
--color-primary: 30 90% 55%;
background-color: hsl(var(--color-primary));
```

**在(v2.0-OKLCH)之后**数字 :

```css
/* Theme values stored as full OKLCH */
--color-primary: oklch(72% 0.18 55);
background-color: var(--color-primary);
```

### 删除了托肯

这个 `-focus` 符号被删除。 使用 `color-mix()` 相反:

```css
/* Before */
background-color: hsl(var(--color-primary-focus));

/* After */
background-color: color-mix(in oklch, var(--color-primary), black 10%);
```

### 透明度

```css
/* Before */
background-color: rgba(var(--color-primary-rgb), 0.5);

/* After */
background-color: color-mix(in oklch, var(--color-primary) 50%, transparent);
```

见 [specs/004-oklch-color- system/ quickstart.md 页面存档备份,存于互联网档案馆](https://npmcn.com/package/%40duskmoon-dev/core/specs/004-oklch-color-system/quickstart.md) 详细移民指南.

## 许可证

麻省理工学院

## 常见问题

### @duskmoon-dev/core 是什么？

Dusk MoonUI - 有材料设计 3 颜色系统和组件样式的 Tailwind CSS v4 插件

### 如何安装 @duskmoon-dev/core？

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

### @duskmoon-dev/core 支持 TypeScript 吗？

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

### @duskmoon-dev/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @duskmoon-dev/core 需要什么版本的 Node\.js？

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

### @duskmoon-dev/core 可以商用吗？

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

### @duskmoon-dev/core 的下载量有多少？

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

### @duskmoon-dev/core 还在维护吗？

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