# @ac-design/design-system 中文文档

规范地址：https://npmcn.com/package/%40ac-design/design-system/

版本：2\.11\.0
npm 元数据更新时间：2026-11-01T06:39:12.732Z
中文译文更新时间：2026-11-06T04:56:01.607Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：1.7 MB，387 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：20 个
- peer 依赖：vue ^3\.5\.0，echarts ^6\.0\.0，@lucide/vue ^1\.0\.0
- 首次发布：2026-10-08T05:27:44.909Z
- 最新版本发布：2026-11-01T06:39:12.575Z
- 近 30 天下载量：5029（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

AppsCode设计系统:Tailwind CSS v4主题和Vue 3组件.

## 安装

```sh
npm install @ac-design/design-system
```

也可以使用：`pnpm add @ac-design/design-system`、`yarn add @ac-design/design-system`、`bun add @ac-design/design-system`

## README

# AppsCode 设计系统

每个AppsCode控制台的设计系统(云-ui,集群-ui,kubedb-ui,平台-ui,计费-ui,自主机-ui.): a **尾风 CSS v4 主题** 财务报告和审定财务报表 **Vue 3 组件**,并有一个文件站点显示每个组件的活性.

它取代了旧的 Bulma/SCSS 图书馆(`@appscode/design-system` 2.x) (简体中文). 从旧图书馆导入的应用程序的每个组件都有一个替换器在这里,文件的"迁移"页面将旧道具映射到新道具.

```sh
npm install
npm run dev          # docs site at http://localhost:5173
```

## 里面有什么东西

|  |  |
| --- | --- |
| **主题** | `src/lib/theme.css`: 颜色平面,语义符号(文本,边框,表面),类型平面,弧度,阴影和一个完整的黑暗主题,作为一个 Tailwind `@theme`。 。 。 . |
| **构成部分** | 101 Vue 组件(计算诸如 `AcDropdownItem`)分为8个组,以下列举. |
| **编辑器** | `AcCodeEditor` 财务报告和审定财务报表 `AcFileEditor` 代码 6, 在 `/editor` 输入后,其他应用程序就不会捆绑CodeMirror. |
| **图表** | 关于Apache ECharts 6(Cloud-ui的引擎)的七张图表,载于 `/charts` 输入. `echarts` 是一个可选的同伴依赖. |
| **可编曲** | `useColorMode()` (轻/暗/系统), `useFontScale()` (文本大小), `useToast()` (通知), `useBrandColor()` (在运行时重置品牌), `useTablePagination()` 财务报告和审定财务报表 `useApiPagination()`, (中文(简体) ), `useBulkSelection()`, (中文(简体) ), `useFormValidation()`,以及 `copyText()`。 。 。 . |
| **标记** | `AcLogo`: AppsCode 标志并标记为遵循暗模式的内置SVG. |
| **文档网站** | 开始,基础,每个组件的一页(活游乐场,实例,指南,可访问性,API表格)和完整的例子页. |

### 构成部分

| 组 | 构成部分 |
| --- | --- |
| 元素 | 按钮、按钮组、徽章、标签、 Avatar、 提醒、 Banner、 牌、 分割符、 Kbd、 复制按钮、 命令块、 检查列表 |
| 反馈 | Spinner and preloader, loader, Skeleton, 进步, 循环进步, Toast, 空状态, 错误状态 |
| 表单 | 输入、数字输入、文本区域、代码编辑器、文件编辑器、选择、组合、标签输入、检查框、检查无线电台、无线电卡、切换、切换卡、搜索栏、文件上传、滑动器、日期拾取器、月拾取器、彩色输入、时间拾取器、窗体、格式阵列、密钥变量输入、纹章输入、主题模式、字体缩放 |
| 重叠 | Modal, 删除 Modal, 确认 Modal, 侧面板, Dropdown, Popover, 工具提示 |
| 版式 | Page, Sidebar, Navbar, 页眉, 产品英雄, 内容表, 章节内容, 设置行, 协议, 状态栏, 页脚 |
| 导航 | Breadcrumb, Tabs, steps, Pagination, 本地切换器, 侧式切换器, App切换器, 集群切换器, 通知 |
| 数据 | 表、 散列动作栏、 信息表、 列表、 单元格值 |
| 纸牌 | 稳定卡、特性卡、资源卡、使用卡、成本汇总 |
| 图表(`/charts`(中文(简体) ) | 线形图, 区域图, 栏形图, 甜甜圈图, 地图图, 图表图, 树形图 |

示例页面将它们组合在一起:一个数据库列表,一个数据库细节页面,一个创建向导,设置,空和出错状态,以及一个完整的app shell.

## 看着和感觉

外观和相声是AppsCode云控制台(英语:`cloud-ui`)),因此系统符合云-ui,克贝德-ui,集群-ui和站台-ui.

