spartan-ng-developer

Spartan/ng 开发指南

与 angular-developer 配合使用——该技能提供 Angular 基础知识（signals、DI、路由、表单、SSR、无障碍）。本技能侧重 Spartan/ng 特有内容。建议同时安装两者，以获得最佳体验。

兼容性

• 跟踪版本： @spartan-ng/brain v1.8.0（于 2026-10-16 发布）。Spartan 于 2026 年 6 月达到 1.0 稳定版；1.x 系列会快速添加组件，同时为 API 表面进行版本管理，并在每次升级时重新验证。
• 1.1 → 1.8 亮点： 1.1 为 Calendar / Date Picker 添加了年月选择器和完整的日期输入支持，为 brn-radio / brn-checkbox / brn-switch 添加了宿主样式覆盖，新增 CLI 脚手架完整性健康检查，并修复严格 CSP 下的内联样式问题。1.2 添加了新的消息、气泡、附件和标记组件，并使 Date Picker 和 Input OTP 兼容 Signal Forms。1.3 / 1.3.1 修复了 autocomplete / combobox / command 的无障碍问题，并为 Sidebar 添加了 defaultOpen 选项。1.4 添加了 Questionnaire（Brain + Helm，支持 Signal Forms）、Chart 的 TanStack Charts 集成（alpha）、Slider 的 maxStepsBetweenThumbs / preventStepOverThumb，以及 Calendar 的焦点日期 API。1.5 添加了用于聊天记录的 Message Scroller，将 brn-switch-thumb 添加为指令并为 Switch 添加 forceInvalid，为 Sonner 添加模板 action / cancelAction，并将 Tooltip 默认的 showDelay / hideDelay 设为 0。1.6 为 Accordion 添加了延迟加载内容（hlmAccordionContentLazy）。1.7 添加了可配置的 Pagination 标签。1.8 添加了 Trace 和 Code Block 组件、指令上的 exportAs，以及可通过 CLI 非交互式地添加所有组件的命令（ui all）。各个补丁版本还修复了无障碍问题（select、autocomplete、combobox、dialog、sidebar sheet）以及 popover / overlay 滚动策略问题。整个 1.x 系列没有破坏性 API 变更。
• Angular： v21 或 v22。@spartan-ng/[email protected] 的 peer 依赖要求 @angular/* >=21.0.0 <23.0.0，因此 Angular 21 和 22 均为官方支持版本。默认使用独立组件、控制流（@if / @for）和信号 API（input() / output()）；不会生成基于 NgModule 或装饰器的代码。
• Tailwind： 必须使用 v4。 Spartan 1.x 的 peer 依赖要求 tailwindcss >=4.0.0，不再支持 v3。它还会引入 peer 依赖 luxon >=3.0.0（日期基础类型）、clsx >=2.0.0 和 tw-animate-css >=1.0.0，请确保已安装这些依赖。参见 setup.md。
• 不支持： 旧版 alpha（v0.0.1-alpha.*），其 API 与 1.0 之前的版本存在差异；Angular v20 或更低版本；Tailwind v3；使用 @spartan-ng/ui-* 软件包的项目（这些软件包已弃用，现由 @spartan-ng/helm 取代）。

如果项目已安装的版本与跟踪版本差异显著，请在生成代码前提醒用户；API 表面可能已经发生变化。

1. 在提供指导前，始终检查项目的 Spartan/ng 版本。Spartan 现已达到 1.0 稳定版，但仍在持续演进；package.json 是权威依据。

2. 尽早检测项目布局：

   • 如果存在 nx.json → Nx 工作区。使用 npx nx g @spartan-ng/cli:ui <name> 命令。
   • 否则 → Angular CLI。使用 ng g @spartan-ng/cli:ui <name> 命令。

   生成的 Helm 源代码目标路径由 components.json 中的 componentsPath 配置——不要假定路径固定。运行 init 后，在 tsconfig.json 的 paths 中查找实际位置。参见 setup.md。

3. 确认项目使用 Tailwind v4（检查 package.json 中的 tailwindcss 依赖）。Spartan 1.x 要求 Tailwind v4（peer 依赖 >=4.0.0）；不再支持 v3。还要确保存在 luxon、clsx 和 tw-animate-css 这些 peer 依赖。参见 setup.md。

4. 生成使用 Spartan 组件的代码后，运行 ng build，确认没有编译错误。如果组件渲染后没有样式，问题几乎总是出在 Tailwind 配置上——请参见 setup.md 的故障排除部分。

Spartan 架构：Helm 与 Brain（重要）

Spartan 提供两个关系独特的软件包：

• @spartan-ng/helm - 样式化组件，位于用户的项目中，而非 node_modules 中。CLI（ng g @spartan-ng/cli:ui button）会将组件源代码复制到 components.json（componentsPath）配置的路径中。@spartan-ng/helm/<name> 导入是指向生成源代码的 tsconfig 路径别名。要自定义 Helm 组件，请编辑用户代码库中的文件。不要在 node_modules 中查找。

• @spartan-ng/brain - 无头、易访问的原语，通过 npm 正常安装。Helm 组件通过 Angular 的 hostDirectives 组合 Brain 原语。

默认使用 Helm。 仅在以下情况下使用 Brain：（1）Helm 未提供所需原语；（2）你正在构建封装多个 Helm 组件的可复用组合；或（3）你需要控制 Helm 隐藏的易访问性属性。

安装与主题设置

• 设置：安装 CLI、添加 Spartan、配置 Tailwind v4（必需，并需安装 luxon / clsx / tw-animate-css 对等依赖），以及 CLI 与 Nx 检测。阅读 setup.md
• 主题设置：CSS 变量、深色模式、自定义主题。阅读 theming.md

组件

Spartan/ng 提供 66 个稳定的 Helm 组件，按类别分组如下。通用约定文件适用于所有组件；类别文件则介绍特定组件的 API 和注意事项。

• Helm 约定：hlm* 指令模式、信号输入、通过 hostDirectives 组合、cn() 助手、HlmXImports 汇总导出模式、常见陷阱。阅读 helm-conventions.md
• 表单控件：自动补全、按钮、按钮组、复选框、组合框、日期选择器、字段、输入框、输入框组、一次性密码输入框、标签、原生选择框、单选按钮组、选择框、滑块、开关、文本区域、切换按钮、切换按钮组。阅读 form-controls.md
• 覆盖层：警告对话框、命令、上下文菜单、对话框、抽屉、下拉菜单、悬停卡片、菜单栏、导航菜单、弹出框、面板、Sonner（Toast）、工具提示。阅读 overlays.md
• 布局：手风琴、宽高比、卡片、可折叠面板、可调整大小面板、滚动区域、分隔线、侧边栏、标签页。阅读 layout.md
• 展示：警告、头像、徽章、空状态、图标、项目、键盘按键、进度条、骨架屏、加载指示器。阅读 display.md
• 数据展示：面包屑、日历、轮播、图表、数据表格、分页、表格。阅读 data-display.md
• 聊天与 Agent 界面：消息、气泡、附件、标记、消息滚动器、跟踪、代码块、问卷。阅读 chat.md

配方

将多个 Helm 组件组合成特定用途界面的实用模式。这些都不是随 Helm 一同提供的组件，配方本身才是贡献内容。如果你正在构建代码审查工具，可从差异查看器（语法高亮、逐行边栏、文件树、行内注释）开始。阅读 recipes.md

Brain 原语

• Brain：无头原语、何时从 Helm 切换到 Brain、如何构建自定义组合。阅读 brain.md

表单集成

• 表单：将 Helm 表单组件连接到 ReactiveForms 或 Signal Forms、ControlValueAccessor 模式、验证结果显示。阅读 forms.md

易访问性

• 易访问性：Helm 和 Brain 开箱即用的无障碍约定、需要了解的 ARIA 模式及注意事项。阅读 accessibility.md