# @cueplusplus/ui 中文文档

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

版本：0\.34\.2
npm 元数据更新时间：2026-11-08T17:49:31.352Z
中文译文更新时间：2026-11-11T04:47:51.723Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：6.3 MB，1239 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：5 个
- peer 依赖：anser ^2\.3\.5，react ^19\.0\.0，date-fns ^4\.4\.0，recharts ^3\.10\.1，react-dom ^19\.0\.0，heat-graph ^0\.0\.15，tailwindcss ^4\.0\.0，lucide-react ^1\.31\.0，@xyflow/react ^12\.11\.3，@base-ui/react ^1\.7\.0，react-markdown ^10\.1\.0，rehype-sanitize ^6\.0\.0，react-day-picker ^10\.0\.1，@assistant-ui/react ^0\.15\.16，embla-carousel-react ^8\.6\.0，mdast-util-gfm-table ^2\.0\.0，@tanstack/react-table ^9\.1\.2，react-aria-components ^1\.20\.0，react-resizable-panels ^4\.12\.3，@internationalized/date ^3\.12\.3，@tanstack/react-virtual ^3\.14\.9，micromark-extension-gfm-table ^2\.1\.1
- 首次发布：2026-09-15T22:07:44.836Z
- 最新版本发布：2026-11-08T17:49:31.197Z
- 近 30 天下载量：3897（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

CUE++ 设计系统组件:由 @cueplus/tokens所驱动的 Tailwind v4 有底部UI外形的包装.

## 安装

```sh
npm install @cueplusplus/ui
```

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

## README

# @ cueplus/ ui (英语)

控制台软件的组件:密密,键盘-第一接口,其中屏幕多为数据. 底部UI用于行为和无障碍,Tailwind v4在上方用于涂料.

## 安装

这个 `@cueplusplus` 范围为 **npm上公开** 并且默认地在那里解决,故无物 用于配置和不提供证书——它像其他任何软件包一样安装.

```sh
pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/react
```

要求并申报三个同行: `react` ^19, `react-dom` ^19和 `@base-ui/react` ^1.7 (韩语). `tailwindcss` ^4 也是被宣布的对等器, 但可选的对等器是默认样式所需的 没有它,你拥有CSS。 所有其他对等者都是可选的,并被扩展至子路径. `@cueplusplus/tokens` 以依赖身份到达; 安装它的名称只是使符号 在您自己的代码中可导入常数。 一揽子主题根本不是对等的,见下文.

