# @bcc-code/component-library-vue 中文文档

规范地址：https://npmcn.com/package/%40bcc-code/component-library-vue/

版本：1\.5\.4
npm 元数据更新时间：2026-10-26T10:51:38.180Z
中文译文更新时间：2026-11-07T21:16:23.346Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bcc-code/component-library-vue
原文对照：https://npmcn.com/package/%40bcc-code/component-library-vue/?lang=original
源码仓库：https://github.com/bcc-code/bcc-design

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

- 包体积（解压后）：14.7 MB，933 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：vue ^3\.5\.0
- 首次发布：2026-02-20T11:59:53.357Z
- 最新版本发布：2026-10-26T10:51:37.802Z
- 近 30 天下载量：2492（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：386（近 12 个月 386 个）

## 中文简介

基于 PrimeVue 和 BCC 设计符的扩展 Vue 组件库

## 安装

```sh
npm install @bcc-code/component-library-vue
```

也可以使用：`pnpm add @bcc-code/component-library-vue`、`yarn add @bcc-code/component-library-vue`、`bun add @bcc-code/component-library-vue`

## README

# @bcc-code/ 组件- 图书馆- vue

Vue 3 组件库 [首选项](https://v4.primevue.org/) 和BCC设计标志。 你个 **仅限** 需要此软件包- 没有单独的 Tailwind 或 PrimeVue 安装 .

### [故事书链接](https://components.bcc.no/)

## 安装

```bash
pnpm add @bcc-code/component-library-vue
# or
npm install @bcc-code/component-library-vue
# or
yarn add @bcc-code/component-library-vue
```

**最低要求:** 3号.

**对 PNPM 安装的注意 :** 图书馆使用 `@bcc-code/icons-vue` 财务报告和审定财务报表 `@bcc-code/design-tokens`在自己的应用程序中使用(例如:. `import { CheckIcon } from '@bcc-code/icons-vue'`)无需明确在自己安装 `package.json`中,添加到您的项目中 **`.npmrc`** 所以,pnpm举起他们:

```ini
public-hoist-pattern[]=@bcc-code/icons-vue
public-hoist-pattern[]=@bcc-code/design-tokens
```

然后运行 `pnpm install` 再来一次 Npm 或 Yarn 不需要这样.

## 快开始

1.  **注册库** 在您的应用程序中( 例如 ). `main.ts`:

```ts
import { createApp } from 'vue';
import App from './App.vue';
import { BccComponentLibrary } from '@bcc-code/component-library-vue';

const app = createApp(App);
app.use(BccComponentLibrary);
app.mount('#app');
```

2.  **添加样式** 使用以下两个选项之一.

### 样式 选项 1 — 建议: 应用程序中的全尾风

如果您想要在您的模板中设置 Tailwind 工具类, 请使用此选项, 同时仍然允许库的组件正确渲染 .

1.  **添加 Tailwind Vite 插件** (包带Tailwind作为依赖;你只把它接上):

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

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

2.  **导入您主 CSS 文件的主题** (例如:. `src/main.css` 或者说 `src/assets/main.css`:

```css
@import '@bcc-code/component-library-vue/theme.css';
/* Optional, if not already included */
@import '@bcc-code/component-library-vue/archivo-font.css';
```

单输入就够了. `theme.css` 包括:

-   BCC设计标志, `@theme` 编号 : `@utility` 定义,以及设计系统CSS的其余部分 `src/style.css` (包括特定组成部分的规则,例如: `BccInput` 图标大小和 `BccButton` 上下文符号).
-   `library-utilities.css`预编的"尾风" **工具类** 图书馆模板内使用的规则(你的构件不能从已公布的JS推断出).

执行 **没有** 依赖 `library-utilities.css` 仅包含最小的“基”导入:您仍然需要完整的 `theme.css` (或 `style.css` 用于选项2,因此存在非通用组件样式和符号.

### 样式 选项 2 - 仅预建 CSS

如果您不想在您的项目中看到Tailwind, 而只需要库的风格和组件, 请使用 .

在您的条目文件中( 如 . `main.ts`在安装应用程序之前:

```ts
import '@bcc-code/component-library-vue/style.css';
```

您只获得 BCC 主题和组件样式; 应用程序中没有 Tailwind 工具 .

## 品牌颜色

图书馆以BCC teal为品牌颜色. BCC配置外的应用程序可以在库导入后,通过在自己的CSS中重新定义两个坡道来提供自己的调色板. 不需要配置或构建设置——这些都是普通自定义属性.

```css
@import '@bcc-code/component-library-vue/theme.css';

/* Drives the semantic brand tokens: primary buttons, checkboxes and radio
   buttons, focus and selected states, links, and the bg-brand-* / text-brand-*
   Tailwind utilities. One set of values covers both color schemes — the
   semantic layer picks different steps in dark mode. */
:root {
    --color-brand-100: #eff6ff;
    --color-brand-200: #dbeafe;
    --color-brand-300: #bfdbfe;
    --color-brand-400: #93c5fd;
    --color-brand-500: #60a5fa;
    --color-brand-600: #3b82f6;
    --color-brand-700: #2563eb;
    --color-brand-800: #1d4ed8;
    --color-brand-900: #1e40af;
    --color-brand-1000: #172554;
}

/* Drives the ctx-brand-* context utilities. This ramp is mode-aware: step 100 is
   always the step furthest from the text color, so the dark values are the same
   palette in reverse. */
:root {
    --color-default-bcc-100: #eff6ff;
    --color-default-bcc-200: #dbeafe;
    --color-default-bcc-300: #bfdbfe;
    --color-default-bcc-400: #93c5fd;
    --color-default-bcc-500: #60a5fa;
    --color-default-bcc-600: #3b82f6;
    --color-default-bcc-700: #2563eb;
    --color-default-bcc-800: #1d4ed8;
    --color-default-bcc-900: #1e40af;
    --color-default-bcc-1000: #172554;
}

.dark {
    --color-default-bcc-100: #172554;
    --color-default-bcc-200: #1e40af;
    --color-default-bcc-300: #1d4ed8;
    --color-default-bcc-400: #2563eb;
    --color-default-bcc-500: #3b82f6;
    --color-default-bcc-600: #60a5fa;
    --color-default-bcc-700: #93c5fd;
    --color-default-bcc-800: #bfdbfe;
    --color-default-bcc-900: #dbeafe;
    --color-default-bcc-1000: #eff6ff;
}
```

积木得在图书馆的CSS之后才能赢得级联. 在备选案文1中,这意味着将其置于以下 `@import` 在您的 CSS 主文件中; 在选项2 中, 在样式表之后加载 `style.css`二者均经核实有效.

命名注释 : `--color-default-bcc-*` 留着 `bcc` 在它的名称中,因为它来自Figma符号集,而不是因为它必须持有BCC的颜色. 支持用自己的调色板来覆盖它.

跳过第二道斜坡 `ctx-brand-*` 泰尔,而其他一切都在变化, 这通常不是你想要的.

### 选择值

第800步带有小的文字和主按钮背景,因此对照其中的对比要求来检查 [颜色文档](https://components.bcc.no/?path=/docs/foundations-colors--docs) —— 4.5: 1对步100和对白. 提供完整的从光到暗的射程,而不是10个同调的荫道,因为镜面的暗坡取而有之.

# 构成部分

所有组件都与 `Bcc`在模板中使用或在全球注册到您 `main.ts`。 。 。 .

**示例**

```vue
<template>
    <div class="flex gap-4 p-4">
        <BccButton label="Save" />
        <BccInput v-model="name" placeholder="Name" />
    </div>
</template>

<script setup lang="ts">
import { BccButton, BccInput } from '@bcc-code/component-library-vue';
import { ref } from 'vue';

const name = ref('');
</script>
```

**示例**

```ts
// main.ts
...
import { BccButton, BccInput } from '@bcc-code/component-library-vue';

// After app.use(BccComponentLibrary)
app.component('BccButton', BccButton);
app.component('BccInput', BccInput);
```

图书馆都出口了 **自定义BCC 组件** (例如:. `BccBadge`, (中文(简体) ), `BccFrame`, (中文(简体) ), `BccReact`和 **包裹的 PrimeVue 组件** (例如:. `BccButton`, (中文(简体) ), `BccDialog`, (中文(简体) ), `BccDataTable`PrimeVue 服务( Toast, 确认, 对话框) 由 `BccComponentLibrary`; 使用可堆肥 `useToast`, (中文(简体) ), `useConfirm`,以及 `useDialog` 需要的时候从图书馆寄来的.

## 套装大小

ES构建为可树可摇:您为导入的组件付费,而不是为整个库付费. 导入单个小部件在Vue上方添加了几克B;更重的部件(`BccDataTable`, (中文(简体) ), `BccEditor`, (中文(简体) ), `BccDatePicker`其成本因带有其PrimeVue执行和风格而按比例增加.

消费者方面需要两点:

-   从软件包根导入,并让你的捆绑机摇动它—— `import { BccBadge } from '@bcc-code/component-library-vue'`。不需要深入输入个人文件.
-   建设为生产. Dev 服务器没有树摇,所以 `pnpm dev` 总是看起来像整个图书馆都装满了.

样式是 **没有** 树形: `style.css` (备选案文2)始终包含每个组成部分的规则。 如果CSS规模很重要,则使用备选案文1(`theme.css` + Tailwind 在您的应用中),其中 Tailwind只释放您实际使用的公用事业.

* * *

# 发展

```bash
pnpm install
pnpm run start        # Storybook on port 6006
pnpm run build        # Typecheck, types, and Vite build
pnpm run docs:ai      # Build Storybook, then generate AI-ready docs outputs
pnpm run build:llms   # Regenerate AI docs from an existing storybook-static/index.json
pnpm run build:vite   # Vite build only (includes theme.css)
```

### 构建输出形状( 不平整它)

`vite build` 发射 **每个模块一个文件** (单位:千美元)`output.preserveModules`而不是一个捆绑,和 `package.json` 声明 `"sideEffects": ["**/*.css"]`两者都要求消费者对一揽子方案进行树摇,而其中任何一个都无所作为——见 [369号](https://github.com/bcc-code/bcc-design/issues/369)。 。 。 .

单个捆绑不能被动摇的原因: PrimeVue 的每个组件样式模块调用 `BaseStyle.extend()` 和主题预设调用 `definePreset()` 在模块顶级。 拼接成一个文件,这些成为消费者捆绑者必须保存的不洁的上层声明,这把~785 kB未用代码拖入了每一个消费者捆绑.

触摸建筑时要记住的后果:

-   依赖被捆绑并重新扎根于 `dist/vendor/<package>/...`. 特别是PrimeVue **绝对不能** 改为外部: `@primevue/icons` 补丁,在BCC图标中互换只能通过我们自己的构建输出到达消费者.
-   `preserveModules` 只支持 ES 格式, 因此 UMD 捆绑由 : `vite.config.umd.ts`。 。 。 .
-   `pnpm run test:bundle-size` 捆绑一个探测器应用程序对 `dist` 如果导入一个组件的成本超过40 kB,则失败。 它运行在CI 在建设之后.

### AI-已准备好的文档输出

`pnpm run docs:ai` 生成公开的 AI 文档文物 `storybook-static/`数字 :

-   `/llms.txt`: 公共docs页面的Markdown索引.
-   `/llms-full.txt`: 为所有公开的文档页加装了Markdown.
-   `/docs/<page>.md`:每页Markdown镜像"故事本"多克路由,例如. `/docs/foundations-colors--docs` - > (中文) `/docs/foundations-colors--docs.md`。 。 。 .

`build-storybook` 在"故事本"构建后运行同一代,所以部署的docs在运行时获取这些文件. 生成的文件存在 `storybook-static/`\- CI不需要进行漂移检查,除非这些建筑文物是后来进行的.

生成器使用故事本 `storybook-static/index.json` 作为真相的路由来源,将MDX转换为可读的Markdown,并从故事元数据中总结出自自動docs故事页面. 它只读取来自 `docs` 财务报告和审定财务报表 `src` 并排除私人/内部/机密路径、内存文件、依赖性文件夹、构建输出和缓存.

覆盖已公布的 URL 基础 `LLMS_BASE_URL=https://your-docs-host pnpm run build:llms` 如果需要的话。 只有静态的Markdown和JSON文献文物生产.

### 文件夹结构( 在哪里工作)

-   `src/components/custom`: 新建BCC-第一组件和组件特有样式/逻辑.
-   `src/components/wrapped`: PrimeVue 包裹组件(`Bcc*`)我们适应API,默认,插槽和行为.
-   `src/styles`: 设计-系统 CSS层(主题,上下文,语义符号,公用类).
-   `src/index.ts`: 公共出口;在此添加新的组件/可组件,使消费者可以进口.
-   `docs` 财务报告和审定财务报表 `*.mdx`: Storybook docs页和设计指导内容.
-   `*.stories.ts`编号 :`*.mdx` (单位:千美元) `src` 或者说 `docs`: 组件的演示文稿、文档和回归覆盖.

### 补丁 PrimeVue 图标

一些 PrimeVue 图标被替换为 [@bcc-code/icons-vue (英语)](https://www.npmjs.com/package/@bcc-code/icons-vue) 因此,图书馆使用BCC图标. 补丁由 pnpm 的内置补丁维护 .

**1\. 开始或重新进入补丁**

```bash
pnpm patch @primevue/icons
```

pnpm 将打印一个路径到一个可写入的软件包副本(例如. `node_modules/.pnpm_patches/@primevue/icons@4.5.4`) (中文(简体) ).

**2\. 编辑图标映射**

-   **主枪管:** 编辑 `index.mjs` 在文件夹里。 每一行从 `@bcc-code/icons-vue` 定义一个覆盖,例如:
    
    ```js
    export { ExpandMoreIcon as ChevronDownIcon } from '@bcc-code/icons-vue';
    ```
    
-   **平角文件 :** 更改主机后 `index.mjs`,运行同步脚本,使每个图标都拥有 `index.mjs` (例如:. `chevrondown/index.mjs`更新后使用相同的BCC组件:
    
    ```bash
    pnpm run sync:primevue-icon-patches
    ```
    
    那样两个 `@primevue/icons` 财务报告和审定财务报表 `@primevue/icons/chevrondown` (和其他被覆盖的图标)使用BCC图标.
    

**3\. 保存补丁**

从 **项目根** (何处) `package.json` ),运行:

```bash
pnpm patch-commit <path-pnpm-printed-in-step-1>
```

示例,如果 pnpm 打印 `~/Projects/bcc-design/component-library/node_modules/.pnpm_patches/@primevue/icons@4.5.4`数字 :

```bash
pnpm patch-commit node_modules/.pnpm_patches/@primevue/icons@4.5.4
```

补丁是写给 `patches/@primevue__icons.patch` 自动应用 `pnpm install`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @bcc-code/component-library-vue 是什么？

基于 PrimeVue 和 BCC 设计符的扩展 Vue 组件库

### 如何安装 @bcc-code/component-library-vue？

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

### @bcc-code/component-library-vue 支持 TypeScript 吗？

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

### @bcc-code/component-library-vue 支持 ESM 还是 CommonJS？

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

### @bcc-code/component-library-vue 可以商用吗？

@bcc-code/component-library-vue 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bcc-code/component-library-vue 的下载量有多少？

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

### @bcc-code/component-library-vue 还在维护吗？

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