# @hadoku/task-ui-components 中文文档

规范地址：https://npmcn.com/package/%40hadoku/task-ui-components/

版本：4\.23\.35
npm 元数据更新时间：2026-11-12T22:27:53.443Z
中文译文更新时间：2026-11-17T05:58:02.776Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.3 MB，245 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@wolffm/themes \*
- 首次发布：2026-10-28T06:27:56.193Z
- 最新版本发布：2026-11-12T22:27:53.089Z
- 近 30 天下载量：9189（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

具有 Bento 网格和金属梯度支持的可重复使用的 UI 组件

## 安装

```sh
npm install @hadoku/task-ui-components
```

也可以使用：`pnpm add @hadoku/task-ui-components`、`yarn add @hadoku/task-ui-components`、`bun add @hadoku/task-ui-components`

## README

# @wolffm/任务-ui-组件

可重用任务管理应用程序的UI组件. 生产准备就绪并全部打入.

## 安装

```bash
npm install @wolffm/task-ui-components
```

## SSR 配置(Astro/Next.js)

如果在 SSR 环境中使用此软件包( Astro, Next.js等), 则添加此一次性配置 :

```js
// astro.config.mjs
export default defineConfig({
  vite: {
    ssr: {
      noExternal: ['@wolffm/task-ui-components']
    }
  }
})
```

```js
// next.config.js
module.exports = {
  transpilePackages: ['@wolffm/task-ui-components']
}
```

这使得软件包可以自动捆绑其CSS. **这是一个一次性的设置** - 未来所有组件更新将自动工作,而不附加配置.

## 构成部分

### Appheader (概览)

每个 hadoku.me app 的生态系统标准顶端栏:标题在左边,一个 右侧的动作栏,上面有主题拾取器和统一设置齿轮. 执行共享头部合同,使孩子的应用停止漂移. 见 [统一应用程序头](https://npmcn.com/package/%40hadoku/task-ui-components/#readme-unified-app-header-recommended-for-hadokume-apps) 见下文.

### 连接的设置( 概览)

统一的每个用户设置齿轮 + 弹出( 访问级别, 显示名称, 全球) 内容可视度级别,以及网站的"Switch密钥"链接 `/auth` 页 次 - 只有该页面创建会话). "接通了":它自通了电线 由同源取来,所以不需要道具 喷出 自动通过 `AppHeader`;也可以单独使用.

重命名或变相器会改变火灾 `NAME_EVENT` (单位:千美元)`hadoku:name`) (中文(简体) ) `AVATAR_EVENT` (单位:千美元)`hadoku:avatar`继续 `window`。齿轮也开始 `relayIdentityChanges()`, (中文(简体) ), 将那些事件带过 `BroadcastChannel('hadoku:identity')` 改为每个 浏览器中的其他 hadoku 选项卡, 并将其重新点燃为同一窗口 事件——在另一个标签中打开的房间听到一个页面上的更改,没有 房间 每一个窗口都有一个中继器,甚至可以复制捆绑的拷贝 软件包; 无齿轮的页面( 室用铬) 可调用 `relayIdentityChanges()` (也在无反应子路径上) `@wolffm/task-ui-components/identity-relay`(中文(简体) ) 自己和加入同一个。 永远不要写第二个接力.

### 主题选择器( 概览)

一个漂亮的主题采摘者 有浅/暗的药丸设计。 完全自定义可与任何主题系统合作 .

### Modal (概览)

带有键盘快捷键、自定义动作和可选输入字段的通用模式对话框.

### 背景菜单( 概览)

基于位置的上下文菜单,有自定义的项目和危险状态.

### 正在装入Skeleton( 概览)

具有多版式(默认,最小,自定义)和黑暗主题支持的灵活加载骨架.

### 设置 Modal (概览)

通用设置对话框,包含基于分区的组织和多个字段类型(切换,文本,密码,选择,按钮,自定义).

