# @datum-cloud/datum-ui 中文文档

规范地址：https://npmcn.com/package/%40datum-cloud/datum-ui/

版本：3\.11\.0
npm 元数据更新时间：2026-11-09T16:24:39.932Z
中文译文更新时间：2026-11-11T16:27:49.662Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40datum-cloud/datum-ui
原文对照：https://npmcn.com/package/%40datum-cloud/datum-ui/?lang=original
源码仓库：https://github.com/datum-cloud/datum-ui

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

- 包体积（解压后）：2.5 MB，723 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：23 个
- peer 依赖：ai \>=7 \<8，zod \>=4\.6\.6 \<5，nuqs \>=2 \<3，react \>=19\.2\.7 \<20，motion \>=13 \<14，sonner \>=2\.0\.7 \<3，js-yaml \>=5\.4\.1 \<6，leaflet \>=1\.9 \<2，date-fns \>=4\.1\.0 \<5，recharts \>=3 \<4，nprogress \>=0\.2 \<1，react-dom \>=19\.2\.7 \<20，streamdown \>=2 \<3，date-fns-tz \>=3 \<4，leaflet-draw \>=1 \<2，lucide-react \>=1 \<2，@dnd-kit/core \>=6\.3\.1 \<7，@tiptap/react \>=3\.30\.5 \<4，monaco-editor \>=0\.44\.0 \<1，react-leaflet \>=5 \<6，react-dropzone \>=15 \<21，@conform-to/zod \>=1\.19\.4 \<2，react-hook-form \>=7\.80\.0 \<8，@streamdown/code \>=1 \<2，react-day-picker \>=10 \<11，@conform-to/react \>=1\.19\.4 \<2，@dnd-kit/sortable \>=10 \<11，@stepperize/react \>=7 \<8，leaflet\.fullscreen \>=5 \<6，@hookform/resolvers \>=5\.4\.0 \<6，@tiptap/starter-kit \>=3\.30\.5 \<4，react-number-format \>=5\.4\.5 \<6，@monaco-editor/react \>=4\.7\.0 \<5，@tanstack/react-table \>=9 \<10，leaflet\.markercluster \>=1\.5\.3 \<2，@tiptap/extension-link \>=3\.30\.5 \<4，@tanstack/react-virtual \>=3\.14\.3 \<4，@tiptap/extension-underline \>=3\.30\.5 \<4，react-leaflet-markercluster \>=5\.0\.0-rc\.0 \<6，@tiptap/extension-placeholder \>=3\.30\.5 \<4，@tiptap/extension-character-count \>=3\.30\.5 \<4
- 首次发布：2026-02-18T18:58:11.242Z
- 最新版本发布：2026-11-09T16:24:39.477Z
- 近 30 天下载量：6193（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 81 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @datum-cloud/datum-ui
```

也可以使用：`pnpm add @datum-cloud/datum-ui`、`yarn add @datum-cloud/datum-ui`、`bun add @datum-cloud/datum-ui`

## README

# @datum-cloud/datum-ui (英语)

达通克云反应设计体系和组件库. 搭建在 [阴影/ ui](https://ui.shadcn.com/), (中文(简体) ), [Radix 用户界面](https://www.radix-ui.com/),以及 [尾风 CSS v4](https://tailwindcss.com/)。 。 。 .

## 安装

```bash
npm install @datum-cloud/datum-ui
# or
yarn add @datum-cloud/datum-ui
# or
pnpm add @datum-cloud/datum-ui
# or
bun add @datum-cloud/datum-ui
```

## 所需资源

-   **反应 19**
-   **尾风 CSS v 4.0.7+** (v4.2.1+建议)

## 设置

### 1\. 导入样式

在您的 CSS 文件后添加 datum- ui 样式, 在 Tailwind 后 :

```css
/* app.css */
@import 'tailwindcss';
@import '@datum-cloud/datum-ui/styles';

