# @cellarnode/ui 中文文档

规范地址：https://npmcn.com/package/%40cellarnode/ui/

版本：0\.224\.0
npm 元数据更新时间：2026-11-04T19:06:25.478Z
中文译文更新时间：2026-11-09T07:25:19.017Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：12.2 MB，4003 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：26 个
- peer 依赖：ably ^2\.19\.0，react ^19\.0\.0，three \>=0\.170\.0，motion ^12\.0\.0，r3f-globe ^1\.6\.0，react-dom ^19\.0\.0，@ably/chat ^1\.3\.1，pdfjs-dist ^6\.2\.108，@ably/spaces ^0\.5\.0，@dnd-kit/dom ^0\.3\.2，@dnd-kit/react ^0\.3\.2，postprocessing ^6\.30\.0，@react-three/drei ^10\.0\.0，@react-three/fiber ^9\.0\.0，i18n-iso-countries \>=7\.0\.0，@cellarnode/finance ^0\.4\.2，@radix-ui/react-slot ^1\.2\.4，@radix-ui/react-tabs ^1\.1\.13，@radix-ui/react-label ^2\.1\.8，@radix-ui/react-toast ^1\.2\.15，@tanstack/react-query ^5\.0\.0，@tanstack/react-table ^8\.0\.0，@radix-ui/react-avatar ^1\.1\.11，@radix-ui/react-dialog ^1\.1\.15，@radix-ui/react-select ^2\.2\.6，@radix-ui/react-slider ^1\.3\.6，@radix-ui/react-switch ^1\.2\.6，@tanstack/react-router ^1\.168\.0，@radix-ui/react-popover ^1\.1\.15，@radix-ui/react-tooltip ^1\.2\.8，@radix-ui/react-checkbox ^1\.3\.3，@radix-ui/react-accordion ^1\.2\.12，@radix-ui/react-separator ^1\.1\.8，@cellarnode/beverage-utils \>=0\.13\.0，@radix-ui/react-hover-card ^1\.1\.15，@radix-ui/react-scroll-area ^1\.2\.10，@react-three/postprocessing ^3\.0\.0，@radix-ui/react-dropdown-menu ^2\.1\.16
- 首次发布：2026-03-27T10:19:30.345Z
- 最新版本发布：2026-11-04T19:06:25.256Z
- 近 30 天下载量：9082（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：460（近 12 个月 460 个）

## 中文简介

共享的UI组件,主题符号,以及CellarNode仪表板的聊天/出价原始.

## 安装

```sh
npm install @cellarnode/ui
```

也可以使用：`pnpm add @cellarnode/ui`、`yarn add @cellarnode/ui`、`bun add @cellarnode/ui`

## README