### 烤面包( T)

吐司通知系统成功,出错,信息变体.

### 本地控制替换

用于浏览器默认铬的Themed站台. 每艘船都有自己的样式表;导入 **无层**旁边 `@wolffm/themes/style.css`。每个主题的活性样本: `pnpm run gallery:controls`。 。 。 .

```tsx
import '@wolffm/task-ui-components/button.css'
import '@wolffm/task-ui-components/select.css'
import '@wolffm/task-ui-components/tooltip.css'
import '@wolffm/task-ui-components/scrollbar.css'
import { Button, Select, NativeSelect, Tooltip } from '@wolffm/task-ui-components'
;<div className="task-app-container hdk-scroll">
  {' '}
  {/* themes every scroller inside */}
  <Tooltip content="Delete task">
    <Button variant="soft" family="danger" icon="trash" aria-label="Delete task" />
  </Tooltip>
  <Select
    aria-label="Status"
    value={status}
    onChange={setStatus}
    options={[
      { value: 'todo', label: 'To do', icon: 'circle' },
      { value: 'done', label: 'Done', icon: 'check' }
    ]}
  />
</div>
```

-   **滚动栏** - 只有CSS系统. `hdk-scroll` 样式 它的元素和里面的每个滚动器, 在主题的初级 颜色( 每个元素溶解, 所以嵌入) `data-theme` 瞄准镜有自己的); 修改 `--subtle`, (中文(简体) ), `--thin`, (中文(简体) ), `--rail`, (中文(简体) ), `--autohide`零特异性(`:where()`内部 `@layer hdk-fallbacks`,所以任何滚动条规则一个应用程序会自己写出胜利——见下文.
-   **按钮** —— 说 `variant` 柔和(默认) ========= `family` 初等成绩 \* 警告危险; `size`, (中文(简体) ), `shape` (圆形药丸正方形), `icon`, (中文(简体) ), `iconEnd`, (中文(简体) ), `loading`, (中文(简体) ), `block`。没有孩子的图标是正方形图标按钮——给它 `aria-label`。 。 。 .
-   **选择** - ARIA列表框,有箭头、家/端、入、出走和打字头; `variant` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}提纲 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}被填满了鬼 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}下划线. **原生选择** 是真实的 `<select>` 同样的 触发; 在 hadoku.me shell 下, 它的列表也是主题( 见 `installSelectMenus`) (中文(简体) ).
-   **数字输入** 一个真正的 `<input type="number">` (所有输入道具通过、控制或 而不是用一个上下分身来取而代之的操作系统旋转器; `size`。 。 。 .
-   **工具提示** - 替换 `title=`. Hover和键盘聚焦、逃生、可悬浮泡; `variant` 卡(默认) 倒数 = 初级, `placement` 与取景口翻转.

选择和工具提示门户, 将其弹出到主机最近的 `[data-theme]` 范围(应用程序) 容器,或里面有嵌入式主题预览),所以弹出式总是会在其主播主题上作画 和逃亡 `overflow: hidden` 并变了祖先.

### 全页倒计时( hadoku site 安装过一次, 每个应用程序)

这些重塑了浏览器留下的应用程序,而没有触摸到它的标记. 应用程序不会 安装它们本身;它们在这里被列出,这样它知道它得到了什么以及如何选择退出.

-   `controls.css` + 键 `<html class="hdk-controls">` 焦点环、 链接颜色、 重音颜色 复选框/辐射/射程/进度、选择、占位符、, `<summary>` 标记, 文件选择器 按钮,没有数字自旋器,和字段/按钮铬.
-   `scrollbar.css` + 键 `<html class="hdk-scroll">` -每个卷轴.
-   `installTitleTooltips()` (单位:千美元)`/title-tooltips`——每 `title=` 作为卡片工具提示. 选择出 : `data-native-title`。 。 。 .
-   `installSelectMenus()` (单位:千美元)`/select-menus`() ——每个本地人的主题清单 `<select>`· ; 触摸保持电话的取取器。 选择出 : `data-native-select`。 。 。 .