/* Optional — import only if you use these components */
@import '@datum-cloud/datum-ui/grid';
@import '@datum-cloud/datum-ui/nprogress';
```

datum-ui 船舶未编译的 CSS 由您的 Tailwind 建筑在单一通道中处理。 样式导入会自动配置 Tailwind 来扫描 datum- ui 的组件, 用于类用 `@source`,所以公用事业喜欢 `bg-primary` 财务报告和审定财务报表 `text-foreground` 工作从盒子.

### 2\. 添加主题提供者

包装您的应用程序 `ThemeProvider` 用于光/暗/系统主题切换:

```tsx
import { ThemeProvider } from '@datum-cloud/datum-ui/theme'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {/* your app */}
    </ThemeProvider>
  )
}
```

## 进口

每个组件都有自己的子路径导出. 只导入您需要的 :

```tsx
import { Button } from '@datum-cloud/datum-ui/button'
import { Dialog } from '@datum-cloud/datum-ui/dialog'
import { Form, FormField, FormInput } from '@datum-cloud/datum-ui/form'
```

这让你的捆绑小。 一些组件需要额外的依赖性——检查下方组件表,以确定要安装什么.

### 共享出口

| 导入路径 | 说明 |
| --- | --- |
| `@datum-cloud/datum-ui` | 根管-除次道取取取器外的每个部件(`./picker`, (中文(简体) ), `./date-picker`; 需要所有对等的解析 |
| `@datum-cloud/datum-ui/styles` | 核心 CSS( 字体、 符号、 主题变量、 组件样式) |
| `@datum-cloud/datum-ui/grid` | 网格系统 CSS( 可选的—— 如果使用网格组件导入) |
| `@datum-cloud/datum-ui/nprogress` | NProgress CSS( 可选的—— 使用 NProgress 组件导入) |
| `@datum-cloud/datum-ui/theme` | 主题 公用事业和类型 |
| `@datum-cloud/datum-ui/hooks` | `useCopyToClipboard`, (中文(简体) ), `useDebounce` |
| `@datum-cloud/datum-ui/icons` | `CloseIcon`, (中文(简体) ), `IconWrapper`, (中文(简体) ), `SpinnerIcon` |
| `@datum-cloud/datum-ui/utils` | `cn` (类名合并工具) |

### 分类出口

一些具有共同的重依赖性的组件被分组在一个子路径下:

| 导入路径 | 包括 | 所需依赖 |
| --- | --- | --- |
| `@datum-cloud/datum-ui/picker` | `Picker.*`, (中文(简体) ), `DateTimeRangePicker`, (中文(简体) ), `DatePicker`, (中文(简体) ), `DateRangePicker`, (中文(简体) ), `TimePicker` | `date-fns`, (中文(简体) ), `date-fns-tz` |
| `@datum-cloud/datum-ui/date-picker` | `CalendarDatePicker`, (中文(简体) ), `TimeRangePicker` (相同别名) | `react-day-picker`, (中文(简体) ), `date-fns`, (中文(简体) ), `date-fns-tz` |
| `@datum-cloud/datum-ui/map` | `Map`, (中文(简体) ), `PlaceAutocomplete`,+地图控制 | `leaflet`, (中文(简体) ), `react-leaflet`,+传单插件 |
| `@datum-cloud/datum-ui/dropzone` | `Dropzone`, (中文(简体) ), `FileInputButton` | `react-dropzone` |
| `@datum-cloud/datum-ui/chart` | `ChartContainer`, (中文(简体) ), `ChartTooltip`等 (中文(简体) ). | `recharts` |
| `@datum-cloud/datum-ui/form` | `Form`, (中文(简体) ), `FormField`, (中文(简体) ), `FormInput`等 (中文(简体) ). | 见 [窗体适配器](https://npmcn.com/package/%40datum-cloud/datum-ui/#readme-form-adapters) 下级 |

## 构成部分

### 基本组件

以"达通"为样式的"Shadcn"/"Radix"原始人周围的薄薄包裹. **Radix UI 依赖性被捆绑** 这些部件不需要额外安装.

| 构成部分 | 其他依赖关系 | 说明 |
| --- | --- | --- |
| `Alert`, (中文(简体) ), `AlertTitle`, (中文(简体) ), `AlertDescription` | —— 说 | 状态警告横幅 |
| `Avatar`, (中文(简体) ), `AvatarImage`, (中文(简体) ), `AvatarFallback` | —— 说 | 有倒置支持的用户配置图像 |
| `Badge` | —— 说 | 标签和状态指标 `type` 财务报告和审定财务报表 `theme` 变体 |
| `Breadcrumb`, (中文(简体) ), `BreadcrumbItem`, (中文(简体) ), `BreadcrumbLink`, (中文(简体) ), `BreadcrumbSeparator`, (中文(简体) ), `BreadcrumbList`, (中文(简体) ), `BreadcrumbPage`, (中文(简体) ), `BreadcrumbEllipsis` | —— 说 | 导航面包屑 |
| `Button` | —— 说 | 按钮为 `type` (初级/中级/危险/警告/成功)和 `theme` (固体/外线/鬼魂/链接)变种 |
| `ButtonGroup` | —— 说 | 水平分组按钮 |
| `Calendar` | `react-day-picker` | 摘取日期日历 |
| `Card`, (中文(简体) ), `CardHeader`, (中文(简体) ), `CardTitle`, (中文(简体) ), `CardDescription`, (中文(简体) ), `CardContent`, (中文(简体) ), `CardFooter` | —— 说 | 内容容器 |
| `Chart` (图集,图图解等 | `recharts` | 数据可视化包 |
| `Checkbox` | —— 说 | 切换复选框 |
| `Collapsible`, (中文(简体) ), `CollapsibleTrigger`, (中文(简体) ), `CollapsibleContent` | —— 说 | 可扩展区域 |
| `Command`, (中文(简体) ), `CommandInput`, (中文(简体) ), `CommandList`, (中文(简体) ), `CommandItem`, (中文(简体) ), `CommandGroup` | —— 说 | 命令调色板/ 搜索 |
| `Dialog`, (中文(简体) ), `DialogTrigger`, (中文(简体) ), `DialogContent`, (中文(简体) ), `DialogHeader`, (中文(简体) ), `DialogTitle`, (中文(简体) ), `DialogDescription`, (中文(简体) ), `DialogFooter`, (中文(简体) ), `DialogClose` | —— 说 | 模块对话框 |
| `HoverCard`, (中文(简体) ), `HoverCardTrigger`, (中文(简体) ), `HoverCardContent` | —— 说 | 狂欢狂欢 |
| `Input` | —— 说 | 文本输入 |
| `InputGroup`, (中文(简体) ), `InputGroupInput`, (中文(简体) ), `InputGroupText` | —— 说 | 输入前缀/后缀元素 |
| `Label` | —— 说 | 表格标签 |
| `Map`, (中文(简体) ), `MapTileLayer`, (中文(简体) ), `MapMarker`, (中文(简体) ), `MapPopup`, (中文(简体) ), `MapTooltip`, (中文(简体) ), `MapZoomControl`, (中文(简体) ), `MapFullscreenControl`, (中文(简体) ), `MapLayers`, (中文(简体) ), `MapLayersControl`, (中文(简体) ), `MapLayerGroup`, (中文(简体) ), `MapCircle`, (中文(简体) ), `MapPolygon`, (中文(简体) ), `MapRectangle`, (中文(简体) ), `MapPolyline`, (中文(简体) ), `MapDrawControl`, (中文(简体) ), `MapDrawMarker`, (中文(简体) ), `MapDrawPolyline`, (中文(简体) ), `MapDrawCircle`, (中文(简体) ), `MapDrawPolygon`, (中文(简体) ), `MapDrawEdit`, (中文(简体) ), `MapDrawDelete`, (中文(简体) ), `MapDrawUndo`, (中文(简体) ), `MapLocateControl`, (中文(简体) ), `MapSearchControl`, (中文(简体) ), `MapControlContainer` | `leaflet`, (中文(简体) ), `react-leaflet`, (中文(简体) ), `leaflet-draw`, (中文(简体) ), `leaflet.fullscreen`, (中文(简体) ), `leaflet.markercluster`, (中文(简体) ), `react-leaflet-markercluster` | 交互式映射( SSR- 安全, 懒惰装入) |
| `PlaceAutocomplete` | —— 说 | Google 地址自动完成 |
| `Popover`, (中文(简体) ), `PopoverTrigger`, (中文(简体) ), `PopoverContent` | —— 说 | 点击触发弹出 |
| `RadioGroup`, (中文(简体) ), `RadioGroupItem` | —— 说 | 无线电按钮组 |
| `Select`, (中文(简体) ), `SelectTrigger`, (中文(简体) ), `SelectContent`, (中文(简体) ), `SelectItem`, (中文(简体) ), `SelectValue`, (中文(简体) ), `SelectGroup`, (中文(简体) ), `SelectLabel`, (中文(简体) ), `SelectSeparator` | —— 说 | 下拉选择 |
| `Separator` | —— 说 | 视觉分隔符 |
| `Sheet`, (中文(简体) ), `SheetTrigger`, (中文(简体) ), `SheetContent`, (中文(简体) ), `SheetHeader`, (中文(简体) ), `SheetTitle`, (中文(简体) ), `SheetDescription`, (中文(简体) ), `SheetFooter`, (中文(简体) ), `SheetClose` | —— 说 | 滑出面板 |
| `Skeleton` | —— 说 | 正在装入占位符 |
| `Spinner` | —— 说 | 正在装入旋转器 |
| `Switch` | —— 说 | 切换切换 |
| `Table`, (中文(简体) ), `TableHeader`, (中文(简体) ), `TableBody`, (中文(简体) ), `TableFooter`, (中文(简体) ), `TableHead`, (中文(简体) ), `TableRow`, (中文(简体) ), `TableCell`, (中文(简体) ), `TableCaption` | —— 说 | 数据表 |
| `Tabs`, (中文(简体) ), `TabsList`, (中文(简体) ), `TabsTrigger`, (中文(简体) ), `TabsContent` | —— 说 | 标签界面 |
| `Textarea` | —— 说 | 多行文本输入 |
| `Tooltip`, (中文(简体) ), `TooltipTrigger`, (中文(简体) ), `TooltipContent`, (中文(简体) ), `TooltipProvider` | —— 说 | Hover 工具提示 |
| `Title`, (中文(简体) ), `Text`, (中文(简体) ), `Paragraph`, (中文(简体) ), `Link`, (中文(简体) ), `List`, (中文(简体) ), `ListItem`, (中文(简体) ), `Blockquote`, (中文(简体) ), `Code` | —— 说 | 字型组件 `level`, (中文(简体) ), `size`, (中文(简体) ), `weight`, (中文(简体) ), `color`, (中文(简体) ), `type` 变体 |
| `VisuallyHidden` | —— 说 | 只读取屏幕内容 |

### 特性组件

复杂,完全定制的组件,具有显著的业务逻辑.

每个组件的可树摇动子路径是其目录的kebab-case,例如. `@datum-cloud/datum-ui/multi-select`, (中文(简体) ), `@datum-cloud/datum-ui/app-navigation`, (中文(简体) ), `@datum-cloud/datum-ui/grouped-table`拾取者的家庭生活在 `@datum-cloud/datum-ui/picker` (见 [分类出口](https://npmcn.com/package/%40datum-cloud/datum-ui/#readme-grouped-exports)) (中文(简体) ).

| 构成部分 | 其他依赖关系 | 说明 |
| --- | --- | --- |
| `Autocomplete` | —— 说 | 搜索自动完成输入 |
| `Autosearch` | —— 说 | 用同步结果搜索首个输入 |
| `AvatarStack` | —— 说 | 堆叠的外观显示 |
| `CalendarDatePicker` | `react-day-picker`, (中文(简体) ), `date-fns` | 预设的日期/范围拾取器 |
| `CodeEditor`, (中文(简体) ), `CodeEditorTabs` | `@monaco-editor/react`, (中文(简体) ), `monaco-editor` | 使用 VS 代码 UX 的摩纳哥码编辑器 |
| `DataTable`, (中文(简体) ), `DataTableColumnHeader`, (中文(简体) ), `DataTablePagination`, (中文(简体) ), `DataTableToolbar`, (中文(简体) ), `DataTableViewOptions` | `@tanstack/react-table` | 带有排序/过滤的高级数据表 |
| `DateTimePicker`, (中文(简体) ), `TimePicker` | `date-fns`, (中文(简体) ), `date-fns-tz` | 带有时区支持的日期/时间拾取器 |
| `Dropdown`, (中文(简体) ), `DropdownHeader`, (中文(简体) ), `DropdownItem`, (中文(简体) ), `DropdownSection` | —— 说 | 下拉菜单 |
| `Dropzone` | `react-dropzone` | 文件拖放上传区域 |
| `EmptyContent` | —— 说 | 空状态占位符 |
| `FileInputButton` | —— 说 | 文件上传按钮 |
| `Form`, (中文(简体) ), `FormField`, (中文(简体) ), `FormInput`, (中文(简体) ), `FormTextarea`, (中文(简体) ), `FormSelect`, (中文(简体) ), `FormCombobox` (单位:千美元)`Form.Combobox`, (中文(简体) ), `FormCheckbox`, (中文(简体) ), `FormSwitch`, (中文(简体) ), `FormRadioGroup`, (中文(简体) ), `FormFieldArray` | 见 [窗体适配器](https://npmcn.com/package/%40datum-cloud/datum-ui/#readme-form-adapters) 下级 | 有可插接适配器支持的形式系统. `Form.Combobox` 是可搜索的单选择字段(代表到 `Autocomplete`(中文(简体) ) |
| `Grid` | `@tanstack/react-virtual` | 虚拟数据网 |
| `InputNumber` | `react-number-format` | 格式化的数字输入 |
| `InputWithAddons` | —— 说 | 输入前缀/后缀加词 |
| `LoaderOverlay` | —— 说 | 全屏加载覆盖 |
| `MoreActions` | —— 说 | 三点动作菜单 |
| `NProgress` | `nprogress` | 页面导航进度栏 |
| `PageTitle` | —— 说 | 有面包屑的页眉 |
| `Sidebar`, (中文(简体) ), `SidebarHeader`, (中文(简体) ), `SidebarContent`, (中文(简体) ), `SidebarFooter`, (中文(简体) ), `SidebarMenu`, (中文(简体) ), `SidebarMenuItem`, (中文(简体) ), `SidebarMenuButton` | —— 说 | 应用侧边栏导航 |
| `Stepper` | `@stepperize/react` | 多步向导 |
| `TagInput` | —— 说 | 标记/芯片输入 |
| `TaskQueue`, (中文(简体) ), `TaskQueueProvider`, (中文(简体) ), `TaskQueueDropdown`, (中文(简体) ), `TaskPanelHeader`, (中文(简体) ), `TaskSummaryDialog` | —— 说 | 背景任务队列与进度 UI |
| `TimeRangePicker` | `date-fns`, (中文(简体) ), `date-fns-tz` | 有时区支持的时间范围选择器 |
| `Transfer` | —— 说 | 带有搜索的双板项目选择器 |
| `Toast`, (中文(简体) ), `Toaster`, (中文(简体) ), `useToast` | `sonner` | 托拉斯通知 |
| `AppNavigation` (单位:千美元)`@datum-cloud/datum-ui/app-navigation`(中文(简体) ) | —— 说 | 应用程序导航菜单 |
| `Logo` (单位:千美元)`@datum-cloud/datum-ui/logo`,通过 `/logo/themed`(中文(简体) ) | —— 说 | Datum 标志( 平面和主题意识) |
| `MultiSelect` (单位:千美元)`@datum-cloud/datum-ui/multi-select`(中文(简体) ) | —— 说 | 通过搜索选择多值 |
| `GroupedTable` (单位:千美元)`@datum-cloud/datum-ui/grouped-table`(中文(简体) ) | `@tanstack/react-table` | 可折叠行组的表格 |
| `RichTextEditor` (单位:千美元)`@datum-cloud/datum-ui/rich-text-editor`(中文(简体) ) | `@tiptap/react`, (中文(简体) ), `@tiptap/starter-kit` | 基于 TipTap 的丰富文本编辑器 |
| `Picker`, (中文(简体) ), `DateTimeRangePicker`, (中文(简体) ), `DateRangePicker`, (中文(简体) ), `DatePicker`, (中文(简体) ), `DateRangeTimePicker` (单位:千美元)`@datum-cloud/datum-ui/picker`(中文(简体) ) | `date-fns`, (中文(简体) ), `date-fns-tz` | 可编译日期/时间拾取者家族(仅次于子路径) |

## 用法实例

### 有远见

```tsx
import { Avatar, AvatarImage, AvatarFallback } from '@datum-cloud/datum-ui/avatar'