![@cellarnode/ui](https://npmcn.com/package/%40cellarnode/ui/docs/banner.svg)

![version](https://img.shields.io/badge/version-0.2.1-0ea5e9?style=flat-square) ![react 19](https://img.shields.io/badge/react-19-61dafb?style=flat-square&logo=react) ![typescript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat-square&logo=typescript) ![tailwind v4](https://img.shields.io/badge/Tailwind-v4-06b6d4?style=flat-square&logo=tailwindcss) ![storybook](https://img.shields.io/badge/Storybook-10-ff4785?style=flat-square&logo=storybook) ![license](https://img.shields.io/badge/license-UNLICENSED-gray?style=flat-square)

* * *

Cellar节点仪表板共享反应组件库. 飞船UI原始,设计符号,聊天组件,提供组件,一个地球可视化,以及Kanban拖放系统——全部被打入,可树可摇动,并通过"故事书"测试.

## 目录

-   [建筑](https://npmcn.com/package/%40cellarnode/ui/#readme-architecture)
-   [安装](https://npmcn.com/package/%40cellarnode/ui/#readme-install)
-   [同伴依赖关系](https://npmcn.com/package/%40cellarnode/ui/#readme-peer-dependencies)
-   [出口](https://npmcn.com/package/%40cellarnode/ui/#readme-exports)
-   [主题设计键( D)](https://npmcn.com/package/%40cellarnode/ui/#readme-theme--design-tokens)
-   [发展](https://npmcn.com/package/%40cellarnode/ui/#readme-development)
-   [写故事](https://npmcn.com/package/%40cellarnode/ui/#readme-writing-stories)
-   [创建命令](https://npmcn.com/package/%40cellarnode/ui/#readme-make-commands)
-   [故事书 MCP(AI 整合)](https://npmcn.com/package/%40cellarnode/ui/#readme-storybook-mcp-ai-integration)
-   [出版](https://npmcn.com/package/%40cellarnode/ui/#readme-publishing)

* * *

## 建筑

```
src/
├── components/        UI primitives (Button, Card, Dialog, Table, Sidebar…)
├── chat/              Chat & negotiation UI (ChatShell, ChatMessageList, ConnectionBanner)
├── offer/             Offer workflow components (BeverageDetails, OrgBanner…)
├── globe/             Interactive 3-D globe visualisation (react-globe.gl)
├── hooks/             Shared hooks (useIsMobile, useToast, useKanbanDnd)
├── lib/               Utilities (cn, semantic tones, currencies, kanban transitions)
└── theme/
    └── tokens.css     Canonical Tailwind v4 design tokens
```

**初级层**

| 层 | 软件包 | 用于 |
| --- | --- | --- |
| Radix 用户界面 | `@radix-ui/*` | 对话框、 滴放、 选择、 标签、 吐司.. |
| 无头UI | `@headlessui/react` | 降( Catalyst), 场集, 组合框 |
| 阴影/ ui | 建于 Radix 上 | 聊天提供内部变体( O) |

* * *

## 安装

```bash
pnpm add @cellarnode/ui
```

> **说明:** 这个软件包在npmjs.org上公开(`publishConfig.access: "public"`cEL-1983);安装不需要注册认证。 回报 `.npmrc` 仍然沿着 `@cellarnode` 登记范围.npmjs.org并读 `${NPM_TOKEN}` 如果一个设置.

* * *

## 同伴依赖关系

安装您的应用程序使用的对等器 :

```bash
# Always required
pnpm add react react-dom

# Optional — only needed when importing the specific sub-path
pnpm add motion                                    # animations
pnpm add @dnd-kit/react @dnd-kit/dom               # ./kanban-dnd
pnpm add @tanstack/react-query                     # chat hooks
pnpm add react-globe.gl three topojson-client world-atlas  # ./globe
pnpm add @cellarnode/beverage-utils i18n-iso-countries     # ./offer
```

* * *

## 出口

| 导入路径 | 目录 |
| --- | --- |
| `@cellarnode/ui` | 所有UI原始人、钩子和公用事业 |
| `@cellarnode/ui/theme/tokens.css` | 尾风 v4 设计符号 CSS |
| `@cellarnode/ui/chat` | ChatShell, ChatMessage列表, 连接 班纳, 信使 布局、 聊天钩 |
| `@cellarnode/ui/offer` | 饮料详细,OrgBanner,提供状态包.. |
| `@cellarnode/ui/kanban-dnd` | KanbanDndBoard 组件 |
| `@cellarnode/ui/kanban-dnd-hooks` | 使用 DraggableCard, 使用 Droppable Column |
| `@cellarnode/ui/globe` | GlobeView 组件 |
| `@cellarnode/ui/animated-list` | 动画 列表组件 |

* * *

## 主题设计键( D)

导入条形符号表 **在此之前** 您的应用程序根 CSS 有尾风 :

```css
@import "@cellarnode/ui/theme/tokens.css";
@import "tailwindcss";
```

Tokens 暴露语义 CSS 变量(`--color-background`, (中文(简体) ), `--color-primary`, (中文(简体) ), `--color-brand-secondary`等),自动被映射入 Tailwind 通用类.

光/暗模式通过添加 `dark` 类改为 `<html>`。 。 。 .

* * *

## 发展

**先决条件:** 节点20+,pnpm 9+,Playwright Chromium (用于浏览器测试).

```bash
# Install dependencies
pnpm install

# Install Playwright browser
pnpm playwright install chromium

# Start Storybook dev server
make storybook        # → http://localhost:6006

# Type-check
make typecheck

# Lint
make lint

# Run tests (Storybook browser tests, headless)
make test

# Full build
make build
```

* * *

## 写故事

每个组件 **必须** 有个 `.stories.tsx` 文件在同一位置.

```tsx
import type { Meta, StoryObj } from "@storybook/react-vite";
import { Button } from "./button";

const meta = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: { children: "Click me" },
};

export const Variants: Story = {
  render: () => (
    <div className="flex gap-3">
      <Button color="brand">Brand</Button>
      <Button outline>Outline</Button>
      <Button plain>Plain</Button>
    </div>
  ),
};
```

### 公约

-   `tags: ["autodocs"]` • 自动生成道具文件
-   包含 a `Default` 故事 + 至少一个变体故事
-   使用 `argTypes` 用于类似enum道具(颜色、大小、变体)
-   检查 **A11y (英语)** 补充小组——在合并前处理所有违规行为
-   切换 **浅/ 暗** 通过主题工具栏
-   写入 `play` 当行为复杂时用于交互测试的函数

* * *

## 创建命令

```
make build            Full build: lint + typecheck + compile
make clean            Remove dist/
make compile          Compile TypeScript to dist/
make lint             Run ESLint
make typecheck        TypeScript type checking (no emit)
make test             Run Storybook/Vitest browser tests (headless Chromium)
make test-watch       Run Vitest in watch mode
make storybook        Start Storybook dev server on :6006
make build-storybook  Build static Storybook to storybook-static/
make publish          Manual fallback ONLY — build and publish current version to npm (not the normal path)
make release-patch    Bump patch version, commit, and git tag (publishes after main's CI is green)
make release-minor    Bump minor version, commit, and git tag (publishes after main's CI is green)
make release-major    Bump major version, commit, and git tag (publishes after main's CI is green)
```

* * *

## 故事书 MCP(AI 整合)

故事书运行时( W)`make storybook`页:1 `@storybook/addon-mcp` addon 显示 MCP 服务器 `http://localhost:6006/mcp`。 。 。 .

**与克洛德密码登记一次:**

```bash
claude mcp add storybook-mcp --transport http http://localhost:6006/mcp --scope project
```

**可用的 MCP 工具 :**

| 工具 | 说明 |
| --- | --- |
| `get_ui_building_instructions` | 创建组件和故事的准则 |
| `get_story_urls` | 浏览器直接链接到每个故事 |

**构成部分表** (关于大赦国际的背景): `http://localhost:6006/manifests/components.html`

* * *

## 出版

软件包发布至npm(公众访问 - `publishConfig.access: "public"`见CEL-1983 **npm 信任出版(OIDC)** —— 说 `.github/workflows/publish.yml` 一旦推入,自动发布`main` CI 运行于 **主页** 绿色和 `package.json`'版本还没有在npm上. 没有人跑 `npm publish` 手;没有 长寿 npm 符号在出版工作。 释放通过 Make 本地剪接,然后通过普通的 PR 降落:

```bash
make release-patch   # 0.2.1 → 0.2.2
make release-minor   # 0.2.1 → 0.3.0
make release-major   # 0.2.1 → 1.0.0
```

每个发布目标:出错版本在 `package.json`滚动 `CHANGELOG.md`、建设、承诺和 创建 git 标签 `ui-vX.Y.Z` - 确实 **没有** 发布。 推出分行,打开公关,并合并. 跟着绿色CI运行 `main`这是小费. `make publish` 仍作为明确的手册 后退( 需要当地 `npm login` 这并非正常路径.

门牌的出版行为(CEL-2530):

-   **等着CI.** `Publish to npm` 开始于 `CI` 推动工作流程 `main` 成功完成,所以期待CI墙 包出现前的时钟(共享跑道池上为1.5-8 h). 看着 **发布到 npm** 运行,而不是合并.
-   **合并发布 PRLST** 暂停其它合并到 `main` 直到出版物出现: `main` 出版,所以稍后 合并使更年长的承诺的运行跳过("main has move on")而更新的承诺自己的绿色CI决定. 如果尖端上的CI是红色或 已取消, 无发布 : 在提示上修正前置或重运行 CI .
-   **`[skip ci]` 提示从未发布** (没有CI跑,没有等待).
-   **`gitHead` 在已出版的软件包中** 可能不等于 `ui-vX.Y.Z` 当一个后期的绿色提示发布该版本时, tag 承诺 .
-   **复苏.** 重运行失败的 CI 任务 `main`提示(发布时遵循新的绿色结果),或使用逃生舱:动作 > _发布到 npm_ > 翻译: _运行工作流程_ 从 `main`,输入准确 `package.json` 版本在 `confirm`真实的 运行时的控件: 它必须从 `main`,启动它的人必须是在演员许可名单上 `publish.yml` (JSON名单) 任务 `if`; 在已审查的PR中添加维护者, 键入 `confirm` 必须匹配, 承诺仍然必须是尖端 `main` (否则运行) 失败并再次启动),同样的"版本还没有在npm上"检查适用. 没有环境或要求的审查者大门(不是 可在本计划的私人检索中获取; 保留 npm 信任的“ 环境” 字段空白.

## 常见问题

### @cellarnode/ui 是什么？

共享的UI组件,主题符号,以及CellarNode仪表板的聊天/出价原始\.

### 如何安装 @cellarnode/ui？

在项目目录运行 npm install @cellarnode/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ably（^2\.19\.0）、react（^19\.0\.0）、react-dom（^19\.0\.0）、@ably/chat（^1\.3\.1）、@ably/spaces（^0\.5\.0）、@cellarnode/finance（^0\.4\.2）、@radix-ui/react-slot（^1\.2\.4）、@radix-ui/react-tabs（^1\.1\.13）、@radix-ui/react-label（^2\.1\.8）、@radix-ui/react-toast（^1\.2\.15）、@radix-ui/react-avatar（^1\.1\.11）、@radix-ui/react-dialog（^1\.1\.15）、@radix-ui/react-select（^2\.2\.6）、@radix-ui/react-slider（^1\.3\.6）、@radix-ui/react-switch（^1\.2\.6）、@radix-ui/react-popover（^1\.1\.15）、@radix-ui/react-tooltip（^1\.2\.8）、@radix-ui/react-checkbox（^1\.3\.3）、@radix-ui/react-accordion（^1\.2\.12）、@radix-ui/react-separator（^1\.1\.8）、@cellarnode/beverage-utils（\>=0\.13\.0）、@radix-ui/react-hover-card（^1\.1\.15）、@radix-ui/react-scroll-area（^1\.2\.10）、@radix-ui/react-dropdown-menu（^2\.1\.16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cellarnode/ui 支持 TypeScript 吗？

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

### @cellarnode/ui 支持 ESM 还是 CommonJS？

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

### @cellarnode/ui 可以商用吗？

@cellarnode/ui 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @cellarnode/ui 的下载量有多少？

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

### @cellarnode/ui 还在维护吗？

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