# @dynamic-labs-sdk/droplet 中文文档

规范地址：https://npmcn.com/package/%40dynamic-labs-sdk/droplet/

版本：1\.51\.0
npm 元数据更新时间：2026-11-10T18:06:37.758Z
中文译文更新时间：2026-11-13T02:25:34.704Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40dynamic-labs-sdk/droplet
原文对照：https://npmcn.com/package/%40dynamic-labs-sdk/droplet/?lang=original

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

- 包体积（解压后）：2.1 MB，593 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：31 个
- peer 依赖：next \>=14，react \>=18，react-dom \>=18，tailwindcss \>=4
- 首次发布：2026-05-12T16:49:10.112Z
- 最新版本发布：2026-11-10T18:06:37.509Z
- 近 30 天下载量：3198（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：88（近 12 个月 88 个）

## 中文简介

动态实验室反应组件库. 由Radix UI原始人,Tailwind CSS v4所建造,以及一个以OKLCH为主的设计令牌系统. 有35+组件的飞船,动画图标,暗模式等,还有活生生的故事书.

## 安装

```sh
npm install @dynamic-labs-sdk/droplet
```

也可以使用：`pnpm add @dynamic-labs-sdk/droplet`、`yarn add @dynamic-labs-sdk/droplet`、`bun add @dynamic-labs-sdk/droplet`

## README

# `@dynamic-labs-sdk/droplet`

动态实验室反应组件库. 由Radix UI原始人,Tailwind CSS v4所建造,以及一个以OKLCH为主的设计令牌系统. 有35+组件的飞船,动画图标,暗模式等,还有活生生的故事书.

* * *

## 安装

```bash
npm install @dynamic-labs-sdk/droplet
# or
pnpm add @dynamic-labs-sdk/droplet
# or
yarn add @dynamic-labs-sdk/droplet
```

**同伴依赖性 :** `react >= 18`, (中文(简体) ), `react-dom >= 18`, (中文(简体) ), `tailwindcss >= 4`下一个`>= 14`)是可选的.

* * *

## 设置

Dropplet ship Tailwind CSS v4 通用类被烤入所编译的输出. 你必须 (1) 在您的应用程序中配置 Tailwind v4 , (2) 导入设计符号样式表, (3) 告诉 Tailwind 扫描 droplet 的 `dist/` 因此,它的工具类会排入您的样式表.

### 1\. 安装和配置 Tailwind v4