// With image and fallback
<Avatar>
  <AvatarImage src="https://example.com/avatar.jpg" alt="User Name" />
  <AvatarFallback>UN</AvatarFallback>
</Avatar>

// Custom size
<Avatar className="size-16">
  <AvatarImage src="https://example.com/avatar.jpg" alt="User Name" />
  <AvatarFallback className="text-lg">UN</AvatarFallback>
</Avatar>

// Fallback only (no image)
<Avatar>
  <AvatarFallback>AB</AvatarFallback>
</Avatar>
```

### 按钮

```tsx
import { Button } from '@datum-cloud/datum-ui/button'

// Variants: type × theme
<Button type="primary" theme="solid">Save</Button>
<Button type="danger" theme="outline">Delete</Button>
<Button type="secondary" theme="ghost">Cancel</Button>
```

### 类型

```tsx
import { Title, Text, Paragraph, Code } from '@datum-cloud/datum-ui/typography'

<Title level={1}>Page Title</Title>
<Title level={3} color="primary">Section</Title>
<Text size="sm" color="secondary">Subtitle text</Text>
<Paragraph>Body paragraph with default styling.</Paragraph>
<Code copyable>npm install @datum-cloud/datum-ui</Code>
```

### 带有验证的表格

形式系统采用可插接适配器模式. 用适配器包装您的应用程序, 然后使用 `Form.*` 常规组件 :

```tsx
import { Form } from '@datum-cloud/datum-ui/form'
import { ConformAdapter } from '@datum-cloud/datum-ui/form/adapters/conform'
// or: import { RHFAdapter } from '@datum-cloud/datum-ui/form/adapters/rhf'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  role: z.enum(['admin', 'user']),
})