CI、Vercel和信使的过期日期在 [`docs/CONSUMING.md` 第1节](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#1-registry-access)。 。 。 .

## 快开始

```css
/* app/globals.css */
@import "tailwindcss";
@import "@cueplusplus/ui/styles.css";
@import "@cueplusplus/theme-cue/theme.css";
```

```tsx
import cue from "@cueplusplus/theme-cue";
import { Button } from "@cueplusplus/ui";
import { ThemeProvider } from "@cueplusplus/ui/system";

export default function App() {
  return (
    <ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system">
      <Button variant="primary">Run cue</Button>
    </ThemeProvider>
  );
}
```

这三个人的顺序 `@import`s是负载的,和 `themes` 道具在 练习:此库没有调色板。 安装和注册 a `@cueplusplus/theme-*` 软件包, 或每张地表画 `@cueplusplus/theme-base`空白的底座 灰色 一种不饱和口音, 平台的单一空间——没有任何错误可告诉你.

为了停止第一次涂料上的默认闪烁,添加 `prepaintScript()` 除了提供商和手 两个相同的阵列—— [第4节 `CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#4-the-provider) 是整个布局.

还有 `theme` 财务报告和审定财务报表 `mode`,提供方取出四根轴,每根轴会改变一件事情: `density` 几何学, `font` 以面相配, `styleSet` 页面构成,以及 `paint` 尾部——相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相相相相接相相接相相相相接相相相相接相接相相相接相接相相相相接相相相接相接相相相相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. `paint` 关闭,除非 您要求它: 供应商的邮票没有 `data-paint`,所以一个页面看起来完全一样 直到你 通过一个 `none`, (中文(简体) ), `halo`, (中文(简体) ), `hatch`, (中文(简体) ), `lift`, (中文(简体) ), `frost`, (中文(简体) ), `bevel` 或者说 `grain`。任何子树都可以取出它的 拥有 `<Density paint="frost">` - 同一个岛屿重新扫描 `density` 财务报告和审定财务报表 `styleSet`编辑 字体配对是子树无法更改的一个轴: 它生活在 `<html>`,所以这是根的.

```tsx
import cue from "@cueplusplus/theme-cue";
import { ThemeProvider } from "@cueplusplus/ui/system";

export function App({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system" paint="halo">
      {children}
    </ThemeProvider>
  );
}
```

这十包,每包都是从哪里测出,每包都拒绝: [https://ui.cueplus.com/docs/paint (中文(简体) )](https://ui.cueplusplus.com/docs/paint)服务于非基于ce的内容-安全政策? 读取 [第4.5节 `CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#45-content-security-policy-the-nonce-prop-and-what-it-does-not-reach) 在你运送之前.. `paint="grain"` 单独需要 `img-src data:`。 。 。 .

## 飞来飞去

常见组件来自根条目. 需要可选对等方的组有一个子路径: 他们自己的,所以导入一个按钮 永远不会把图表库拉入你的捆绑.

| 导入指定符 | 里面有什么东西 |
| --- | --- |
| `@cueplusplus/ui` | 根管:没有可选同位素的每个组件,包括商标和容器图标 |
| `@cueplusplus/ui/primitives` | 叶:按钮、芯片、相机、圆点和两个加载形状 |
| `@cueplusplus/ui/forms` | 用户输入、切换、摘取或拖动的所有类型 |
| `@cueplusplus/ui/overlays` | 所有浮出水面的:对话框、工作表、菜单、工具提示、命令调色板 |
| `@cueplusplus/ui/chrome` | 控制台家具:面板、行、条、标签、树轮廓和 `Inspector` 版式 |
| `@cueplusplus/ui/layout` | 页面结构:卡片、堆栈、网格、, `Bento`,则 `Preview` 框架、披露和导航形状 |
| `@cueplusplus/ui/layout/carousel` | 需求 `embla-carousel-react` |
| `@cueplusplus/ui/layout/resizable` | 需求 `react-resizable-panels` |
| `@cueplusplus/ui/instruments` | 读出:米,花花,桌子,日志, `CodeBlock` 和两个设备框架 |
| `@cueplusplus/ui/instruments/data-table` | 需求 `@tanstack/react-table` |
| `@cueplusplus/ui/instruments/log-viewer` | 需求 `@tanstack/react-virtual`, (中文(简体) ), `anser` |
| `@cueplusplus/ui/charts` | 系统符号中的标记,加上绝对调色板和坡道;需要 `recharts` |
| `@cueplusplus/ui/date` | 日历、拾取器和分日期/时间字段;需要 `react-day-picker`, (中文(简体) ), `date-fns`, (中文(简体) ), `react-aria-components`, (中文(简体) ), `@internationalized/date` |
| `@cueplusplus/ui/color` | 拾取器套用配置器编辑 : `react-aria-components` |
| `@cueplusplus/ui/configurator` | 用于编辑符号层的活出并导出其编辑内容的浮动面板; 需要 `react-aria-components` |
| `@cueplusplus/ui/flow` | 戴着信使的回放:节点卡、手柄、信号接线;需要 `@xyflow/react` (+ 数) `./flow.css`(中文(简体) ) |
| `@cueplusplus/ui/chat` | 多代理记录:信息、作曲、HITL问题、代理颜色 |
| `@cueplusplus/ui/agent-runtime` | chat 下的流层; 需要 `@assistant-ui/react` |
| `@cueplusplus/ui/elements` | (a) 代理商自己的表面,从助理-伊销售,并重新油漆到代币上 `lucide-react` 财务报告和审定财务报表 `heat-graph` (+ 数) `./elements.css`(中文(简体) ) |
| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; 需求 `react-markdown`, (中文(简体) ), `rehype-sanitize`, (中文(简体) ), `micromark-extension-gfm-table`, (中文(简体) ), `mdast-util-gfm-table` |
| `@cueplusplus/ui/elements/generative` | 基因UI 渲染器及其谱(+) `./elements/generative.css`(中文(简体) ) |
| `@cueplusplus/ui/elements/replay` | 脚本会话重放框架 |
| `@cueplusplus/ui/dmx` | 512个字节按有线速率:栏,条,补丁栏,通道网格 |
| `@cueplusplus/ui/midi` | 测序器乐器:键盘、音乐钟、尺子、分析器、阈值铁路 |
| `@cueplusplus/ui/system` | `ThemeProvider`, (中文(简体) ), `prepaintScript`,则 `Density` 岛,门户框架, `isSafeTokenValue` |
| `@cueplusplus/ui/theming` | `createTheme()`, (中文(简体) ), `contrastReport()` 编辑 `--cue-*` 作为常数的词汇表 |

四个样式表导出 . `@cueplusplus/ui/styles.css` 总是进口;其他三个是: 只有在你用他们画的东西的时候才进口.. `@cueplusplus/ui/elements.css`, (中文(简体) ), `@cueplusplus/ui/flow.css` 财务报告和审定财务报表 `@cueplusplus/ui/elements/generative.css`。 。 。 .

## 显示组件 : `Preview`, (中文(简体) ), `Inspector`, (中文(简体) ), `CodeBlock`

显示组件而非仅使用组件的一页有三块——docs页面,设计 复议,设置屏幕带有活的样本. 从根管和从 它的子路径, 不需要一个可选的对等点.

### `Preview` - 舞台上的一个部分

从 `@cueplusplus/ui/layout`具有标本舞台的框架,a `tools` 在顶端的插槽 权利与a `footer`。 。 。 . `label` 因为框架是 `role="group"` 由它命名 。 这个 舞台可以携带自己的 `theme`, (中文(简体) ), `mode`, (中文(简体) ), `density` 财务报告和审定财务报表 `font`他们中没有任何人 属性和继承页面.

**一个舞台 `theme` 需要页面上的主题样式表.** 命名主题不加载: 阶段范围为 `[data-theme="<name>"]`这样 `@cueplusplus/theme-<name>/theme.css` 必须是 与其它调色板一样导入,或者舞台上画出空白底片,没有出错. 这个 以下示例显示 `terminal` 编号 `cue` 页面,所以两者都是导入和注册的:

```css
/* app/globals.css */
@import "tailwindcss";
@import "@cueplusplus/ui/styles.css";
@import "@cueplusplus/theme-cue/theme.css";
@import "@cueplusplus/theme-terminal/theme.css";
```

```tsx
import cue from "@cueplusplus/theme-cue";
import terminal from "@cueplusplus/theme-terminal";
import { Chip } from "@cueplusplus/ui";
import { Preview } from "@cueplusplus/ui/layout";
import { ThemeProvider } from "@cueplusplus/ui/system";

export default function ChipPage() {
  return (
    <ThemeProvider themes={[cue, terminal]} theme="cue" density="compact" mode="system">
      <Preview label="Chip preview" theme="terminal" resizable footer="terminal · compact">
        <Chip tone="accent">Standby</Chip>
      </Preview>
    </ThemeProvider>
  );
}
```

-   只有舞台改变主题. `tools`, (中文(简体) ), `footer`调整了手柄和打开的任何东西 所以驱使标本的控件 总是像周围的一页.
-   `resizable` 每轴加一个握把,160–1280×96–960 px默认,按指针和按 键盘(arros step 8 px, Shift+arrow 64 px). 过 `{ axis, minWidth, maxWidth, minHeight, maxHeight }` 以收缩. 重排预览可以填充容器的宽度 .
-   这是一个客户部分(`"use client"`) (中文(简体) ).

### `Inspector` 设置面板的布局

从 `@cueplusplus/ui/chrome`. 标签和控制行的标题部分,然后是页脚——形状 属性边栏或扳手菜单。 控制器是图书馆的.

```tsx
import { Button, Input, SegmentedControl } from "@cueplusplus/ui";
import { Inspector } from "@cueplusplus/ui/chrome";

const sizes = [
  { value: "sm", label: "Small" },
  { value: "md", label: "Medium" },
  { value: "lg", label: "Large" },
];

export function ButtonInspector() {
  return (
    <Inspector.Root>
      <Inspector.Section label="Variants">
        <Inspector.Row label="Size">
          <SegmentedControl items={sizes} defaultValue="md" />
        </Inspector.Row>
        <Inspector.Row label="Label" htmlFor="button-label">
          <Input id="button-label" defaultValue="Run cue" />
        </Inspector.Row>
      </Inspector.Section>
      <Inspector.Footer note="preset · primary" action={<Button size="sm">Reset</Button>} />
    </Inspector.Root>
  );
}
```

-   一行命名它的控制。 与 `htmlFor` 标签是 `<label>` 对于那个id;没有它,行 铺设 `label` 控制为 `aria-label`,除非控制本身已经命名.
-   一行是一行,直到督察宽到18雷姆,然后在控制旁贴上标签。 这是一个 容器查询,所以它跟随 弹出或侧边栏 检查员坐在那里,而不是取景口.
-   `Inspector` 没有钩子,也没有钩子 `"use client"`,所以服务器组件可以渲染出.

### `CodeBlock` ——带有标题和副本按钮的代码

从 `@cueplusplus/ui/instruments`。 。 。 .

```tsx
import { CodeBlock } from "@cueplusplus/ui/instruments";

export function ButtonSource() {
  return <CodeBlock label="button.tsx" language="jsx" code={'<Button variant="primary">Run cue</Button>'} />;
}
```

-   `code` 打印成逐字记录, 复制按钮复制的就是这个. `label` 标题和 默认语言; `language` 默认为 `"tsx"`。 。 。 .
-   没有语法高亮调色板. `language="jsx"` 选择标签名称、属性名称和 将主题分出三行;其他语言打印平原.

## 机器可读的那一半

这包装了自己的货单: `@cueplusplus/ui/manifest.json` 是每个 每一份配套文件都有SHA-256组件,以及 `@cueplusplus/ui/manifest/components/<name>.json` 是一个完整的组件——道具、变体、 它用它来画, 和手写笔记 当它是错误的选择。 除了他们, `@cueplusplus/ui/manifest/tokens.json` 是标志性词汇 `@cueplusplus/ui/manifest/fixtures.json` 游乐场固定目录。 代理或代码 生成器应该读取这些而非猜测道具名称 .

同样的表面公布于 [https://ui.cueplus.com (英语)](https://ui.cueplusplus.com/),与文件网站,现场 厨房水槽和CUE++的代理技能.

## 其余的就在这

-   从另一个项目安装和使用: [`docs/CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md)
-   每个组件,都有道具和活生生的例子: [https://ui.cueplus.com/docs/组件](https://ui.cueplusplus.com/docs/components)
-   密度和密度 `--cue-*` 合同: [https://ui.cueplus.com/docs/theming (英语)](https://ui.cueplusplus.com/docs/theming)
-   整个表面在一页: [https://ui.cueplus.com/kitchen-sink 页面存档备份,存于互联网档案馆](https://ui.cueplusplus.com/kitchen-sink)
-   每个机器可读的表面,都有复制版片段: [https://ui.cueplus.com/ai (中文(简体) )](https://ui.cueplusplus.com/ai)
-   您的版本有什么变化 : `node_modules/@cueplusplus/ui/CHANGELOG.md`

## 常见问题

### @cueplusplus/ui 是什么？

CUE\+\+ 设计系统组件:由 @cueplus/tokens所驱动的 Tailwind v4 有底部UI外形的包装\.

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

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

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

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

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

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

### @cueplusplus/ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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