@bcc-code/ 组件- 图书馆- vue
Vue 3 组件库 首选项 和BCC设计标志。 你个 仅限 需要此软件包- 没有单独的 Tailwind 或 PrimeVue 安装 .
故事书链接
安装
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举起他们:
public-hoist-pattern[]=@bcc-code/icons-vue
public-hoist-pattern[]=@bcc-code/design-tokens
然后运行 pnpm install 再来一次 Npm 或 Yarn 不需要这样.
快开始
- 注册库 在您的应用程序中( 例如 ).
main.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');
- 添加样式 使用以下两个选项之一.
样式 选项 1 — 建议: 应用程序中的全尾风
如果您想要在您的模板中设置 Tailwind 工具类, 请使用此选项, 同时仍然允许库的组件正确渲染 .
- 添加 Tailwind Vite 插件 (包带Tailwind作为依赖;你只把它接上):
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [vue(), tailwindcss()],
// ...
});
- 导入您主 CSS 文件的主题 (例如:.
src/main.css或者说src/assets/main.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在安装应用程序之前:
import '@bcc-code/component-library-vue/style.css';
您只获得 BCC 主题和组件样式; 应用程序中没有 Tailwind 工具 .
品牌颜色
图书馆以BCC teal为品牌颜色. BCC配置外的应用程序可以在库导入后,通过在自己的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步带有小的文字和主按钮背景,因此对照其中的对比要求来检查 颜色文档 —— 4.5: 1对步100和对白. 提供完整的从光到暗的射程,而不是10个同调的荫道,因为镜面的暗坡取而有之.
构成部分
所有组件都与 Bcc在模板中使用或在全球注册到您 main.ts。 。 。 .
示例
<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>
示例
// 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, (中文(简体) ), BccDataTablePrimeVue 服务( 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只释放您实际使用的公用事业.
发展
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号。 。 。 .
单个捆绑不能被动摇的原因: 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 (英语) 因此,图书馆使用BCC图标. 补丁由 pnpm 的内置补丁维护 .
1. 开始或重新进入补丁
pnpm patch @primevue/icons
pnpm 将打印一个路径到一个可写入的软件包副本(例如. node_modules/.pnpm_patches/@primevue/[email protected]) (中文(简体) ).
2. 编辑图标映射
-
主枪管: 编辑
index.mjs在文件夹里。 每一行从@bcc-code/icons-vue定义一个覆盖,例如:export { ExpandMoreIcon as ChevronDownIcon } from '@bcc-code/icons-vue'; -
平角文件 : 更改主机后
index.mjs,运行同步脚本,使每个图标都拥有index.mjs(例如:.chevrondown/index.mjs更新后使用相同的BCC组件:pnpm run sync:primevue-icon-patches那样两个
@primevue/icons财务报告和审定财务报表@primevue/icons/chevrondown(和其他被覆盖的图标)使用BCC图标.
3. 保存补丁
从 项目根 (何处) package.json ),运行:
pnpm patch-commit <path-pnpm-printed-in-step-1>
示例,如果 pnpm 打印 ~/Projects/bcc-design/component-library/node_modules/.pnpm_patches/@primevue/[email protected]数字 :
pnpm patch-commit node_modules/.pnpm_patches/@primevue/[email protected]
补丁是写给 patches/@primevue__icons.patch 自动应用 pnpm install。 。 。 .
许可证
阿帕奇 - 2.0