# @aleph-alpha/ui-library 中文文档

规范地址：https://npmcn.com/package/%40aleph-alpha/ui-library/

版本：7\.0\.2
npm 元数据更新时间：2026-10-29T15:58:23.895Z
中文译文更新时间：2026-11-05T21:34:28.258Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aleph-alpha/ui-library
原文对照：https://npmcn.com/package/%40aleph-alpha/ui-library/?lang=original
项目主页：https://docs.aleph-alpha.com/

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

- 包体积（解压后）：16.3 MB，4334 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：15 个
- peer 依赖：unocss \>=66\.0\.0，@unocss/preset-wind4 \>=66\.0\.0，unocss-preset-shadcn \>=1\.0\.0，unocss-preset-animations \>=1\.0\.0
- 首次发布：2025-12-18T13:47:46.145Z
- 最新版本发布：2026-10-29T15:58:10.487Z
- 近 30 天下载量：17246（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 84 个）

## 中文简介

Vue.js 工程的下源 UI 库.

## 安装

```sh
npm install @aleph-alpha/ui-library
```

也可以使用：`pnpm add @aleph-alpha/ui-library`、`yarn add @aleph-alpha/ui-library`、`bun add @aleph-alpha/ui-library`

## README

# UI 图书馆

📘 **[查看故事书](https://dev.aleph-alpha.de/ui-library)**

调用触摸到的 ii-library 运行 受影响的故事本构建和测试检查 在CI.

## 安装

```bash
pnpm add @aleph-alpha/ui-library
```

### 所需同伴依赖

```bash
pnpm add -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn
```

## 使用量

### 1\. 配置UnoCSS

库导出一个帮助函数 `getUiLibraryContentConfig()` 以简化 UnoCSS 配置 :

```typescript
// 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`,可以直接装入:

```typescript
// 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:

```typescript
// 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\. 配置维特

```typescript
// 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\. 导入样式

```typescript
// 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\. 使用组件

```vue
<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预设已包括这些公用事业。 从不同的包中再次添加它们会引起样式冲突.

```typescript
// 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 代码或光标的组件发现 :

```bash
npx @aleph-alpha/ui-library mcp-install
```

光标, 添加 `--cursor` 旗帜。 然后重新启动您的 IDE .

**可用工具 :**

-   `list_components` - 浏览所有组件(按名称/类别/描述选择过滤)
-   `get_component_docs` - 获取一个组件的全部文件

## 外部资源

-   [阴影vue](https://www.shadcn-vue.com/) ——我们所依托的组成部分库
-   [Reka 用户界面](https://reka-ui.com/) ——地下可通原始人
-   [塔克表格](https://tanstack.com/table/latest) – 无头表库(被UiDataTable所使用)
-   [瓦伊-阿里亚斯](https://www.w3.org/WAI/ARIA/apg/) ——无障碍模式指南
-   [世界保护咨询小组 2.2](https://www.w3.org/TR/WCAG22/) ——网络无障碍指南

## 文档

-   [建筑](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/ARCHITECTURE.md) - 构成部分结构和设计决定
-   [贡献准则](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/CONTRIBUTION_GUIDELINES.md) - 无障碍要求和模式
-   [故事书指南](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/STORYBOOK.md) - 故事模式和准则
-   [测试战略](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/TESTING.md) - 我们测试的东西,包括自动化测试,每个部件必须运送到哪里

## 开始

### 节点版本

这个工程需要Node.js v22.13.0. 使用 `nvm` 切换到正确的版本 :

```bash
nvm use
```

这将自动读取 `.nvmrc` 在寄存器根中的文件.

## 发展中国家

### 提交信件

我们跟着 [常规武器委员会](https://www.conventionalcommits.org/) 规格。 提交信件的结构必须如下:

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

**类型 :**

-   `feat`: 新特性
-   `fix`: 错误修正
-   `docs`: 仅文档更改
-   `style`:不影响代码含义的更改(格式化等)
-   `refactor`: 代码更改,既不修正错误,也不添加特性
-   `perf`: 改进性能的代码更改
-   `test`: 添加缺失的测试或更正现有测试
-   `chore`: 构建过程或辅助工具的修改

**实例:**

```bash
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 添加新组件,请使用以下命令:

```bash
pnpm dlx shadcn-vue@latest add [component]
```

示例

```bash
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](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/CONTRIBUTION_GUIDELINES.md) 关于“Strict Facade”模式和无障碍要求的更详细信息.

## 测试

| 命令 | 目的 |
| --- | --- |
| `pnpm test` | 运行单元测试 |
| `pnpm test:storybook` | 运行自动测试( E)`play` 函数 + a11y)对一个建筑 |
| `pnpm test:storybook:local` | 构建故事本, 然后运行自动测试 |
| `pnpm lint` | 运行内嵌规则 11y |

每一部件必须同时运载两层:单元测试和自动化测试(`play` 包含交互、键盘、缩放、屏幕阅读器和移动功能。 见 [测试战略](https://npmcn.com/package/%40aleph-alpha/ui-library/docs/TESTING.md#required-coverage--all-five-categories-every-component)。 。 。 .

## 承诺前工作流程

这个项目使用 `nx affected` 在承诺前的钩子中确保代码质量. 因为 `lint` 财务报告和审定财务报表 `test` 目标取决于 `build`,如果建筑物缓存是冷的,承诺可能会被吊死.

### 如果实施绞刑:

在执行前运行一个完整的构建以填充缓存 :

```bash
pnpm nx run-many --target=build --all
```

那就再试一次 承诺前钩会击中缓存并迅速完成.

### 快速解锁( 只紧急)

如果您需要绕行钩子 :

```sh
git commit -m "Your message" --no-verify
```

少用这个 确保CI通过.

## 常见问题

### @aleph-alpha/ui-library 是什么？

Vue\.js 工程的下源 UI 库\.

### 如何安装 @aleph-alpha/ui-library？

在项目目录运行 npm install @aleph-alpha/ui-library，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unocss（\>=66\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aleph-alpha/ui-library 支持 TypeScript 吗？

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

### @aleph-alpha/ui-library 支持 ESM 还是 CommonJS？

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

### @aleph-alpha/ui-library 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aleph-alpha/ui-library 可以商用吗？

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

### @aleph-alpha/ui-library 的下载量有多少？

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

### @aleph-alpha/ui-library 还在维护吗？

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