# @clidey/ux 中文文档

规范地址：https://npmcn.com/package/%40clidey/ux/

版本：1\.6\.4
npm 元数据更新时间：2026-11-03T05:29:41.370Z
中文译文更新时间：2026-11-10T04:39:56.577Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.4 MB，690 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：27 个
- peer 依赖：react \>=18\.3\.0，react-dom \>=18\.3\.0
- 首次发布：2025-07-28T13:27:03.479Z
- 最新版本发布：2026-11-03T05:29:41.019Z
- 近 30 天下载量：2183（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 39 个）

## 中文简介

Clidey Design — 可访问 React 组件和设计标志.

## 安装

```sh
npm install @clidey/ux
```

也可以使用：`pnpm add @clidey/ux`、`yarn add @clidey/ux`、`bun add @clidey/ux`

## README

![Clidey Design](https://npmcn.com/package/%40clidey/ux/docs/logo/logo.png)

**滑翔机设计**  
**以Radix UI和Tailwind CSS v4相建的制作准备回放组件库.**  
37+ 无障碍,可堆肥,暗模可备组件——下船.

 [![npm version](https://img.shields.io/npm/v/@clidey/ux?color=6366f1&labelColor=18181b&style=flat-square)](https://www.npmjs.com/package/@clidey/ux)[![downloads](https://img.shields.io/npm/dm/@clidey/ux?color=6366f1&labelColor=18181b&style=flat-square) ](https://www.npmjs.com/package/@clidey/ux)[![Apache 2.0 license](https://img.shields.io/badge/license-Apache--2.0-6366f1?labelColor=18181b&style=flat-square) ](https://github.com/clidey/ux/blob/main/LICENSE)![React 18/19](https://img.shields.io/badge/React-18%20%7C%2019-6366f1?labelColor=18181b&style=flat-square) ![TypeScript](https://img.shields.io/badge/TypeScript-ready-6366f1?labelColor=18181b&style=flat-square)

* * *

## 为什么是克利德设计?

从零开始建立一个连贯的,无障碍的UI需要几周的时间. Clidey Design给你一套完整的被打磨的组件,这样你就可以专注于自己的产品,而不是你的设计系统.

-   **默认可访问** - 每个组成部分都建立在 [Radix 用户界面](https://radix-ui.com/) 原始的 原始的 原始的 键盘导航,焦点管理,和ARIA属性都是为您处理的.
-   **包含暗模式** - 包装您的应用程序 `ThemeProvider` 所有组件自动调整。 系统偏好检测和 `localStorage` 坚韧不拔.
-   **完全输入** ——采用严格模式的完整TypeScript定义. 每个道具、变体和事件处理器自动完成 .
-   **可编译的 API** ——子构件图案使你完全控制了布局和打分,而不与有见解的结构相对抗.
-   **尾风 CSS v4** - 以你已经知道的实用类命名 覆盖任何东西 `className`。 。 。 .
-   **0 配置** 一个导入, 一个样式表, 完成 .

* * *

## 安装

```bash
npm install @clidey/ux
# or
pnpm add @clidey/ux
# or
yarn add @clidey/ux
```

**一次导入样式表** 在您的应用程序入口:

```tsx
// main.tsx / _app.tsx
import '@clidey/ux/styles.css';
```

**以主题提供器环绕** 以启用暗模式 :

```tsx
import { ThemeProvider } from '@clidey/ux';

export default function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* your app */}
    </ThemeProvider>
  );
}
```

就是这样。 没有额外的配置, 您的项目中不需要 Tailwind 设置 .

* * *

## 快开始

```tsx
import {
  Button,
  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter,
  Badge,
  Input,
  Label,
} from '@clidey/ux';
import '@clidey/ux/styles.css';

export default function Example() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Create account</CardTitle>
        <CardDescription>Get started in seconds. No credit card required.</CardDescription>
      </CardHeader>
      <CardContent className="space-y-3">
        <div className="space-y-1">
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="you@example.com" />
        </div>
        <div className="space-y-1">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" showPasswordToggle />
        </div>
      </CardContent>
      <CardFooter className="flex items-center justify-between">
        <Badge variant="outline">Free plan</Badge>
        <Button>Create account</Button>
      </CardFooter>
    </Card>
  );
}
```

* * *

## 构成部分

### 行动

| 构成部分 | 说明 |
| --- | --- |
| `Button` | 6个变种(`default`, (中文(简体) ), `destructive`, (中文(简体) ), `outline`, (中文(简体) ), `secondary`, (中文(简体) ), `ghost`, (中文(简体) ), `link`4个大小 |
| `ButtonGroup` | 连接工具栏和分区控件的按钮条 |

### 投入

| 构成部分 | 说明 |
| --- | --- |
| `Input` | 带有可选密码切换的文本字段 |
| `TextArea` | 多行文本输入 |
| `SearchInput` | 带有内置搜索图标的文本字段 |
| `Checkbox` | 使用不确定状态的可访问复选框 |
| `Switch` | 切换布尔设置 |
| `Select` | 可编译的下拉选择器 |
| `SearchSelect` | 带有搜索过滤和图标支持的下放 |
| `Label` | 可访问表单标签 |

### 显示

| 构成部分 | 说明 |
| --- | --- |
| `Badge` | 状况和类别标签 4个变种 |
| `Card` | 有标题、内容、页脚和动作槽的容器 |
| `Alert` | 内含反馈信息 `default` 财务报告和审定财务报表 `destructive` |
| `Spinner` | 动画加载器 → 5个颜色变体 → 3个大小 |
| `Skeleton` | 为装入状态推出占位符 |
| `Progress` | 线性进度栏 |
| `EmptyState` | 空列表和零状态屏幕的占位符 |
| `Separator` | 水平或垂直分隔符 |

### 导航

| 构成部分 | 说明 |
| --- | --- |
| `Tabs` | 节间切换的标签面板 |
| `Breadcrumb` | 带有椭圆支持的分级路径 |
| `Pagination` | 上一个/ 下一个和编号的页控件 |
| `Sidebar` | 带有可折叠菜单、子菜单、移动支持的完整侧边栏 |

### 重叠

| 构成部分 | 说明 |
| --- | --- |
| `Dialog` | 带有焦点陷阱和滚动锁的模块 |
| `AlertDialog` | 阻碍确认破坏性行动 |
| `Drawer` | 任意边缘的滑入面板( 由 Vaul 驱动) |
| `Sheet` | 侧面板覆盖( 由 Radix Dialog 驱动) |
| `Tooltip` | 带有可配置延迟和位置的粘贴标签 |
| `Popover` | 点击扰动浮动面板 |

### 菜单

| 构成部分 | 说明 |
| --- | --- |
| `DropdownMenu` | 带有复选框、无线电组和子菜单的触发菜单 |
| `ContextMenu` | 用相同的丰富项目类型右键单击菜单 |
| `Command` | 由 cmdk 提供动力的模糊搜索命令调色板(%K) |

### 版式

| 构成部分 | 说明 |
| --- | --- |
| `Accordion` | 有动画扩展/缩放的可折叠部分 |
| `ResizablePanelGroup` | 拖放到修改大小的分隔视图 |
| `MasterDetailPanels` | 列表/ 细节拆分; 低于 768px 的一个面板 |
| `ScrollArea` | 自定义有样式的音轨和拇指的滚动条 |
| `StackList` | 带有分隔符的关键值元数据列表 |

### 数据可视化

| 构成部分 | 说明 |
| --- | --- |
| `Table` | 包含大型数据集和 JSON 预览虚拟化的完整表格 |
| `Chart` | 带有主题感知工具提示和传说的缩写包 |
| `Tree` | 带有扩展和选择的分级树 / 文件探索器 |

### 公用事业

| 构成部分 | 说明 |
| --- | --- |
| `Icon` | SVG 有相容尺寸的包装 |
| `CatalogIcon` | 按目录名称选择的普通 SVG 图标 |
| `IconSearch`, (中文(简体) ), `IconHome`,, , , , , , , , | 每个目录的命名组件 SVG, 包括 `Alt` 变体 |
| `Toaster` | 由索纳公司提供催眠通知 |

### 主题

| 构成部分/钩 | 说明 |
| --- | --- |
| `ThemeProvider` | 光 / 暗 / 系统主题的背景提供者 |
| `useTheme` | 要读取并设定活动主题的钩 |
| `ModeToggle` | 为切换主题而准备的下拉 |

* * *

## 用法实例

### 目录图标

```tsx
import { IconSearch, IconSearchAlt, CatalogIcon } from '@clidey/ux';

<IconSearch className="size-4" />
<IconSearchAlt size={20} />
<CatalogIcon name="source" size={16} />
```

Catalog 图标继承了当前文本颜色并接受 SVG 道具和 ref. 添加 `aria-label` 当图标需要它自己的无障碍名称时.

### 触发和 `asChild`

环绕交互式儿童在 `DropdownMenuTrigger`, (中文(简体) ), `TooltipTrigger`, (中文(简体) ), `PopoverTrigger`, (中文(简体) ), `DialogTrigger` 朋友们 **无** `asChild`;当时间档安全时,触发器作为孩子产生(`Button`, (中文(简体) ), `Badge`, (中文(简体) ), `SidebarMenuButton`,内在 `button`编号 :`a`编号 :`span`编号 :`div`,否则作为自己的按钮。 过 `asChild` 仅用于转发 refs 的非 ux 元素。 见 [文件/触发器-和-儿童](https://npmcn.com/package/%40clidey/ux/docs/triggers-and-aschild.md) 对于规则,安全/不安全的桌子和陷阱.

```tsx
<DropdownMenuTrigger>
  <Button variant="ghost" size="icon"><MoreHorizontal /></Button>
</DropdownMenuTrigger>
```

### 确认对话框

```tsx
import {
  AlertDialog, AlertDialogTrigger, AlertDialogContent,
  AlertDialogHeader, AlertDialogTitle, AlertDialogDescription,
  AlertDialogFooter, AlertDialogCancel, AlertDialogAction,
  Button,
} from '@clidey/ux';

<AlertDialog>
  <AlertDialogTrigger>
    <Button variant="destructive">Delete account</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. Your data will be permanently deleted.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Delete account</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

### 托拉斯通知

```tsx
import { Toaster, toast } from '@clidey/ux';

// In your root layout
<Toaster />

// Anywhere in your app
toast.success('Saved successfully!');
toast.error('Something went wrong.');
toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Done!',
  error: 'Failed to save.',
});
```

### 命令调色板 (QQ)

```tsx
import {
  CommandDialog, CommandInput, CommandList,
  CommandEmpty, CommandGroup, CommandItem,
} from '@clidey/ux';

<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Search commands..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Navigation">
      <CommandItem onSelect={() => navigate('/dashboard')}>Dashboard</CommandItem>
      <CommandItem onSelect={() => navigate('/settings')}>Settings</CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>
```

### 具有虚拟化的大型数据集表

```tsx
import {
  TableProvider, Table, TableHeader, TableHeadRow,
  TableHead, VirtualizedTableBody, TableRow, TableCell,
} from '@clidey/ux';

<TableProvider columnCount={3}>
  <Table>
    <TableHeader>
      <TableHeadRow>
        <TableHead>ID</TableHead>
        <TableHead>Name</TableHead>
        <TableHead>Status</TableHead>
      </TableHeadRow>
    </TableHeader>
    <VirtualizedTableBody rowCount={10000} rowHeight={48} height={400}>
      {({ index, style }) => (
        <TableRow style={style}>
          <TableCell>{rows[index].id}</TableCell>
          <TableCell>{rows[index].name}</TableCell>
          <TableCell>{rows[index].status}</TableCell>
        </TableRow>
      )}
    </VirtualizedTableBody>
  </Table>
</TableProvider>
```

* * *

## 他们

所有可视标志作为CSS自定义属性被曝光. 导入后在您的样式表中覆盖 `@clidey/ux/styles.css`数字 :

```css
:root {
  --primary: 250 84% 54%;          /* your brand color */
  --radius: 0.375rem;              /* border radius */
}
```

黑暗模式是自动的—— `ThemeProvider` 应用 a `dark` 类改为 `<html>` 所有部件都通过Tailwind的 `dark:` 修饰相.

* * *

## 下一个.js

```tsx
// app/providers.tsx
'use client';
import { ThemeProvider } from '@clidey/ux';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ThemeProvider defaultTheme="system">{children}</ThemeProvider>;
}

// app/layout.tsx
import '@clidey/ux/styles.css';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

* * *

## 同伴依赖关系

| 软件包 | 版本 |
| --- | --- |
| `react` | `>= 18.3.0` |
| `react-dom` | `>= 18.3.0` |

所有其他依赖(Radix UI,Lucide,Recharts,Sonner,Vaul,cmdk)都被捆绑——不需要额外的安装.

* * *

## 捐款

欢迎投稿、错误报告和特性请求。 请打开一个问题或调用请求 [GitHub 图像](https://github.com/clidey/ux)。 。 。 .

## 未找到页面

在您的应用程序倒置路线中使用动画 404 视图 :

```tsx
import { NotFoundPage } from '@clidey/ux';

<NotFoundPage homeHref="/" homeLabel="Back to home" />
```

自定义副本 `title`, (中文(简体) ), `description`,以及 `eyebrow`启用 `onHome` 用于路由器导航或 `action` 习惯动作。 播放支持 `loop`, (中文(简体) ), `once`,以及 `off` 结束 `defaultMotion` 或受控制 `motion` 编号 : `onMotionChange` 道具来. 减少的运动偏好自动显示一个静态. 启用可选播放控制 `showMotionControls`。 。 。 .

## 许可证

凭 [Apache 许可证 2.0](https://npmcn.com/package/%40clidey/ux/LICENSE)。 。 。 .

## 滑翔机设计图标

完整的Clidey Design图标收藏作为原始的SVG资产,无需通过主UI条目加载. 在 Vite app 中导入单个图标 URL :

```tsx
import searchUrl from "@clidey/ux/icons/svg/search.svg?url";

<img src={searchUrl} alt="" />
```

对于动态图标拾取器,请导入 `icons` URL 地图来自 `@clidey/ux/icons`。见 [`icons/README.md`](https://npmcn.com/package/%40clidey/ux/icons/README.md) 用于使用示例.

## 常见问题

### @clidey/ux 是什么？

Clidey Design — 可访问 React 组件和设计标志\.

### 如何安装 @clidey/ux？

在项目目录运行 npm install @clidey/ux，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.3\.0）、react-dom（\>=18\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clidey/ux 支持 TypeScript 吗？

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

### @clidey/ux 支持 ESM 还是 CommonJS？

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

### @clidey/ux 可以商用吗？

@clidey/ux 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @clidey/ux 的下载量有多少？

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

### @clidey/ux 还在维护吗？

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