// Wrap your app once with an adapter
function App() {
  return (
    <ConformAdapter>
      <MyForm />
    </ConformAdapter>
  )
}

// Form code is identical regardless of adapter
function MyForm() {
  return (
    <Form.Root schema={schema} onSubmit={handleSubmit}>
      <Form.Field name="name" label="Name" required>
        <Form.Input />
      </Form.Field>
      <Form.Field name="role" label="Role" required>
        <Form.Select placeholder="Select a role">
          <Form.SelectItem value="admin">Admin</Form.SelectItem>
          <Form.SelectItem value="user">User</Form.SelectItem>
        </Form.Select>
      </Form.Field>
      <Form.Submit>Save</Form.Submit>
    </Form.Root>
  )
}
```

### 地图

```tsx
import {
  Map, MapTileLayer, MapMarker, MapPopup, MapZoomControl,
} from '@datum-cloud/datum-ui/map'

<div className="h-[500px] w-full">
  <Map center={[51.505, -0.09]} zoom={13}>
    <MapTileLayer />
    <MapZoomControl position="topright" />
    <MapMarker position={[51.505, -0.09]}>
      <MapPopup>Hello from London!</MapPopup>
    </MapMarker>
  </Map>
</div>
```

### 对话框

```tsx
import {
  Dialog, DialogTrigger, DialogContent,
  DialogHeader, DialogTitle, DialogDescription,
} from '@datum-cloud/datum-ui/dialog'

