内容
# ng-blatui
[](https://www.npmjs.com/package/ng-blatui)
[](./LICENSE)
[](https://angular.dev)
可访问的 **Angular UI 库** — [BlatUI](https://ngblatui.remix-it.com) 的视觉系统忠实移植到 Angular。构建在官方 Angular 无头栈（Angular Aria + CDK）上，使用 Tailwind CSS v4 + oklch 设计令牌进行样式设计。
**155 个组件 · 16 个区块 · 70 个图表 · 34 个页面模板** — 所有组件均独立、基于信号、 无区隔且 SSR 安全。
🔗 **[文档和实时演示 →](https://ngblatui.remix-it.com)** · 📦 **[npm](https://www.npmjs.com/package/ng-blatui)** · 🤖 **[与 AI 结合使用 →](./USING-WITH-AI.md)**
---
## 亮点
- **Angular 21 & 22** — 独立组件，**信号** (`input()`/`model()`/`output()`)，**无区隔** 变更检测，默认为 `OnPush`。
- **SSR-ready** — 每个组件都在服务器端渲染下正确渲染（文档网站预渲染 280+ 个静态路由）。
- **可访问** — 行为基于 `@angular/aria` + `@angular/cdk`；通过 AXE / WCAG AA。
- **表单原生** — 每个表单控件都实现了 `ControlValueAccessor`，因此相同的组件适用于响应式、模板驱动和信号表单。
- **可主题化** — Tailwind v4 实用工具 + CSS 变量（oklch 令牌）；开箱即支持浅色/深色主题。
- **AI-ready** — 配备 MCP 服务器、`llms.txt` 索引和机器可读注册表（见下文）。
## 安装
```bash
npm i ng-blatui
```
对等依赖（Angular **21 或 22**）：`@angular/core`、`@angular/common`、`@angular/forms`、`@angular/cdk`、`@angular/aria`。样式为 **Tailwind CSS v4** — 将 ng-blatui 令牌/预设导入到您的全局样式表和 Tailwind 配置中。完整设置：**https://ngblatui.remix-it.com/docs/installation**。
## 用法
从 `ng-blatui` 桶中导入组件类并将其添加到独立组件的 `imports[]` 中 — 无 NgModule。选择器前缀为 **`bui`**。
```ts
import { Component } from '@angular/core';
import { BuiButton, BuiBadge, BuiInput } from 'ng-blatui';
@Component({
selector: 'app-demo',
imports: [BuiButton, BuiBadge, BuiInput],
template: `
<label>
邮箱
<input buiInput type="email" placeholder="you@example.com" />
</label>
<button buiButton>保存 <span buiBadge tone="success">新增</span></button>
`,
})
export class Demo {}
```
- **元素选择器**：`<bui-avatar>`、`<bui-rating>`、…
- **属性/指令选择器**：`<button buiButton>`、`<input buiInput>`、`<span buiBadge tone="success">`、…
- **信号**：绑定 `[checked]` / `(checkedChange)` 等；在无区隔 CD 和 SSR 下工作，无需额外设置。
- **表单**：`formControlName`、`[(ngModel)]` 或 `[formControl]` 均可使用 — 每个控件都是 `ControlValueAccessor`。
## 主题化
样式为 Tailwind v4 + CSS 变量。覆盖 oklch 设计令牌（`--background`、`--foreground`、`--primary`、`--border`、`--muted`、`--radius`、…）以全局重新样式化；切换 `dark` 类以启用深色主题。参见 **https://ngblatui.remix-it.com/docs/theming**。
## 内容
| 类别 | 数量 | 浏览 |
| ---------- | ----- | ---------------------------------------- |
| **组件** | 155 | https://ngblatui.remix-it.com/components |
| **区块** | 16 | https://ngblatui.remix-it.com/blocks |
| **图表** | 70 | https://ngblatui.remix-it.com/charts |
| **模板** | 34 | https://ngblatui.remix-it.com/templates |
模板是完整的、生产风格的页面（仪表盘、定价、身份验证、商店、CRM、博客、文档、电子商务产品，以及 20 个艺术指导的着陆页）— 忠实地 1:1 复制 BlatUI 原件。
## 与 AI 代理结合使用
ng-blatui 构建为可被 AI 编码助手消耗，以便它们正确发现和使用目录 — 通过三层：
| 层 | 内容 | 位置 |
| -------------- | ----------------------------------------------------------- | ------------------------------------------- |
| **MCP 服务器** | 用于列出/搜索目录和获取完整文档 + 代码的工具 | `npx ng-blatui-mcp` |
| **llms.txt** | [llms.txt](https://llmstxt.org) 标准索引 | https://ngblatui.remix-it.com/llms.txt |
| **registry.json** | 机器可读目录 | https://ngblatui.remix-it.com/registry.json |
快速入门（适用于 Claude、Cursor、Windsurf、Cline、Zed、VS Code…）：
```bash
claude mcp add ng-blatui -- npx -y ng-blatui-mcp
# 或添加到任何 MCP 客户端：
# { "mcpServers": { "ng-blatui": { "command": "npx", "args": ["-y", "ng-blatui-mcp"] } } }
```
MCP 服务器公开 `list_components`（可选 `category`）、`list_blocks`、`list_charts`、`list_templates`、`search({ query })` 和 `get_docs({ name })`。完整指南，包括每个客户端的配置和复制粘贴编辑器规则：**[USING-WITH-AI.md](./USING-WITH-AI.md)**。
---
## 开发
这是一个 Angular 工作区，包含两个项目：库 (`projects/ng-blatui`) 和文档/演示应用 (`projects/demo`)。
```bash
git clone https://github.com/anousss007/ng-blatui.git
cd ng-blatui
npm install
npm start # 在 http://localhost:4200 上提供演示应用
```
### 脚本
| 命令 | 执行的操作 |
| -------------------------- | -------------------------------------------------------- |
| `npm start` | 提供演示应用 (`ng serve demo`) |
| `npm run build:lib` | 构建可发布的库 (`ng build ng-blatui`) |
| `npm run build` | 构建演示网站 |
| `npm test` | 单元测试（Vitest） |
| `npm run lint` | ESLint（类型感知，严格）+ 模板 a11y |
| `npm run format` | Prettier（带有 Tailwind 类排序） |
| `npm run build:registry` | 从目录中重新生成 `registry.json` + `llms.txt` |
| `npm run capture:previews` | 捕获模板预览图像（Playwright） |
| `npm run deploy:site` | 构建 + 部署文档网站到 VPS |
### 项目结构
```
projects/
ng-blatui/ # 已发布的库（src/lib/* = 157 个组件目录，public-api.ts）
demo/ # 文档 + 实时演示网站（组件/区块/图表/模板画廊）
src/app/pages/templates/ # 34 个页面模板
public/ # 静态资产，包括生成的 llms.txt + registry.json
scripts/
build-registry.mjs # 生成 registry.json + llms.txt + mcp/registry.json
capture-previews.mjs # 模板预览截图
deploy-site.sh # 构建 + rsync 到 VPS
mcp/ # ng-blatui-mcp MCP 服务器包（单独发布）
.claude/skills/ # angular-best-practices（贡献）+ ng-blatui（消耗）
AGENTS.md # AI 代理在该仓库中工作的指南
USING-WITH-AI.md # 使用 AI 代理消耗 ng-blatui 的指南
```
### 约定
Angular **v22**，无区隔，独立（默认值 — 永远不会显式设置）。到处都是信号；原生控制流（`@if`/`@for`/`@switch`）；无 `*ngIf`/`ngClass`。库选择器前缀 `bui`，演示前缀 `app`。参见 **[AGENTS.md](./AGENTS.md)** 和 **[CONTRIBUTING.md](./CONTRIBUTING.md)** 以获取完整规则集。
## 发布
- **库** (`ng-blatui`) — **发布** GitHub Actions 工作流（手动调度）运行 `semantic-release`：它分析 Conventional Commits，调整版本，添加标签，创建 GitHub 发布并使用 provenance 发布到 npm。
- **MCP 服务器** (`ng-blatui-mcp`) — 调整 `mcp/package.json`，然后运行 **发布 MCP** 工作流（手动调度）以发布它。
## 致谢
[**BlatUI**](https://ngblatui.remix-it.com) 的 Angular 端口（Blade/Laravel + Tailwind 组件系统）。行为基于 Angular Aria + CDK。
## 许可证
[MIT](./LICENSE)
连接信息
猜你喜欢
暂无推荐服务器