UI 图书馆
📘 查看故事书
调用触摸到的 ii-library 运行 受影响的故事本构建和测试检查 在CI.
安装
pnpm add @aleph-alpha/ui-library
所需同伴依赖
pnpm add -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn
使用量
1. 配置UnoCSS
库导出一个帮助函数 getUiLibraryContentConfig() 以简化 UnoCSS 配置 :
// uno.config.ts
import { defineConfig } from 'unocss';
import { getUiLibraryContentConfig } from '@aleph-alpha/ui-library/config';
import presetWind from '@unocss/preset-wind4';
import presetAnimations from 'unocss-preset-animations';
import presetShadcn from 'unocss-preset-shadcn';
export default defineConfig({
...getUiLibraryContentConfig(),
presets: [
presetWind(),
presetAnimations(),
presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
],
});
自定义主题( 通过设计符号)
@aleph-alpha/ui-library 使用shadcn 风格的语义工具,例如 bg-background, (中文(简体) ), text-foreground, (中文(简体) ), bg-primary, (中文(简体) ), border-input等 (中文(简体) ).
这些解析通过CSS变量(例如. --background, (中文(简体) ), --primary) (中文(简体) ).
备选案文A:使用内置 tokens.json 与库一起装运(建议)
如果您在其中添加/保存了符号 packages/ui-library/tokens.json,可以直接装入:
// uno.config.ts
import { defineConfig } from 'unocss';
import {
getUiLibraryContentConfig,
presetUiLibraryThemeFromTokens,
} from '@aleph-alpha/ui-library/config';
import presetWind from '@unocss/preset-wind4';
import presetAnimations from 'unocss-preset-animations';
import presetShadcn from 'unocss-preset-shadcn';
export default defineConfig({
...getUiLibraryContentConfig(),
presets: [
presetWind(),
presetAnimations(),
presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
// Put the theme preset AFTER shadcn so it overrides shadcn's default CSS vars
presetUiLibraryThemeFromTokens(),
],
});
备选案文B:明确提供自己的阴影 vars
要从您符号值执行自定义主题,请添加 presetUiLibraryTheme() 之后 presetShadcn() 因此它覆盖了Shadcn默认的 CSS vars:
// uno.config.ts
import { defineConfig } from 'unocss';
import {
getUiLibraryContentConfig,
presetUiLibraryTheme,
} from '@aleph-alpha/ui-library/config';
import presetWind from '@unocss/preset-wind4';
import presetAnimations from 'unocss-preset-animations';
import presetShadcn from 'unocss-preset-shadcn';
export default defineConfig({
...getUiLibraryContentConfig(),
presets: [
presetWind(),
presetAnimations(),
presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
presetUiLibraryTheme({
light: {
// shadcn vars (keys without the leading `--`)
background: '0 0% 100%',
foreground: '240 10% 3.9%',
primary: '222.2 47.4% 11.2%',
'primary-foreground': '210 40% 98%',
border: '240 5.9% 90%',
input: '240 5.9% 90%',
ring: '240 5.9% 10%',
},
dark: {
background: '240 10% 3.9%',
foreground: '0 0% 98%',
primary: '210 40% 98%',
'primary-foreground': '222.2 47.4% 11.2%',
border: '240 3.7% 15.9%',
input: '240 3.7% 15.9%',
ring: '240 4.9% 83.9%',
},
}),
],
});
注释:
- 数值格式: 您可以通过 OKLCH 组件, 或者
hex编号 :rgb(...)编号 :hsl(...)——它们将被转换为能与阴影相容的OKLCH组件. - 暗模式选择器默认为
html.dark。如果您的应用程序使用.dark在另一个元素上,通过{ darkSelector: '.dark' }作为第二个论点.
2. 配置维特
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import UnoCSS from 'unocss/vite';
export default defineConfig({
plugins: [vue(), UnoCSS()],
});
3. 导入样式
// main.ts
import '@unocss/reset/tailwind.css';
import 'virtual:uno.css';
import { createApp } from 'vue';
import App from './App.vue';
createApp(App).mount('#app');
4. 使用组件
<script setup lang="ts">
import { UiButton, UiBadge } from '@aleph-alpha/ui-library';
</script>
<template>
<UiButton>Click me</UiButton>
<UiBadge variant="secondary">New</UiBadge>
</template>
使用@aleph- alpha/ ds- 组件- vue
已折旧的软件包 :
@aleph-alpha/ds-components-vue已贬值。 仅在迁移已有时使用此共存设置Aa*用于@aleph-alpha/ui-library; 不添加到新应用程序中.
如果你同时使用 ui-library 财务报告和审定财务报表 ds-components-vue,配置 UnoCSS 以包含两个:
重要内容: 不添加
presetWind()或者说presetAnimations()单独使用时presetsAlephAlpha()DS预设已包括这些公用事业。 从不同的包中再次添加它们会引起样式冲突.
// uno.config.ts
import { defineConfig } from 'unocss'
import { presetsAlephAlpha, getDesignSystemContentPathConfig } from '@aleph-alpha/config-unocss'
import { getUiLibraryContentConfig } from '@aleph-alpha/ui-library/config'
import presetShadcn from 'unocss-preset-shadcn'
const uiLibraryConfig = getUiLibraryContentConfig();
const dsConfig = getDesignSystemContentPathConfig('vue');
export default defineConfig({
presets: [
// DS presets (already includes presetWind + presetAnimations)
...presetsAlephAlpha(),
// UI Library preset (for shadcn CSS variables only)
presetShadcn({ color: 'neutral' }),
],
content: {
filesystem: [
...(uiLibraryConfig.content.filesystem || []),
...(dsConfig.content?.filesystem || []),
],
pipeline: {
include: [
/\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
'src/**/*.{js,ts,vue}',
'node_modules/@aleph-alpha/ui-library/**/*.js',
'node_modules/@aleph-alpha/ds-components-vue/**/*.{js,ts}',
],
},
},
});
AI 助理一体化
启用 Claude 代码或光标的组件发现 :
npx @aleph-alpha/ui-library mcp-install
光标, 添加 --cursor 旗帜。 然后重新启动您的 IDE .
可用工具 :
list_components- 浏览所有组件(按名称/类别/描述选择过滤)get_component_docs- 获取一个组件的全部文件
外部资源
- 阴影vue ——我们所依托的组成部分库
- Reka 用户界面 ——地下可通原始人
- 塔克表格 – 无头表库(被UiDataTable所使用)
- 瓦伊-阿里亚斯 ——无障碍模式指南
- 世界保护咨询小组 2.2 ——网络无障碍指南
文档
开始
节点版本
这个工程需要Node.js v22.13.0. 使用 nvm 切换到正确的版本 :
nvm use
这将自动读取 .nvmrc 在寄存器根中的文件.
发展中国家
提交信件
我们跟着 常规武器委员会 规格。 提交信件的结构必须如下:
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
类型 :
feat: 新特性fix: 错误修正docs: 仅文档更改style:不影响代码含义的更改(格式化等)refactor: 代码更改,既不修正错误,也不添加特性perf: 改进性能的代码更改test: 添加缺失的测试或更正现有测试chore: 构建过程或辅助工具的修改
实例:
git commit -m "feat(button): add loading state"
git commit -m "fix(dropdown): resolve keyboard navigation issue"
git commit -m "docs(readme): update installation instructions"
添加新组件
要从 Shadcn-vue 添加新组件,请使用以下命令:
pnpm dlx shadcn-vue@latest add [component]
示例
pnpm dlx shadcn-vue@latest add tooltip
在节点 24 运行 CLI ()nvm use 24而不是钉住的22.13.0, 否则它的依赖性
终止方式 ERR_PNPM_UNSUPPORTED_ENGINE。之后,将任何生成的重定向 @lucide/vue 或者说
lucide-vue-next 图标导入到 @/icons/lucide图书馆唯一的Lucide入口.
请参考 贡献 Guidelines.md 关于“Strict Facade”模式和无障碍要求的更详细信息.
测试
| 命令 | 目的 |
|---|---|
pnpm test | 运行单元测试 |
pnpm test:storybook | 运行自动测试( E)play 函数 + a11y)对一个建筑 |
pnpm test:storybook:local | 构建故事本, 然后运行自动测试 |
pnpm lint | 运行内嵌规则 11y |
每一部件必须同时运载两层:单元测试和自动化测试(play 包含交互、键盘、缩放、屏幕阅读器和移动功能。 见 测试战略。 。 。 .
承诺前工作流程
这个项目使用 nx affected 在承诺前的钩子中确保代码质量. 因为 lint 财务报告和审定财务报表 test 目标取决于 build,如果建筑物缓存是冷的,承诺可能会被吊死.
如果实施绞刑:
在执行前运行一个完整的构建以填充缓存 :
pnpm nx run-many --target=build --all
那就再试一次 承诺前钩会击中缓存并迅速完成.
快速解锁( 只紧急)
如果您需要绕行钩子 :
git commit -m "Your message" --no-verify
少用这个 确保CI通过.