ng-blatui

ng-blatui

易于访问的 Angular UI 库 — 将 BlatUI 的视觉系统忠实移植到 Angular。基于官方 Angular 无头组件栈（Angular Aria + CDK），使用 Tailwind CSS v4 和 oklch 设计令牌进行样式设计。

157 个组件 · 16 个区块 · 70 个图表 · 35 个页面模板 — 全部为独立组件、基于信号、无 Zone 且兼容 SSR。

🔗 文档和在线演示 → · 📦 npm · 🤖 与 AI 搭配使用 →

---

亮点

• Angular 21 和 22 — 独立组件、信号（input()/model()/output()）、无 Zone 变更检测，默认使用 OnPush。
• 支持 SSR — 每个组件在服务器端渲染下都能正确呈现（文档站点预渲染了 280 多个静态路由）。
• 易于访问 — 基于 @angular/aria + @angular/cdk 构建交互行为；通过 AXE / WCAG AA 检测。
• 原生支持表单 — 每个表单控件都实现了 ControlValueAccessor，因此同一个组件可用于响应式表单、模板驱动表单和信号表单。
• 支持主题 — Tailwind v4 工具类 + CSS 变量（oklch 令牌）；开箱即用地支持浅色和深色主题。
• 为 AI 做好准备 — 内置 MCP 服务、llms.txt 索引和机器可读注册表（见下文）。

安装

npm i ng-blatui

Peer 依赖（Angular 21 或 22）：@angular/core、@angular/common、@angular/forms、@angular/cdk、@angular/aria。

Tailwind CSS 配置

样式使用 Tailwind CSS v4。在应用的全局样式表（例如 src/styles.css）中添加三行：

@import 'tailwindcss';
@import 'ng-blatui/foundations/blatui.css'; /* design tokens + dark theme */
@source '../node_modules/ng-blatui'; /* ← generate the utilities the lib's classes use */

@source 这一行最容易被遗漏：没有它，Tailwind 就不会扫描 ng-blatui 编译后的模板，因此组件会以无样式状态呈现。将其指向 ng-blatui 相对于样式表所在的位置（调整 ../ 的层级）。深色模式通过父元素上的 dark 类启用（<html class="dark">）；可在 :root / .dark 中覆盖任意 oklch 令牌以更换主题。完整指南： **https://ngblatui.remix-it.com/docs/installation**。

图标

ng-blatui 不附带图标集 — 请接入自己的图标集（例如 @ng-icons），并使用 provideIcons(...) 注册用到的每个图标。需要图标的组件接受 SVG 路径 d 字符串，因此可使用任何图标来源。

使用方法

从 ng-blatui 汇总导出中导入组件类，并将其添加到独立组件的 imports[] 中 — 无需 NgModule。选择器均以 bui 为前缀。

import { Component } from '@angular/core';
import { BuiButton, BuiBadge, BuiInput } from 'ng-blatui';

@Component({
  selector: 'app-demo',
  imports: [BuiButton, BuiBadge, BuiInput],
  template: `
    <label>
      Email
      <input buiInput type="email" placeholder="[email protected]" />
    </label>
    <button buiButton>Save <span buiBadge tone="success">New</span></button>
  `,
})
export class Demo {}

• 元素选择器：<bui-avatar>、<bui-rating>、…
• 属性／指令选择器：<button buiButton>、<input buiInput>、<span buiBadge tone="success">、…
• 信号：绑定 [checked] / (checkedChange) 等；无需额外配置即可在无 Zone 的变更检测和 SSR 下使用。
• 表单：formControlName、[(ngModel)] 或 [formControl] 均可使用 — 每个控件都是 ControlValueAccessor。

表单字段：两个层级

• 内置齐全功能的组件会为你连接标签、提示、错误信息和 ARIA：BuiInputField、 BuiMoneyInput（本地化货币；symbol="DH" 可覆盖 ISO 代码）、BuiDateRangePicker （带预设选项的开始日期→结束日期），以及 BuiSelect、BuiCombobox、BuiAutocomplete、BuiPhoneInput。
• 组合式基础组件可用于自定义布局：buiField + buiFieldLabel / buiFieldDescription / buiFieldError 包裹基础 buiInput / .blat-* 控件，并管理无障碍关联关系。

只有在你也自行添加 buiField 结构时，才使用基础控件（buiInput）。 其他容易遗漏的构建组件：buiEmpty（空状态）、bui-stat（统计卡片）、 buiFieldSet / buiFieldLegend（分组字段）。

主题