<Dialog>
  <DialogTrigger asChild>
    <Button>Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Confirm</DialogTitle>
      <DialogDescription>Are you sure?</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>
```

### 土司

```tsx
import { ThemeProvider } from '@datum-cloud/datum-ui/theme'
import { Toaster, useToast } from '@datum-cloud/datum-ui/toast'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <Toaster />
      <MyComponent />
    </ThemeProvider>
  )
}

function MyComponent() {
  const { toast } = useToast()
  return <Button onClick={() => toast.success('Saved!')}>Save</Button>
}
```

### 任务队列

```tsx
import {
  TaskQueueProvider, TaskQueueDropdown, useTaskQueue,
} from '@datum-cloud/datum-ui/task-queue'

<TaskQueueProvider config={{ concurrency: 3 }}>
  <TaskQueueDropdown />
  <MyComponent />
</TaskQueueProvider>

function MyComponent() {
  const { enqueue } = useTaskQueue()

  const handleUpload = () => {
    enqueue({
      id: 'upload-1',
      label: 'Uploading file.pdf',
      run: async () => { /* upload logic */ },
    })
  }

  return <Button onClick={handleUpload}>Upload</Button>
}
```

## 他们

`ThemeProvider` 支持光、暗和系统主题模式:

```tsx
import { ThemeProvider } from '@datum-cloud/datum-ui/theme'

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>
```

访问当前主题 :

```tsx
import { useTheme } from '@datum-cloud/datum-ui/theme'

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