如果你还没有泰尔温德V4,跟着 [尾风 v4 安装导线](https://tailwindcss.com/docs/installation)编辑 `@tailwindcss/vite` 插件是 Vite/ Next 的最简单路径 :

```ts
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});
```

### 2\. 导入设计符号样式表

从您的应用根导入一次 。 这提供了全色,阴影,半径,和打字符系统,是所有组件正确渲染的要求.

```ts
import '@dynamic-labs-sdk/droplet/styles/globals.css';
```

### 3\. 在 Tailwind 上添加水滴 `@source` 路径

Tailwind v4 默认只扫描了消耗性项目,所以它会错过Ltplet编译的JS内部的公用类. 添加一个 `@source` 对您的应用程序主样式表的指示 :

```css
/* app.css */
@import 'tailwindcss';
@source "../node_modules/@dynamic-labs-sdk/droplet/dist";
```

调整相对路径以匹配样式表的住址。 没有这个步骤,组件将变成无样式.

* * *

## 使用量

```tsx
import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Badge,
} from '@dynamic-labs-sdk/droplet';

export const Example = () => (
  <Card>
    <CardHeader>
      <CardTitle>
        My Feature
        <Badge variant="brand">New</Badge>
      </CardTitle>
    </CardHeader>
    <CardContent>
      <Button>Get started</Button>
    </CardContent>
  </Card>
);
```

* * *

## 构成部分

### UI 初级

薄薄的包装 [Radix 用户界面](https://www.radix-ui.com/) 原始人有完全的代号风格.

| 导出 | 说明 |
| --- | --- |
| `Accordion`, (中文(简体) ), `AccordionItem`, (中文(简体) ), `AccordionTrigger`, (中文(简体) ), `AccordionContent` | 可折叠的内容部分 |
| `AlertDialog`, (中文(简体) ), `AlertDialogTrigger`, (中文(简体) ), `AlertDialogContent`, (中文(简体) ), `AlertDialogAction`, (中文(简体) ), `AlertDialogCancel`,, , , , , , , , . | 破坏性行动确认模式 |
| `Avatar`, (中文(简体) ), `AvatarImage`, (中文(简体) ), `AvatarFallback` | 缩写为回缩的用户外形 |
| `Badge` | 语义状态/标签芯片. 备选案文: `default`, (中文(简体) ), `secondary`, (中文(简体) ), `outline`, (中文(简体) ), `destructive`, (中文(简体) ), `brand`, (中文(简体) ), `success`, (中文(简体) ), `warning`, (中文(简体) ), `process` |
| `Button` | 主要互动要素。 备选案文: `default`, (中文(简体) ), `secondary`, (中文(简体) ), `outline`, (中文(简体) ), `ghost`, (中文(简体) ), `destructive`, (中文(简体) ), `link` |
| `Card`, (中文(简体) ), `CardHeader`, (中文(简体) ), `CardTitle`, (中文(简体) ), `CardDescription`, (中文(简体) ), `CardContent`, (中文(简体) ), `CardFooter` | 可制成的卡片布局 |
| `Checkbox` | 带有绘图动画的可访问复选框 |
| `Collapsible`, (中文(简体) ), `CollapsibleTrigger`, (中文(简体) ), `CollapsibleContent` | 可切换内容区域 |
| `Command`, (中文(简体) ), `CommandInput`, (中文(简体) ), `CommandList`, (中文(简体) ), `CommandItem`, (中文(简体) ), `CommandGroup`,, , , , , , , , . | 无头命令调色板( cmdk) |
| `Dialog`, (中文(简体) ), `DialogTrigger`, (中文(简体) ), `DialogContent`, (中文(简体) ), `DialogHeader`, (中文(简体) ), `DialogTitle`, (中文(简体) ), `DialogBody`, (中文(简体) ), `DialogFooter`,, , , , , , , , . | 可访问模式对话框 |
| `DropdownMenu`, (中文(简体) ), `DropdownMenuTrigger`, (中文(简体) ), `DropdownMenuContent`, (中文(简体) ), `DropdownMenuItem`,, , , , , , , , . | 键盘可导航下拉 |
| `Icon` | 中风宽度一致的巨型Icons 包装器 |
| `Input` | 用字段阴影系统输入文本 |
| `Kbd` | 键盘快捷键显示( E)`⌘K`(中文(简体) ) |
| `Label` | 链接到控件的窗体标签 |
| `Popover`, (中文(简体) ), `PopoverTrigger`, (中文(简体) ), `PopoverContent`, (中文(简体) ), `PopoverAnchor` | 浮动内容面板 |
| `Progress` | 进步栏、确定和不确定 |
| `RadioGroup`, (中文(简体) ), `RadioGroupItem` | 有悬浮点的无线电按钮组 |
| `ScrollArea`, (中文(简体) ), `ScrollBar` | 自定义可滚动容器 |
| `SearchInput` | 输入主搜索图标 |
| `Select`, (中文(简体) ), `SelectTrigger`, (中文(简体) ), `SelectContent`, (中文(简体) ), `SelectItem`, (中文(简体) ), `SelectValue`,, , , , , , , , . | 以 Radix 为后盾的选择 |
| `SelectableCard` | 有嵌入式复选框/无线电状态的卡 |
| `Separator` | 水平或垂直分隔符 |
| `Sheet`, (中文(简体) ), `SheetTrigger`, (中文(简体) ), `SheetContent`, (中文(简体) ), `SheetHeader`, (中文(简体) ), `SheetTitle`, (中文(简体) ), `SheetFooter`,, , , , , , , , . | 侧抽屉(上/右/下/左) |
| `Skeleton` | 闪光装入占位符 |
| `Toaster` | 敬酒通知(Sonner) |
| `Spinner` | 动画加载指标 |
| `Switch` | 切换切换为 `data-slot` 标签集成 |
| `Table`, (中文(简体) ), `TableHeader`, (中文(简体) ), `TableBody`, (中文(简体) ), `TableRow`, (中文(简体) ), `TableHead`, (中文(简体) ), `TableCell`, (中文(简体) ), `TableFooter`, (中文(简体) ), `TableCaption` | 数据表 |
| `Tabs`, (中文(简体) ), `TabsList`, (中文(简体) ), `TabsTrigger`, (中文(简体) ), `TabsContent` | 有标签的导航、下划线和避孕药变体 |
| `Textarea` | 多行文本输入 |
| `Tooltip`, (中文(简体) ), `TooltipTrigger`, (中文(简体) ), `TooltipContent`, (中文(简体) ), `TooltipProvider` | Hover 工具提示 |
| `Well`, (中文(简体) ), `WellReveal` | 组合设置的设置容器 |

### 项目模式

由原始人所组成的更高级组件,为仪表板和设置UI所设计.

| 导出 | 说明 |
| --- | --- |
| `AskAiSheet` | AI助理整合侧面板 |
| `AssetIcon` | 链/托起图标并带有倒置初始 |
| `CodeBlock` | 带有复制按钮的语法高亮代码块 |
| `CopyButton` | 带有动画检查的剪贴板复制触发器 |
| `DangerZone` | 以确认方式打开的损坏设置区 |
| `DomainList` | 可编辑的允许添加/移动域列表 |
| `EmptyState` | 零数据占位符,带有图标、标题、描述、 CTA |
| `InfoBanner` | 上下文所标. 备选案文: `info`, (中文(简体) ), `warning`, (中文(简体) ), `success`, (中文(简体) ), `danger` |
| `MetricCard` | 带有价值、标签和趋势的 KPI 统计卡 |
| `PageActions` | 带有初级/中级插槽的粘性底部动作栏 |
| `PageSkeleton`, (中文(简体) ), `StatCardSkeleton`, (中文(简体) ), `TableSkeleton` | 页面级加载骨架 |
| `ProductPageLayout` | 全页脚手架:页眉、标签、内容、侧边栏 |
| `SettingsSection` | 设置页面的标签区域包装 |
| `StatusBadge` | 活性/不活动/待定状态指标 |
| `TabNavigation` | 用于切换相关视图的全宽下划线标签导航 |
| `ToggleRow` | 标签 + 描述 + 切换到单个可访问行 |
| `UnsavedChangesBar` | 带有更改跟踪保存/丢弃的粘贴底条 |

### 动画图标

自定义带有弹簧物理的 SVG 图标 [动议](https://motion.dev/)。所有图标接受标准的 SVG 道具加一个 `className`。 。 。 .

```tsx
import {
  ChevronDownIcon,
  CopyCheckIcon,
  SettingsIcon,
} from '@dynamic-labs-sdk/droplet';

<SettingsIcon className="size-4 text-muted-foreground" />;
```

| 导出 | 说明 |
| --- | --- |
| `AnimatedIcon` | 用于构建动画图标的基础包装器 |
| `ArrowUpRightIcon` | 外部链接箭头 |
| `ChartBarIncreasingIcon` | 动画条形图 |
| `ChevronDownIcon` | Chevron, 切换旋转 |
| `ChevronRightIcon` | 雪佛龙指向右边 |
| `CopyIcon` | 复制到剪贴板 |
| `CopyCheckIcon` | 复制 – 检查过渡 |
| `DollarSignIcon` | 货币符号 |
| `DownloadIcon` | 下载箭头 |
| `FingerprintIcon` | 生物指纹 |
| `HomeIcon` | 家用/贴板 |
| `KeyIcon` | API 密钥/ 认证 |
| `LayoutPanelTopIcon` | 布局面板 |
| `LinkIcon` | 超链接 |
| `MoonIcon` | 黑暗模式 |
| `PanelLeftCloseIcon` | 折叠侧边栏 |
| `PanelLeftOpenIcon` | 展开侧边栏 |
| `PlusIcon` | 添加/ 创建 |
| `RefreshCWIcon` | 刷新/ 重新装入 |
| `SearchIcon` | 搜索放大镜 |
| `SettingsIcon` | 设置齿轮 |
| `ShieldCheckIcon` | 安保/核实 |
| `SunIcon` | 灯光模式 |
| `TerminalIcon` | 代码/ CLI |
| `UsersIcon` | 用户/ 团队 |
| `ClaudeLogo`, (中文(简体) ), `CursorLogo`, (中文(简体) ), `OpenAILogo`, (中文(简体) ), `VSCodeLogo`, (中文(简体) ), `WindsurfLogo` | MCP 工具标识 |

### 公用事业和胡克

| 导出 | 说明 |
| --- | --- |
| `cn(...classes)` | `clsx` + 键 `tailwind-merge` 类工具 |
| `useUnsavedChanges(hasChanges)` | 钩子取出 `UnsavedChangesBar` ——跟踪肮脏状态和线条键盘快捷键 |
| `IconConfigProvider` | 全球图标配置的背景提供者 |
| `useIconConfig()` | 访问图标配置上下文 |

* * *

## 他们

Droplet)的主题为一层CSS自定义属性. Tailwind 公用事业类通过它们解决(`bg-brand-default` → `var(--brand-default)`),每个组件都从同一个 vars 读取——这样你就可以完全重塑由 **在您的样式表中重新定义 vars**。没有 Tailwind 配置变化,没有重建,没有叉子.

### 快速启动: 改变品牌颜色

```css
/* your-theme.css — imported AFTER @dynamic-labs-sdk/droplet/styles/globals.css */

:root {
  --brand-default: oklch(0.67 0.21 30);  /* your light-mode brand */
  --brand-hover: oklch(0.72 0.19 30);
  --brand-accented: oklch(0.58 0.22 30);
  --brand-light: oklch(0.97 0.03 30);
  --ring: oklch(0.67 0.21 30);
  --action: oklch(0.67 0.21 30);
}

.dark {
  --brand-default: oklch(0.6 0.22 30);   /* your dark-mode brand */
  --brand-hover: oklch(0.68 0.19 30);
  --brand-accented: oklch(0.52 0.23 30);
  --brand-light: oklch(0.27 0.07 30);
  --ring: oklch(0.6 0.22 30);
  --action: oklch(0.6 0.22 30);
}
```

```ts
// in your app entry, AFTER the droplet import
import '@dynamic-labs-sdk/droplet/styles/globals.css';
import './your-theme.css';
```

就是这样。 按钮,链接,焦点环,文本选取要闻,侧边栏-都切换到新品牌.

### 连带命令事项

您的主题样式表 **必须在之后装入** `@dynamic-labs-sdk/droplet/styles/globals.css`,或相同的选择者(`:root`, (中文(简体) ), `.dark`)在 Ddroplet 的样式表中,会胜出,而您的操作会默默无所作为. 狦 `@import` 在单个 CSS 文件中,将 put ditchlet 导入 **第一个**数字 :

```css
@import '@dynamic-labs-sdk/droplet/styles/globals.css';
@import './your-theme.css';
```

### 什么主题

里面的东西 [设计符号](https://npmcn.com/package/%40dynamic-labs-sdk/droplet/#readme-design-tokens) 下面的表格——颜色,阴影,弧度. 最常用的东西 :

| 你想改变什么 | 键 |
| --- | --- |
| 品牌颜色( 按钮、 焦点环、 链接、 选择) | `--brand-default`, (中文(简体) ), `--brand-hover`, (中文(简体) ), `--brand-accented`, (中文(简体) ), `--brand-light`, (中文(简体) ), `--ring`, (中文(简体) ), `--action` |
| 表面( bg、 牌、 侧边栏) | `--background`, (中文(简体) ), `--card`, (中文(简体) ), `--bg-bottom`, (中文(简体) ), `--bg-default`, (中文(简体) ), `--sidebar` |
| 文本颜色 | `--foreground`, (中文(简体) ), `--muted-foreground`, (中文(简体) ), `--text-link` |
| 半径比例 | `--radius-sm` 结束 `--radius-4xl` |
| 选择突出显示 | `--selection-bg` |
| 固态按钮上高光 | `--button-highlight` |
| 复选框/ 电台盘旋填充 | `--checkbox-hover-fill`, (中文(简体) ), `--radio-hover-fill` |

对于语义颜色( 成功/ 危险/ 警告/ 进程) , 覆盖匹配 `--<state>-default`, (中文(简体) ), `--<state>-light`, (中文(简体) ), `--text-<state>` 三个.

### 将一个主题限定为应用程序的一部分

如果你只想要在树下丢出它们(例如,一个营销站点重用一个组件),就把超接放在包装类上,而不是 `:root`数字 :

```css
.my-theme {
  --brand-default: oklch(0.67 0.21 30);
  /* ... */
}
```

```tsx
<div className="my-theme">
  <Button>Themed</Button>
</div>
```

### 颜色空间

滴盘用途 [罢](https://oklch.com/) 整个 如果你的设计系统是六分之一/四分之一 [oklch.com (英语)](https://oklch.com/) 或者说 [oklch.fyi (英语)](https://oklch.fyi/) 将转换。 你没有 _有过_ 将 OKLCH 用于您的覆盖 `oklch()`, (中文(简体) ), `hex`, (中文(简体) ), `rgb()`,以及 `hsl()` 所有的操作都很好,但是在OKLCH里,当你调谐时,你就会有 感知的统一的光度坡道.

* * *

## 设计符号

所有符號都由 CSS 自定义属性所定义 `globals.css`由 Tailwind 工具类直接绘制图 `bg-brand-default` 决定: `var(--brand-default)`。 。 。 .

### 颜色组

| 组 | 键 |
| --- | --- |
| **表面** | `--background`, (中文(简体) ), `--card`, (中文(简体) ), `--popover`, (中文(简体) ), `--muted`, (中文(简体) ), `--accent`, (中文(简体) ), `--bg-bottom`, (中文(简体) ), `--bg-default`, (中文(简体) ), `--bg-accented`, (中文(简体) ), `--bg-strong`, (中文(简体) ), `--bg-absolute` |
| **文本** | `--foreground`, (中文(简体) ), `--muted-foreground`, (中文(简体) ), `--text-disabled`, (中文(简体) ), `--text-placeholder`, (中文(简体) ), `--text-link`, (中文(简体) ), `--text-invert` |
| **品牌** | `--brand-default`, (中文(简体) ), `--brand-hover`, (中文(简体) ), `--brand-accented`, (中文(简体) ), `--brand-light`, (中文(简体) ), `--action` |
| **语义** | `--success-default/light/text`, (中文(简体) ), `--danger-default/light/text`, (中文(简体) ), `--warning-default/light/text`, (中文(简体) ), `--process-default/light/text` |
| **边框** | `--border`, (中文(简体) ), `--border-divider`, (中文(简体) ), `--border-default`, (中文(简体) ), `--border-hover`, (中文(简体) ), `--border-strong`, (中文(简体) ), `--border-focused`, (中文(简体) ), `--border-selected`, (中文(简体) ), `--border-danger`, (中文(简体) ), `--border-success`, (中文(简体) ), `--border-process`, (中文(简体) ), `--border-warning` |
| **重叠** | `--overlay-hover`, (中文(简体) ), `--overlay-pressed`, (中文(简体) ), `--overlay-selected`, (中文(简体) ), `--overlay-selected-hover`, (中文(简体) ), `--overlay-md`, (中文(简体) ), `--overlay-strong` |

### 阴影系统

```css
--shadow-border       /* 1px outline */
--shadow-card         /* card elevation */
--shadow-button       /* button depth */
--shadow-input        /* form field */
--shadow-input-hover  /* field on hover */
--shadow-elevated     /* popovers / dropdowns */
--shadow-card-content /* content area separator */
```

### 半径比例

| 脚本 | 数值 |
| --- | --- |
| `--radius-sm` | 6个px |
| `--radius-md` | 8个px |
| `--radius-lg` | 10px (英语) |
| `--radius-xl` | 12px 时速 |
| `--radius-2xl` | 14px 时速 |
| `--radius-3xl` | 16px 时 |
| `--radius-4xl` | 20px (英语) |

### 黑暗模式

应用 `.dark` 类改为 `<html>` 以激活深色调色板。 所有符号在下方重新定义 `.dark` 与 OKLCH 相匹配的值——品牌色调被保留,只有光度变化.

```ts
document.documentElement.classList.toggle('dark', isDark);
```

* * *

## 故事书

交互式组件文档,包含活的代号参考,暗模式切换,以及对每个故事的11y审计.

```bash
# From repo root
pnpm --filter @dynamic-labs-sdk/droplet storybook

# From packages/droplet
pnpm storybook
```

运行在 **[http://localhost:4402 (英语)](http://localhost:4402/)**。 。 。 .

* * *

## 发展

```bash
# Run tests
pnpm --filter @dynamic-labs-sdk/droplet test

# Watch mode
pnpm --filter @dynamic-labs-sdk/droplet test:watch

# Build (ESM + CJS + .d.ts)
pnpm --filter @dynamic-labs-sdk/droplet build

# Lint
pnpm --filter @dynamic-labs-sdk/droplet lint
```

* * *

## 技术堆栈

|  |  |
| --- | --- |
| **初级** | [Radix 用户界面](https://www.radix-ui.com/) |
| **样式** | [尾风 CSS v4](https://tailwindcss.com/) 通过 `@tailwindcss/vite` |
| **动画** | [动议](https://motion.dev/) (春季物理学) |
| **图标** | [巨型Icons( 巨型Icons)](https://hugeicons.com/) |
| **备选案文** | [类变量授权](https://cva.style/) |
| **土司** | [索纳](https://sonner.emilkowal.ski/) |
| **构建** | [s](https://tsdown.dev/) (双重无害环境管理/CJS) |
| **测试** | [维特](https://vitest.dev/) + 键 [测试库](https://testing-library.com/) |
| **文档** | [故事本 第8册](https://storybook.js.org/) |

## 常见问题

### @dynamic-labs-sdk/droplet 是什么？

动态实验室反应组件库\. 由Radix UI原始人,Tailwind CSS v4所建造,以及一个以OKLCH为主的设计令牌系统\. 有35\+组件的飞船,动画图标,暗模式等,还有活生生的故事书\.

### 如何安装 @dynamic-labs-sdk/droplet？

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

### @dynamic-labs-sdk/droplet 支持 TypeScript 吗？

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

### @dynamic-labs-sdk/droplet 支持 ESM 还是 CommonJS？

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

### @dynamic-labs-sdk/droplet 可以商用吗？

@dynamic-labs-sdk/droplet 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dynamic-labs-sdk/droplet 的下载量有多少？

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

### @dynamic-labs-sdk/droplet 还在维护吗？

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