# @cycomdatasystems/headwindui 中文文档

规范地址：https://npmcn.com/package/%40cycomdatasystems/headwindui/

版本：1\.10\.0
npm 元数据更新时间：2026-11-10T22:39:10.589Z
中文译文更新时间：2026-11-11T07:13:10.603Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cycomdatasystems/headwindui
原文对照：https://npmcn.com/package/%40cycomdatasystems/headwindui/?lang=original
项目主页：https://github.com/CycomDataSystems/headwind#readme
源码仓库：https://github.com/CycomDataSystems/headwind

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

- 包体积（解压后）：2.3 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18，motion \>=11，date-fns ^3\.0 \|\| ^4\.0，react-dom \>=18，tailwindcss ^4\.0，react-hot-toast ^2\.4，@heroicons/react ^2\.0，react-day-picker ^9\.0，@headlessui/react ^2\.0，@floating-ui/react ^0\.27，@tanstack/react-table ^8\.0
- 首次发布：2026-04-20T18:10:25.951Z
- 最新版本发布：2026-11-10T22:39:10.408Z
- 近 30 天下载量：3098（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

使用 Tailwind CSS 、 无头 UI 和 Motion 构建的 React UI 组件库

## 安装

```sh
npm install @cycomdatasystems/headwindui
```

也可以使用：`pnpm add @cycomdatasystems/headwindui`、`yarn add @cycomdatasystems/headwindui`、`bun add @cycomdatasystems/headwindui`

## README

# @ cycomdatas/ headwindui

由Tailwind CSS,无头UI,和Motion所建的React UI组件库. WCAG 2.1 AA 符合规定.

## 安装

```bash
npm install @cycomdatasystems/headwindui
```

### 同伴依赖关系

这些包是 **所需经费** 并且必须安装在消耗性应用程序中:

```bash
npm install react react-dom @headlessui/react @heroicons/react @tanstack/react-table motion tailwindcss
```

| 软件包 | 版本 | 用于 |
| --- | --- | --- |
| `react` | `>=18` | 所有组件 |
| `react-dom` | `>=18` | 所有组件 |
| `@headlessui/react` | `^2.0` | 复选框、 Combobox、 Drawer、 菜单、 Modal、 选择等 |
| `@heroicons/react` | `^2.0` | Banner, BottomSheet, Chip, Combobox, DatePicker, 绘图器, 表格 |
| `@tanstack/react-table` | `^8.0` | 图表 |
| `motion` | `>=11` | 所有动画组件 |
| `tailwindcss` | `^4.0` | 所有组件( 样式) |

### 可选同伴依赖关系

只有当您使用所列特定组件时,才需要这些组件:

```bash
# For HWDatePicker
npm install date-fns react-day-picker

# For HWToast / hwToast
npm install react-hot-toast
```

| 软件包 | 版本 | 用于 |
| --- | --- | --- |
| `date-fns` | `^3.0 || ^4.0` | 日期选择器 |
| `react-day-picker` | `^9.0` | 日期选择器 |
| `react-hot-toast` | `^2.4` | 土司 |

## 使用量

```tsx
import { HWButton, HWModal, hwToast } from "@cycomdatasystems/headwindui";
import "@cycomdatasystems/headwindui/styles.css";
```

> **{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `styles.css` 需要导入.** 它包含 `@theme` 登记所有 `hw-*` 设计代号(`bg-hw-primary`, (中文(简体) ), `text-hw-surface`, (中文(简体) ), `text-hw-danger`, (中文(简体) ), `rounded-hw-md`, (中文(简体) ), `outline-hw-focus-ring`等)加上他们的 `.dark` 超载 没有它,每个HW组件都会使无样式——按钮没有背景,输入没有边框,需要的域星号是看不见的. 添加尾风 v4 `@source` 指向软件包的指示 **没有** 替换此导入 : `@source` 仅控制类字符串扫描,它不注册设计符.

### 主题( 光 / 暗 / 系统)

将您的应用程序包入 `<HWThemeProvider>` 减少 `<HWThemeToggle>` 随处取取开关. 钩子 `useTheme()` 曝光情况 `{ mode, resolved, setMode }`。 。 。 .

```tsx
import { HWThemeProvider, HWThemeToggle } from "@cycomdatasystems/headwindui";

export function App() {
  return (
    <HWThemeProvider>
      <HWThemeToggle />
      {/* …rest of your app… */}
    </HWThemeProvider>
  );
}
```

为了防止在第一幅画上闪出错误的主题,请将这个脚本插入 `<head>` **在此之前** 反应挂载 :

```html
<script>
  (function () {
    try {
      var s = localStorage.getItem('headwind_theme') || 'system';
      var dark = s === 'dark' || (s === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
      if (dark) document.documentElement.classList.add('dark');
      document.documentElement.setAttribute('data-theme', s);
    } catch (e) {}
  })();
</script>
```

## 用于AI工具

充分利用指南`AI_AGENT_GUIDE.md`和紧凑的构成部分选择表`COMPONENT_INDEX.yaml`)在已公布的软件包内起航,因此在消耗性应用中运行的AI编码代理可以读取准确的,版本固定的从 `node_modules` 没有克隆这个回转。 通过软件包的子路径输出解决它们:

```js
require.resolve("@cycomdatasystems/headwindui/agent-guide"); // → dist/AI_AGENT_GUIDE.md
require.resolve("@cycomdatasystems/headwindui/manifest");    // → dist/manifest/COMPONENT_INDEX.yaml
```

名单上印有 `_packageVersion` 在顶端,当缓存副本相对于已安装的版本而言已经停止时,工具可以检测.

## 发展

```bash
# Install dependencies
npm install

# Start Storybook
npm run storybook

# Run tests
npm test

# Build the library
npm run build
```

## 命名公约

所有导出组件都使用 `HW` 前缀 :

-   组件 : `HWButton`, (中文(简体) ), `HWModal`
-   子组件 : `HWModal.Title`, (中文(简体) ), `HWMenu.Item`
-   道具 : `HWButtonProps`, (中文(简体) ), `HWModalProps`
-   必需的 API : `hwToast.success()`

## 许可证

麻省理工学院

## 常见问题

### @cycomdatasystems/headwindui 是什么？

使用 Tailwind CSS 、 无头 UI 和 Motion 构建的 React UI 组件库

### 如何安装 @cycomdatasystems/headwindui？

在项目目录运行 npm install @cycomdatasystems/headwindui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、motion（\>=11）、react-dom（\>=18）、tailwindcss（^4\.0）、@headlessui/react（^2\.0）、@floating-ui/react（^0\.27）、@tanstack/react-table（^8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cycomdatasystems/headwindui 支持 TypeScript 吗？

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

### @cycomdatasystems/headwindui 支持 ESM 还是 CommonJS？

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

### @cycomdatasystems/headwindui 可以商用吗？

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

### @cycomdatasystems/headwindui 的下载量有多少？

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

### @cycomdatasystems/headwindui 还在维护吗？

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