两个工作表都是零特性 **财务报告和审定财务报表** 请坐 `@layer hdk-fallbacks`,所以任何规则 一个应用程序写 包括Tailwind公用事业,它们分层生活,否则会输给一个没有层次的人 任何具体规则。 只有在页上首先声明层时才有效: `@layer hdk-fallbacks, base, theme, utilities;` - 大户网站 `global.css` 已经.

## 使用量

### 统一应用程序头 (推荐为 hadoku.me apps)

每一个应用程序下 `hadoku.me` 应当使同一条上条. `AppHeader` 给 您所执行的布局 - 标题左侧, `[ status? · ThemePicker · Settings ]` 右- 并注入已线 `ConnectedSettings` 给你的装备 递给你 拥有 `ConnectedThemePicker` (主题状态保持不动):

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

function App() {
  const { theme, setTheme } = useTheme()
  return (
    <>
      <AppHeader
        title="Print Tool"
        themePicker={
          <ConnectedThemePicker
            themeFamilies={THEME_FAMILIES}
            currentTheme={theme}
            onThemeChange={setTheme}
            getThemeIcon={t => {
              const Icon = THEME_ICON_MAP[t as keyof typeof THEME_ICON_MAP]
              return Icon ? <Icon /> : null
            }}
          />
        }
      />
      {/* app body — the app's own concern */}
    </>
  )
}
```

`ConnectedSettings` 自动解决呼叫者的级别/名称 `/session/whoami` 并击中边缘路由器 `/session/*` + 键 `/prefs/api/v1/content-level` 路线. 关闭 `hadoku.me` (如"故事书") 每一个呼叫都会解决安全默认和 齿轮使一个只读的外壳——它从不扔出. 过 `settingsProps={{ userType, name }}` 当应用程序已经知道要跳过额外抓取的身份时,或者 `showSettings={false}` 以忽略齿轮.

取取主题的触发器和齿轮都是 `.app-header__icon-btn` (32px圆, 一个 `:focus-visible` ),在 `icon-btn.css`。动作行中的链接 使用同样的阶级,没有别的——它留下 `--color-text` 访问与否,没有 下划线,甚至在主机页面下 `a:visited` 规则:

```tsx
<a className="app-header__icon-btn" href="https://discord.gg/…" aria-label="Discord">
  <Icon name="chat" size={16} />
</a>
```

标题有椭圆,动作从不收缩,所以栏杆有 状态和 320px 的四个图标 (`e2e/header-icon-btn.spec.ts`) (中文(简体) ).

### 以 @ wolffm/ 主题快速启动( 建议)

使用主题选择器的最简单方法是 `@wolffm/themes` 软件包 :

```tsx
import { ConnectedThemePicker } from '@wolffm/task-ui-components'
import { useTheme, THEME_FAMILIES, THEME_ICON_MAP } from '@wolffm/themes'
import '@wolffm/themes/style.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
      }}
    />
  )
}
```

**说明:** CSS由组件自动导入——不需要人工CSS导入!!

### 使用已连接的ThemePicker( 状态)

`ConnectedThemePicker` 管理自己的开放/关闭状态 :

```tsx
import { ConnectedThemePicker } from '@wolffm/task-ui-components'

function App() {
  const [theme, setTheme] = useState('light')

  return (
    <ConnectedThemePicker
      themeFamilies={THEME_FAMILIES}
      currentTheme={theme}
      onThemeChange={setTheme}
    />
  )
}
```

### 使用主题选择器( 手册状态)

对于采取者状态的全面控制:

```tsx
import { ThemePicker, SunIcon, MoonIcon } from '@wolffm/task-ui-components'

const THEME_FAMILIES = [
  {
    lightIcon: <SunIcon />,
    darkIcon: <MoonIcon />,
    lightTheme: 'light',
    darkTheme: 'dark',
    lightLabel: 'Light',
    darkLabel: 'Dark'
  }
  // ... more themes
]

function App() {
  const [theme, setTheme] = useState('light')
  const [showPicker, setShowPicker] = useState(false)

  return (
    <ThemePicker
      currentTheme={theme}
      isOpen={showPicker}
      themeFamilies={THEME_FAMILIES}
      onThemeChange={setTheme}
      onToggle={() => setShowPicker(!showPicker)}
      onSettingsClick={() => console.log('Settings clicked')}
    />
  )
}
```

### 带有自动后退图标( 不需要图标 )

使用自己的主题系统时完美:

```tsx
import { ThemePicker } from '@wolffm/task-ui-components'
import './my-custom-style.css' // Your own theme CSS

const THEME_FAMILIES = [
  {
    // Icons will be automatically assigned (CircleIcon for first theme)
    lightTheme: 'ocean-light',
    darkTheme: 'ocean-dark',
    lightLabel: 'Ocean Light',
    darkLabel: 'Ocean Dark'
  },
  {
    // SquareIcon for second theme
    lightTheme: 'forest-light',
    darkTheme: 'forest-dark',
    lightLabel: 'Forest Light',
    darkLabel: 'Forest Dark'
  },
  {
    // TriangleIcon for third theme
    lightTheme: 'sunset-light',
    darkTheme: 'sunset-dark',
    lightLabel: 'Sunset Light',
    darkLabel: 'Sunset Dark'
  }
]

function App() {
  const [theme, setTheme] = useState('ocean-light')
  const [showPicker, setShowPicker] = useState(false)

  return (
    <ThemePicker
      currentTheme={theme}
      isOpen={showPicker}
      themeFamilies={THEME_FAMILIES}
      onThemeChange={setTheme}
      onToggle={() => setShowPicker(!showPicker)}
    />
  )
}
```

## CSS 变量

主题选择器需要这些 CSS 变量由您的主题系统定义 :

```css
:root {
  --color-text: #000000;
  --color-primary: #3b82f6;
  --color-primary-hover: rgba(59, 130, 246, 0.1);
  --color-primary-bg: rgba(59, 130, 246, 0.05);
  --color-bg-card: #ffffff;
  --color-text-secondary: #64748b;
  --shadow-focus-sm: 0 0 0 2px rgba(59, 130, 246, 0.25);
  --shadow-md: 0 2px 4px rgba(0, 0, 0, 0.1);
  --shadow-modal: 0 8px 24px rgba(0, 0, 0, 0.15);
  --transition-fast: 0.15s ease;
  --spacing-sm: 8px;
  --spacing-md: 12px;
  --spacing-lg: 16px;
  --font-size-lg: 18px;
  --font-weight-semibold: 600;
}
```

## 图标

### 主题特定图标

特定美学可用主题图标 :

-   `SunIcon` - 日光模式图标
-   `MoonIcon` - 月球/黑暗模式图标
-   `WaveIcon` - 海浪图标
-   `ZapIcon` - 闪电螺栓图标(cyberpunk)
-   `CoffeeIcon` - 咖啡杯图标
-   `FlowerIcon` - 花卉/薰衣草图标
-   `HeartIcon` - 心脏图标(平克主题)
-   `LeafIcon` - 叶图标(自然主题)
-   `SettingsIcon` - 工具/设置图标
-   `TagIcon` - 标签/标签图标
-   `SpaIcon` - 温泉/斯帕图标(扎卡亚主题)

### 通用/ 折叠图标

当您没有针对主题的特定图标时, 使用通用形状图标进行视觉区分 :

-   `CircleIcon` - 简单的圆圈
-   `SquareIcon` - 圆形正方形
-   `TriangleIcon` - 三角区
-   `DiamondIcon` - 钻石形状
-   `StarIcon` - 恒星形状
-   `HexagonIcon` - 六边形
-   `PentagonIcon` - 五角大楼
-   `OctagonIcon` - 奥克塔贡

**自动后退 :**

这个 `ThemePicker` 如果您不提供任何 :

```tsx
import { ThemePicker } from '@wolffm/task-ui-components'

const THEME_FAMILIES = [
  {
    // No icons provided - will use CircleIcon automatically
    lightTheme: 'custom-light',
    darkTheme: 'custom-dark',
    lightLabel: 'Custom Light',
    darkLabel: 'Custom Dark'
  },
  {
    // No icons provided - will use SquareIcon automatically
    lightTheme: 'another-light',
    darkTheme: 'another-dark',
    lightLabel: 'Another Light',
    darkLabel: 'Another Dark'
  }
]
```

**手动后退使用 :**

您也可以手动使用倒置图标 :

```tsx
import { getFallbackIcon, FALLBACK_ICONS } from '@wolffm/task-ui-components'

// Get icon by index (0-7, repeats after 8)
const icon = getFallbackIcon(0) // Returns CircleIcon
const icon2 = getFallbackIcon(5) // Returns HexagonIcon

// Or use the array directly
const CircleIconComponent = FALLBACK_ICONS[0]
const iconElement = <CircleIconComponent />
```

**后退图标序列 :**

当图标被省略时 `ThemeFamily`,他们被分配在这个顺序:

1.  `CircleIcon` (指数0)
2.  `SquareIcon` (指数1)
3.  `TriangleIcon` (指数2)
4.  `DiamondIcon` (指数3)
5.  `StarIcon` (指数4)
6.  `HexagonIcon` (指数5)
7.  `PentagonIcon` (指数6)
8.  `OctagonIcon` (指数7)
9.  模式从 `CircleIcon` 9+主题

这可以确保每个主题都获得一个视觉上截然不同的图标,同时保持应用程序重装的一致性.

## 锁定器

尊重发展模式和管理地位的生产安全伐木设施.

### 基本用途

```typescript
import { logger } from '@wolffm/task-ui-components'

// Informational logs (dev/admin only)
logger.info('[Component] Loading data', { userId: '123' })

// Debug logs (dev/admin only)
logger.debug('[Component] State updated', { isOpen: true, count: 5 })

// Warnings (always shown)
logger.warn('[Component] Deprecated API used', { feature: 'old-api' })

// Errors (always shown)
logger.error('[Component] Failed to save', {
  error: err instanceof Error ? err.message : String(err),
  taskId: 'task-123'
})
```

### 高级特性

**启用管理模式** 用于生产调试:

```typescript
// After user authentication
if (userIsAdmin) {
  logger.setAdminStatus(true)
}
```

**专用日志方法**数字 :

```typescript
// Component lifecycle logging
logger.component('mount', 'ThemePicker', { props })
logger.component('update', 'TaskList', { taskCount: 42 })

// Theme changes
logger.theme('pink-dark', { source: 'user-preference' })
logger.theme('ocean-light', { source: 'system' })
```

### 最佳做法

**总是使用结构化日志** 有信件和上下文对象:

```typescript
// ✅ Good - Structured with context
logger.info('[TaskList] Loading tasks', { boardId, filter })

// ❌ Bad - String concatenation
logger.info(`Loading tasks for board ${boardId}`)

// ✅ Good - Proper error extraction
logger.error('[API] Request failed', {
  error: err instanceof Error ? err.message : String(err),
  endpoint: '/api/tasks'
})

// ❌ Bad - Logging error object directly
logger.error('Request failed:', err)
```

**使用组件前缀** 便于过滤 :

```typescript
// Component-based prefixes
logger.info('[TaskList] Mounted')
logger.info('[ThemePicker] Theme changed')

// Feature-based prefixes
logger.info('[API] Request completed')
logger.info('[Auth] User logged in')
```

### 行为

| 模式 | 发展 | 生产(每日) | 生产(用户) |
| --- | --- | --- | --- |
| `logger.info()` | ✅ | ✅ | ❌ |
| `logger.debug()` | ✅ | ✅ | ❌ |
| `logger.component()` | ✅ | ✅ | ❌ |
| `logger.theme()` | ✅ | ✅ | ❌ |
| `logger.warn()` | ✅ | ✅ | ✅ |
| `logger.error()` | ✅ | ✅ | ✅ |

**检测:**

-   自动启用于 `localhost` 或者说 `127.0.0.1`
-   或者什么时候 `import.meta.env.DEV` 真实

**管理模式 :**

-   打电话 `logger.setAdminStatus(true)` 认证后
-   启用生产中用于调试的所有日志
-   有助于解决生产问题

## 道具

### 主题选择器

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `currentTheme` | `string` | ✅ | 当前活动主题名称 |
| `isOpen` | `boolean` | ✅ | 是否可见采取器下拉 |
| `themeFamilies` | `ThemeFamily[]` | ✅ | 要显示的主题组合 |
| `onThemeChange` | `(theme: string) => void` | ✅ | 选择主题时召回 |
| `onToggle` | `() => void` | ✅ | 回召切换拾取器的能见度 |
| `onSettingsClick` | `() => void` | ❌ | 设置按钮的可选召回 |
| `getThemeIcon` | `(theme: string) => ReactNode` | ❌ | 获取当前主题图标的可选函数 |
| `className` | `string` | ❌ | 容器的可选 CSS 类 |

### 主题家庭

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `lightIcon` | `ReactNode` | ❌ | 光变体图标( 省略后自动返回) |
| `darkIcon` | `ReactNode` | ❌ | 暗变体图标( 省略后自动返回) |
| `lightTheme` | `string` | ✅ | 光变体的主题名称 |
| `darkTheme` | `string` | ✅ | 暗变体的主题名称 |
| `lightLabel` | `string` | ✅ | 轻变体标签( 工具提示) |
| `darkLabel` | `string` | ✅ | 暗变体标签( 工具提示) |

## 许可证

麻省理工学院

* * *

## 其他组件文档

### Modal (API 参考文献)

带有键盘快捷键和自定义动作的通用模式对话框 .

**特征 :**

-   `role="dialog"` + 键 `aria-modal` + 键 `aria-labelledby` 与标题接通 焦点移动到打开的对话框中
-   从对话框的任何地方逃出关闭, 输入或不输入
-   从可选输入字段输入确认
-   可配置按钮(显示/隐藏取消/确认),或替换整个动作 横行通过 `actions` 对于流动,固定对不能表达
-   破坏性行动的危险变体
-   自定义样式类名

**套件的样式船** 导入一次:

```ts
import '@wolffm/task-ui-components/modal.css'
```

**用法 :**

```tsx
import { Modal } from '@wolffm/task-ui-components'

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false)
  const [value, setValue] = useState('')

  return (
    <Modal
      isOpen={isOpen}
      title="Create Item"
      onClose={() => setIsOpen(false)}
      onConfirm={async () => {
        await createItem(value)
        setIsOpen(false)
      }}
      inputValue={value}
      onInputChange={setValue}
      inputPlaceholder="Enter name..."
      confirmLabel="Create"
      confirmDisabled={!value.trim()}
    >
      <p>Enter a name for your new item.</p>
    </Modal>
  )
}
```

**道具 :**

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| \`开放 ' | \`布尔' | ✅ | 模式是否可见 |
| 标题 | " 弦 " | ✅ | 模块标题 |
| " 关闭 " | \`(.) 无效' | ✅ | 关闭回调 |
| " 确认 " | \`() \`承诺' | ❌ | 确认回调 |
| \`儿童 ' | " 反应节点 " | ❌ | 模块内容 |
| \`投入值 ' | " 弦 " | ❌ | 输入字段值 |
| " 投入变化 " | \`( 值: 字符串) \`% 空' | ❌ | 输入更改回调 |
| " 输入位置 " | " 弦 " | ❌ | 输入占位符 |
| \`确认标签 ' | " 弦 " | ❌ | 确认按钮文本( 默认: 确认) |
| \`取消标签 ' | " 弦 " | ❌ | 取消按钮文本( 默认: 取消) |
| " 确认残疾 " | \`布尔' | ❌ | 禁用确认按钮 |
| " 确认危险 " | \`布尔' | ❌ | 危险型态确认 |
| \`表演Cancel' | \`布尔' | ❌ | 显示取消按钮( 默认: 真) |
| " 显示确认 " | \`布尔' | ❌ | 显示确认按钮( 默认: 真) |
| " 类名 " | " 弦 " | ❌ | 自定义 CSS 类 |
| " 重叠分类 " Name | " 弦 " | ❌ | 自定义覆盖 CSS 类 |
| \`行动 ' | " 反应节点 " | ❌ | 替换整个动作行 |
| \`领导 ' | " 反应节点 " | ❌ | 标题左侧 |

`actions` 检查对象 `undefined`,不与 `??` ——通过 `null` 调制 **没有** 动作行( 进步步骤, 查看器), 但不包含它保留 默认取消/确认对.

* * *

### 上下文Menu( API 参考)

右键或上下文动作的基于位置的上下文菜单.

**特征 :**

-   基于位置的渲染 (x, y 坐标)
-   可配置菜单项目
-   破坏性物品的危险状态
-   残疾状态支持
-   带z-index的固定定位

**用法 :**

```tsx
import { ContextMenu, type ContextMenuItem } from '@wolffm/task-ui-components'

function MyComponent() {
  const [menu, setMenu] = useState<{ x: number; y: number } | null>(null)

  const items: ContextMenuItem[] = [
    {
      label: 'Edit',
      onClick: () => handleEdit()
    },
    {
      label: 'Delete',
      onClick: () => handleDelete(),
      isDanger: true
    }
  ]

  return (
    <div
      onContextMenu={e => {
        e.preventDefault()
        setMenu({ x: e.clientX, y: e.clientY })
      }}
    >
      <ContextMenu
        isOpen={!!menu}
        x={menu?.x || 0}
        y={menu?.y || 0}
        items={items}
        className="my-context-menu"
      />
    </div>
  )
}
```

**道具 :**

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| \`开放 ' | \`布尔' | ✅ | 菜单是否可见 |
| \`x ' 号 | \`数目 ' | ✅ | X 位置( 像素) |
| \`y\` | \`数目 ' | ✅ | Y 位置( 像素) |
| \`项目 ' | \`ContextMenu项目\[...\] | ✅ | 菜单项目 |
| " 类名 " | " 弦 " | ❌ | 自定义 CSS 类 |

**上下文菜单项目 :**

++ Project ++ 类型 + 需要 + 描述 + 描述 |------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \`标签 ' \`字符串 ' \`项目标签 ' =============================================================================================================================================================================================================================================================== \`危险'\`布尔'\`危险型号' +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

* * *

### 正在装入Skeleton( API 参考)

有多种布局选项的弹性加载骨架.

**特征 :**

-   多个布局选项( 默认、 最小值、 自定义)
-   黑暗主题支持
-   通过 " Custom Content " 道具定制内容

**用法 :**

```tsx
import { LoadingSkeleton } from '@wolffm/task-ui-components'

function MyComponent() {
  const [isLoading, setIsLoading] = useState(true)
  const isDark = useTheme() === 'dark'

  if (isLoading) {
    return <LoadingSkeleton isDarkTheme={isDark} layout="minimal" />
  }

  return <div>Content loaded!</div>
}
```

**道具 :**

++ Project ++ 类型 + 需要 + 描述 + 描述 |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------- ------- -- - -- --- -- - -- - - -- -- 黑暗主题模式 \`班级名 ' \`弦 ' \`自定义CSS班'\` +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \*

* * *

### 设置 Modal( API 参考)

与分区组织的通用设置对话框 .

**特征 :**

-   基于科的组织
-   多个字段类型:切换、文本、密码、选择、按钮、自定义
-   验证支持
-   描述字段文字

**用法 :**

```tsx
import { SettingsModal, type SettingsSection } from '@wolffm/task-ui-components'

function MyApp() {
  const [isOpen, setIsOpen] = useState(false)
  const [darkMode, setDarkMode] = useState(false)
  const [language, setLanguage] = useState('en')

  const sections: SettingsSection[] = [
    {
      id: 'display',
      title: 'Display Settings',
      fields: [
        {
          type: 'toggle',
          id: 'darkMode',
          label: 'Dark Mode',
          description: 'Use dark color scheme',
          value: darkMode,
          onChange: setDarkMode
        },
        {
          type: 'select',
          id: 'language',
          label: 'Language',
          value: language,
          onChange: setLanguage,
          options: [
            { value: 'en', label: 'English' },
            { value: 'es', label: 'Spanish' }
          ]
        }
      ]
    }
  ]

  return <SettingsModal isOpen={isOpen} sections={sections} onClose={() => setIsOpen(false)} />
}
```

**道具 :**

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| \`开放 ' | \`布尔' | ✅ | 模式是否可见 |
| \`部门 ' | \`安排部分' | ✅ | 设置区域 |
| " 关闭 " | \`(.) 无效' | ✅ | 关闭回调 |
| 标题 | " 弦 " | ❌ | 模块标题( 默认 : “ 设置” ) |
| " 类名 " | " 弦 " | ❌ | 自定义 CSS 类 |
| " 显示关闭按钮 " | \`布尔' | ❌ | 显示关闭按钮( 默认: 真) |

**字段类型 :**

```typescript
// Toggle field
{
type: 'toggle',
id: string,
label: string,
description?: string,
value: boolean,
onChange: (value: boolean) => void,
disabled?: boolean
}

// Text input field
{
type: 'text',
id: string,
label: string,
description?: string,
value: string,
onChange: (value: string) => void,
placeholder?: string,
disabled?: boolean
}

// Password field
{
type: 'password',
id: string,
label: string,
description?: string,
value: string,
onChange: (value: string) => void,
placeholder?: string,
showButton?: boolean,
buttonLabel?: string,
onButtonClick?: () => void | Promise<void>,
buttonDisabled?: boolean,
error?: string | null,
autoComplete?: string,
disabled?: boolean
}

// Select dropdown
{
type: 'select',
id: string,
label: string,
description?: string,
value: string,
onChange: (value: string) => void,
options: Array<{ value: string; label: string }>,
disabled?: boolean
}

// Action button
{
type: 'button',
id: string,
label?: string,
description?: string,
buttonLabel: string,
onClick: () => void | Promise<void>,
variant?: 'primary' | 'danger' | 'default',
disabled?: boolean
}

// Custom component
{
type: 'custom',
id: string,
label?: string,
description?: string,
render: () => ReactNode,
disabled?: boolean
}
```

## 常见问题

### @hadoku/task-ui-components 是什么？

具有 Bento 网格和金属梯度支持的可重复使用的 UI 组件

### 如何安装 @hadoku/task-ui-components？

在项目目录运行 npm install @hadoku/task-ui-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@wolffm/themes（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hadoku/task-ui-components 支持 TypeScript 吗？

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

### @hadoku/task-ui-components 支持 ESM 还是 CommonJS？

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

### @hadoku/task-ui-components 可以商用吗？

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

### @hadoku/task-ui-components 的下载量有多少？

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

### @hadoku/task-ui-components 还在维护吗？

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

