# @caqophony/ui 中文文档

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

版本：0\.6\.3
npm 元数据更新时间：2026-11-09T19:19:50.805Z
中文译文更新时间：2026-11-09T18:05:08.962Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：494 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，chart\.js ^4\.5\.1，react-dom ^18\.0\.0 \|\| ^19\.0\.0，react-chartjs-2 ^5\.3\.1
- 首次发布：2026-10-13T04:10:52.383Z
- 最新版本发布：2026-11-09T19:19:50.598Z
- 近 30 天下载量：2014（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

通用,可选的React UI再利用库(Gossamer sorders). 中央维持由Caqophony.

## 安装

```sh
npm install @caqophony/ui
```

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

## README

# @caqophony/ ui (英语)

在Gossamer语义设计符号上构建的通用反应UI组件 (道风. 由Caqophony和麻省理工学院许可集中维护.

**此库是可选的 .** 由 Caqophony 生成的 Apps 可以使用它,这样 常见的UI( 按钮、 牌、 对话框、 表格、 页面布局) 不重生成 从头到尾的每个应用程序, 这保存了符号。 这是礼貌,不是SDK: 在生成的应用程序中,不需要它。 如果为一个项目停止再利用, 应用程序的构建没有此依赖性,其组件来自 刮伤。 它只包含通用UI:没有平台、产品、认证或 数据访问码.

## 安装

```bash
pnpm add @caqophony/ui        # or npm i / yarn add
```

同伴依赖性 : `react` 财务报告和审定财务报表 `react-dom` (单位:千美元)`^18 || ^19`) (中文(简体) ). `@caqophony/ui/charts` 需要可选的同位素 `chart.js` 财务报告和审定财务报表 `react-chartjs-2`: 安装它们 如果你输入了子路径,你自己。 没有 `next` 依赖性.

一揽子措施仅限无害环境管理。 子路径类型( N)`@caqophony/ui/charts`决心通过 页:1 `exports` 映射, 因此 TypeScript 需要 `moduleResolution` 联 合 国 `bundler` (或 `node16`编号 :`nodenext`) (中文(简体) ).

`DiceBearAvatar` 使图像从 `api.dicebear.com` 在运行时间,所以它 从用户的浏览器中创建网络请求; 不要使用它 无法接受.

## 样式 (Tailwind v4)

组件使用 Gossamer 符号类(`bg-primary`, (中文(简体) ), `text-muted-foreground`, (中文(简体) ), `border-intent-error-border`(中文(简体) ). 尾风 v4 不扫描 `node_modules` 而没有这些名称的映射, 因此导入此软件包的样式表 在您的全球CSS中:

```css
@import 'tailwindcss';
@import '@caqophony/ui/styles.css';
```

`styles.css` 定义符号变量(亮和暗) `@media (prefers-color-scheme: dark)`,同样的OS设置 Tailwind v4's `dark:` 将它们映射到 尾风v4 颜色/辐射/z-index/ Opacity/长期公用事业并登记 软件包已建为 Tailwind 文件 `@source`覆盖任意 `--token` 之后 导入到再主题.

## 样式 (Tailwind v3)

在Caqophony monorepo内部,一个应用将 Gossamer 预设并添加 库到 `content`。不要手动映射符号 `theme.extend.colors`数字 : 左边 `bg-primary-solid` 没有规则,或者规则读取变量 任何事物都不宣示,任何事物都不引起错误.

```ts
import { gossamerPreset } from '@caqophony/tokens/tailwind-preset';

export default {
  presets: [gossamerPreset],
  darkMode: ['class'],
  content: ['./app/**/*.{ts,tsx}', '../../packages/ui/src/**/*.{ts,tsx}'],
};
```

预设图示库的符号并声明其变量(亮度,以及 黑暗的下层 `.dark`,并增加公用事业和 `not-first:` 变体 a v3 主题不能表达。 它只添加名字: 股票 Tailwind 保留它的值, 您的 `theme` 胜过预设,而您的 CSS 声明的变量胜过预设 预设的.

`pnpm exec tsx scripts/check-ui-classes-compile.ts` 覆盖两个表面 绘制库: 在 Tailwind v3 上的 monorepo 产品应用和生成 应用程序 `globals.css` 加号 `styles.css` 在Tailwind v4, 各对各班 水面可以到达。 它的失败在类 Tailwind 不产生规则 规则读取默认无法到达元素的变量。 它运行在 预推.

预设不发布 。 单管外的 Tailwind v3 应用程序需要 `./node_modules/@caqophony/ui/dist/**/*.js` 内 `content` 和同样的地图, 变量、公用事业和自身配置中的变量,或 Tailwind v4 和 `styles.css` 见上文.

## 动画和散文

在尾风v4, `styles.css` 定义 `animate-in` 编号 : `animate-out` 水电费 模式和工具提示的使用和载荷 `@tailwindcss/typography` 页:1 `MarkdownRenderer`,哪个 `@caqophony/ui` 取决于。 没有什么可补充的. 在 Tailwind v3 上安装 `tailwindcss-animate` 财务报告和审定财务报表 `@tailwindcss/typography` 作为 插件 .

## 使用

```tsx
import { Button, Card, PageContent } from '@caqophony/ui';
import { BarChart } from '@caqophony/ui/charts';
import { MarkdownRenderer } from '@caqophony/ui/markdown';
import { MarketingCta, MarketingFooter } from '@caqophony/ui/marketing';
import { Band, Display, Stack, Text } from '@caqophony/ui/material';
```

`@caqophony/ui/material` 持有由下列区域组成的设计页面:, 显示类型、布局和平面插图。 每种颜色都是一种象征,所以 主题更改覆盖全部。 设置 a `Band`是因为 `surface` 改为 `night` 和每个 图书馆内部组件在暗地上读取,没有自己的道具.

`@caqophony/ui/material-tones` 持有 `FILL` 财务报告和审定财务报表 `STROKE`艺术画 进去 还有 `@caqophony/ui/material-art` 没有的条目 `'use client'` 指令,这样服务器组件就可以使用它们. 其他入境点都带着 该指令.

应用程序本身的艺术是数据,而不是代码: SVG 元素的闭合树,以音量表示,以a `*.art.json` 文件输入 `art/` 旁边 `app/`图书馆外. `Art` 从 `@caqophony/ui/material-art` 画它,作为一个 `Figure`一个孩子,没有别的 在槽中创建元素。 阴影 `paper` 在低透明度下保持一步: `paper` 保持颜色为暗模式 `mist-*` 没有.

## 许可证

麻省理工学院,看 `LICENSE`。 。 。 .

## 常见问题

### @caqophony/ui 是什么？

通用,可选的React UI再利用库\(Gossamer sorders\)\. 中央维持由Caqophony\.

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

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

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

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

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

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

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

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

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

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

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

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