-   **类型 :** 界面的机器人,标题的Google Sans Flex和代码和资源名的JetBrains Mono,一个14px基.
-   **颜色 :** 白牌在一号 `#f9fafb` 页面,中性灰色(`#252525` 文本,则, `#5c5c5c` 说明, 1 `#ebebeb` 边框) `#00a651` 绿色品牌,以及成功,信息,警告,危险和待决状态,每个都有AA `-strong` 文本颜色.
-   **形状 :** 42px按钮和字段,有10px半径,14px卡和16px对话框. 卡片会停留在边框上;阴影只标记所浮出的东西.
-   **重点:** (单位:千美元) `focus-ring` 用于窗体字段的效用(主边框和一个2px光环),以及按钮上的一个2px抵消环.
-   **暗模式 :** 以班为主. 每个令牌都有一个暗值,因此组件不需要暗特定代码.
-   **图标 :** [卢西德](https://lucide.dev/) (单位:千美元)`@lucide/vue`) (中文(简体) ). 组件从不绘制自己的SVG图标.

## 用在应用程序上

软件包是 [`@ac-design/design-system`](https://www.npmjs.com/package/@ac-design/design-system) 时间npm. `npm run build:lib` 写给 `dist/lib`,以及 `npm pack` 制造可安装的柏油球.

```sh
npm install @ac-design/design-system @lucide/vue
npm install echarts   # only if you use /charts
```

## 造型规则

样式 **尾风工具类和设计符号**。不要写自定义 CSS: 不 `<style>` 块在组件中,没有一次性的类规则。 使用任意值( E)`max-w-[320px]`, (中文(简体) ), `bg-[color-mix(in_srgb,var(--color-primary)_6%,var(--color-surface))]`精确值和任意变量(`[&_.cm-content]:p-2`) 对于标记你没有。 如果真的不能成为有用的东西, 增加一个符号或者 `@utility` 改为 `theme.css`。完整规则在 `CLAUDE.md`。 。 。 .

装入样式有两种方式:

| 应用程序.. | 装入 | 应用程序中的尾风 |
| --- | --- | --- |
| 运行 Tailwind v4( 云- ui, 集群- ui, kubedb- ui, 平台- ui和新应用程序) | `theme.css` | 对 |
| 仍在装入旧的 Bulma/ SCSS 设计系统, 没有 Tailwind | `compat.css` | 没有 |

### 在 Tailwind v4 的应用程序中

```ts
// main.ts: fonts once
import "@fontsource-variable/roboto";
import "@fontsource-variable/google-sans-flex/opsz.css";
import "@fontsource-variable/jetbrains-mono";
```

```css
/* your main CSS file */
@import "tailwindcss";
@import "@ac-design/design-system/theme.css";
```

### 在一个只有旧风格的应用程序中

文件页 **启动 — 现有应用程序** 拥有完整的向导。 简而言之:

```ts
// main.ts (Vite), or the `css` list in nuxt.config.ts: after the old styles
import "./assets/styles/scss/main.scss";
import "@fontsource-variable/roboto";
import "@fontsource-variable/google-sans-flex/opsz.css";
import "@fontsource-variable/jetbrains-mono";
import "@ac-design/design-system/compat.css";
```

-   **`compat.css`** 是图书馆的风格, 预编和栅栏: 它们只在新组件内应用 `!important` 水电设施。 旧页面不变; 此页面已被像素用 kubedb- ui 检查 .
-   **不要在新组件上设置工具类** 两者都装入。 将组件包入您自己的元素中进行间隔.

### 不管怎样

```ts
import { AcButton, AcInput, useToast } from "@ac-design/design-system";
import { AcCodeEditor, AcFileEditor } from "@ac-design/design-system/editor";
import { AcLineChart, AcDonutChart } from "@ac-design/design-system/charts";
```

-   **所需经费:** Vue 3.5+, Vite 5+或 Nuxt 3+, 和类型脚本 `moduleResolution: "bundler"`。每个组件都会在服务器上生成,所以Nuxt SSR工作.
-   **同伴依赖性 :** `vue` ^3.5和 (中文(简体) ) `@lucide/vue` ^1.0, 加上 `echarts` ^6(可选)用于 `/charts`密码Mirror、Ajv和 `yaml` 是普通的依赖关系,仅由从 `/editor`。 。 。 .
-   **暗模式 :** 设置 `.dark` 打开 `<html>` (旧的) `.is-dark-theme` 上课也行,或者打电话 `useColorMode().setMode("dark" | "light" | "system")`。用户的选择保存在旧的下面 `themeMode` 本地Storage 密钥.
-   **敬酒:** 挂载 `<AcToaster />` 一旦靠近根,然后调用 `useToast().success("Saved")` 随便哪里.
-   **品牌颜色 :** `useBrandColor().setColor("#0066cc")` 重置主标. 旧的 `HexToHSL`, (中文(简体) ), `setThemeHSL` 财务报告和审定财务报表 `getThemeHSL` 帮助者以相同名称导出.
-   **路由器链接 :** 组件 `to` 道具使用vue-router的 `RouterLink` 当应用程序注册。 图书馆本身并不依赖于vue-router.

## 脚本

| 命令 | 它会做什么 |
| --- | --- |
| `npm run dev` | 重新生成 API 数据, 然后在 http://localhost: 5173 上启动 Docs 站点 |
| `npm run build` | 重新生成 API 数据、 类型检查, 并将文件站点构建为 `dist/` |
| `npm run preview` | 服务于来自 `dist/` |
| `npm run build:lib` | 将库构建为 `dist/lib`: ES模块, `.d.ts` 文档, `theme.css` 财务报告和审定财务报表 `compat.css` |
| `npm run type-check` | `vue-tsc` 整个项目 |
| `npm run meta` | 重现 `src/docs/generated/component-meta.json` (API表)来自组件类型 |

还没有试跑者,ESLint或Pretier配置。 类型检查和两种构造都必须通过,在浏览器中以光线,暗线和电话宽度检查变化.

## 项目布局

```
src/
  lib/                        the design system (what gets published)
    theme.css                 tokens as a Tailwind @theme, the dark theme, utilities and keyframes
    index.ts                  main entry: every component, composable and public type
    components/               AcButton.vue, AcInput.vue, … one file per component (sub-parts too)
      index.ts                component exports, sorted
      types.ts                shared types (Tone, Variant, Option, SelectOption)
    editor/                   the /editor entry: index.ts, CodeMirror theme, YAML/JSON Schema checks
    charts/                   the /charts entry: index.ts, ECharts setup, ChartFrame.vue (legend, tooltip, sr-only table)
    composables/              useColorMode, useFontScale, useToast, useBrandColor, pagination, selection and form helpers
  docs/                       the documentation site
    nav.ts                    every page: path, title, description, section, group, component
    router.ts                 hash router built from nav.ts
    pages/                    getting-started/, foundations/, components/, examples/
    examples/<slug>/*.vue     one runnable file per example, shown live with its source
    snippets/<page>/*.txt     code samples shown on pages, loaded with ?raw
    components/               doc building blocks: ComponentPlayground, ComponentExample, ApiTables, DoDont…
    layout/                   header, sidebar, table of contents, search
    generated/                component-meta.json, written by scripts/gen-meta.mjs (don't edit)
scripts/
  gen-meta.mjs                reads component types with vue-component-meta → API tables
  copy-theme.mjs              ships theme.css with the library build
  build-compat.mjs            builds compat.css for apps that still load the old styles
public/                       favicon, logos
vite.config.ts                docs site
vite.lib.config.ts            library build (three entries: index, editor/index and charts/index)
```

## 捐款

读取 [克劳德·姆德](https://npmcn.com/package/%40ac-design/design-system/CLAUDE.md) 先说 它是代码库的完整指南,为人们和编码代理编写:上下文,结构,组件和docs模式,写作风格,以及不做的事.

新组件的简短版本:

1.  写入 `src/lib/components/AcThing.vue` 与 `<script setup lang="ts">`每道道道具的JSDoc线, 和主题符号。 导出它从 `src/lib/components/index.ts`及其公共类型 `src/lib/index.ts`。 。 。 .
2.  将示例添加为文件 `src/docs/examples/thing/`从 `@/lib`。 。 。 .
3.  添加 `src/docs/pages/components/ThingPage.vue` 并登记在 `src/docs/nav.ts`。 。 。 .
4.  运行 `npm run dev`。 API 表格从您的类型中重新生成.
5.  在移入页面中添加旧行, 如果它取代了旧库中的东西 .
6.  检查光线、暗线和375px电话宽度,然后运行 `npm run build` 财务报告和审定财务报表 `npm run build:lib`。 。 。 .

提交 `git commit -s`。 。 。 .

## 常见问题

### @ac-design/design-system 是什么？

AppsCode设计系统:Tailwind CSS v4主题和Vue 3组件\.

### 如何安装 @ac-design/design-system？

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

### @ac-design/design-system 支持 TypeScript 吗？

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

### @ac-design/design-system 支持 ESM 还是 CommonJS？

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

### @ac-design/design-system 可以商用吗？

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

### @ac-design/design-system 的下载量有多少？

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

### @ac-design/design-system 还在维护吗？

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