样式使用 Tailwind v4 + CSS 变量。覆盖 oklch 设计令牌（--background、--foreground、--primary、--border、--muted、--radius，等等），即可全局重设样式；添加 dark 类即可切换到深色模式。请参阅 **https://ngblatui.remix-it.com/docs/theming**。

本地化

两个提供程序即可覆盖整个库，只需在应用配置中各设置一次：

import { provideBuiLabels, provideBuiLocale } from 'ng-blatui';

providers: [
  provideBuiLocale('fr-BE'), // dates, times, numbers, week start, weekend, week numbering
  provideBuiLabels({ fileUploadRemove: 'Supprimer le fichier' }), // built-in strings
];

两者都不设置时，所有内容都会按 en-US 格式化——这是 Angular 自带的 LOCALE_ID 默认值，也是日期选择器在非美国应用中仍显示美国格式的常见原因。解析顺序从最具体的设置开始：组件的 [locale] 输入 → provideBuiLocale() → 应用的 LOCALE_ID → en-US。这里无需调用 registerLocaleData()；ng-blatui 通过 Intl 格式化。

两个提供程序也都接受 signal，或在注入上下文中运行的工厂函数——因此它们可以与任何翻译库（Transloco、ngx-translate、自定义 signal store）搭配使用，而 ng-blatui 无需依赖这些库，也无需了解任何翻译格式。完整指南（含 Transloco 示例）：**https://ngblatui.remix-it.com/docs/localization**。

包含内容

类别	数量	浏览
组件	157	https://ngblatui.remix-it.com/components
区块	16	https://ngblatui.remix-it.com/blocks
图表	70	https://ngblatui.remix-it.com/charts
模板	35	https://ngblatui.remix-it.com/templates

模板是完整的生产风格页面（仪表板、定价、身份验证、商店、CRM、博客、文档、电商产品，以及 20 个经过艺术指导的落地页），均忠实 1:1 复刻自 BlatUI 原版。

与 AI Agent 搭配使用

ng-blatui 专为 AI 编码助手而构建，让它们能够正确发现并使用目录，而非靠猜测——这通过三个层面实现：

层面	内容	位置
MCP 服务	用于列出／搜索目录及获取完整文档和代码的工具	npx ng-blatui-mcp
llms.txt	llms.txt 标准索引	https://ngblatui.remix-it.com/llms.txt
registry.json	机器可读目录	https://ngblatui.remix-it.com/registry.json

快速开始（适用于 Claude、Cursor、Windsurf、Cline、Zed、VS Code 等）：

claude mcp add ng-blatui -- npx -y ng-blatui-mcp
# or add to any MCP client:
# { "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。

---

开发

这是一个包含两个项目的 Angular 工作区：库（projects/ng-blatui）和文档／演示应用（projects/demo）。

git clone https://github.com/anousss007/ng-blatui.git
cd ng-blatui
npm install
npm start          # serve the docs/demo app at 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（类型感知、严格模式）+ 模板无障碍检查
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/        # the published library (src/lib/* = 157 component dirs, public-api.ts)
  demo/             # docs + live demo site (components/blocks/charts/templates galleries)
    src/app/pages/templates/   # the 35 page templates
    public/         # static assets incl. generated llms.txt + registry.json
scripts/
  build-registry.mjs   # generates registry.json + llms.txt + mcp/registry.json
  capture-previews.mjs # template preview screenshots
  deploy-site.sh       # build + rsync to VPS
mcp/                # the ng-blatui-mcp MCP server package (published separately)
.claude/skills/     # angular-best-practices (contributing) + ng-blatui (consuming)
AGENTS.md           # guide for AI agents working IN this repo
USING-WITH-AI.md    # guide for consuming ng-blatui WITH an AI agent

约定

Angular v22，无 Zone，独立模式（默认设置——切勿显式设置）。全面使用 Signals；使用原生控制流（@if/@for/@switch）；不使用 *ngIf/ngClass。库的选择器前缀为 bui，演示应用的前缀为 app。完整规则请参阅 AGENTS.md 和 CONTRIBUTING.md。

发布

• 库（ng-blatui）——GitHub Actions 的 Release 工作流（手动触发）会运行 semantic-release：分析 Conventional Commits、更新版本号、创建标签和 GitHub 发布版本，并通过 provenance 发布到 npm。
• MCP 服务（ng-blatui-mcp）——更新 mcp/package.json 中的版本号，然后手动触发 Release MCP 工作流进行发布。

致谢

BlatUI（Blade/Laravel + Tailwind 组件系统）的 Angular 移植版。基于 Angular Aria + CDK 实现行为。

许可证

MIT