## 同伴依赖关系

### 需求

这些依赖关系是: **所需经费** 来使用 datum-ui :

```bash
npm install react react-dom tailwindcss lucide-react
```

-   **反应 19+** 财务报告和审定财务报表 **反应 DOM 19+**: 框架要求
-   **尾风 CSS v4** (v4.0.7+,v4.2.1+建议):用于造型
-   **清晰的反应**: 整个组件使用的图标库

**所有 Radix UI 软件包都被捆绑** -你不需要单独安装.

### 可选( 组件- 特定)

许多组件需要额外的包. 只安装您使用的东西 :

> 替换 `npm install` 与 `yarn add`, (中文(简体) ), `pnpm add`,或 `bun add` 给您的包管理器.

```bash
# Forms — Conform adapter
npm install @conform-to/react @conform-to/zod zod

# Forms — React Hook Form adapter (alternative)
npm install react-hook-form @hookform/resolvers zod

# Maps (Map, MapMarker, MapPopup, etc.)
npm install leaflet react-leaflet leaflet-draw leaflet.fullscreen leaflet.markercluster react-leaflet-markercluster

# Charts (ChartContainer, ChartTooltip, etc.)
npm install recharts

# Code editor (CodeEditor, CodeEditorTabs)
npm install @monaco-editor/react monaco-editor

# Date pickers (Calendar, CalendarDatePicker, TimeRangePicker)
npm install react-day-picker date-fns date-fns-tz

# File upload (Dropzone)
npm install react-dropzone

# Number formatting (InputNumber)
npm install react-number-format

# Stepper (multi-step flows)
npm install @stepperize/react

# Toast notifications (Toast, Toaster)
npm install sonner

# Progress bar (NProgress)
npm install nprogress

# Data grid (Grid - virtualized tables)
npm install @tanstack/react-virtual

# Data Table (DataTable component)
npm install @tanstack/react-table

# Data Table with URL state (optional)
npm install nuqs

# Animations (motion components)
npm install motion
```

## 窗体适配器

形式系统支持可插接适配器. 选择一个并包装您的应用程序 :

| 适配器 | 导入路径 | 依赖关系 |
| --- | --- | --- |
| **政协.js** | `@datum-cloud/datum-ui/form/adapters/conform` | `@conform-to/react`, (中文(简体) ), `@conform-to/zod`, (中文(简体) ), `zod` (4点) |
| **反应钩形** | `@datum-cloud/datum-ui/form/adapters/rhf` | `react-hook-form` (>=7.5), `@hookform/resolvers` (>=5), `zod` (4点) |

这个 `Form.*` 组件 API 与两个适配器相同。 切换适配器只需更改根提供器 -- 不需要更改格式代码 .

见 [读取格式](https://npmcn.com/package/%40datum-cloud/datum-ui/src/components/features/form/README.md) 详细文件.

## 技术堆栈

-   **反应 19** 有服务器组件支持
-   **尾风 CSS v4** (v4.0.7+)用于造型——由消费者建造处理的未压缩CSS
-   **Radix 用户界面** 为方便原始人
-   **简历** 以变式为基础的构件API(类-变相授权)
-   **类型脚本** ——按出口类型完全输入

## 链接

-   [GitHub 图像](https://github.com/datum-cloud/datum-ui)
-   [无](https://www.npmjs.com/package/@datum-cloud/datum-ui)

## 许可证

麻省理工学院

## 可选: Canela 字体

Datum- branded surfaces 可以选择 Canela 文本用于 `font-title` 尾风工具 :

```ts
import '@datum-cloud/datum-ui/styles/canela'
```

不导入此文件的消费者使用默认系统字体堆栈在符文中声明——没有视觉降解.

## 常见问题

### 如何安装 @datum-cloud/datum-ui？

在项目目录运行 npm install @datum-cloud/datum-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.2\.7 \<20）、motion（\>=13 \<14）、react-dom（\>=19\.2\.7 \<20）、lucide-react（\>=1 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @datum-cloud/datum-ui 支持 TypeScript 吗？

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

### @datum-cloud/datum-ui 支持 ESM 还是 CommonJS？

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

### @datum-cloud/datum-ui 可以商用吗？

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

### @datum-cloud/datum-ui 的下载量有多少？

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

### @datum-cloud/datum-ui 还在维护吗？

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