For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/installation.md.
A3S UI
  • 简体中文
  • next

      • 安装

      A3S UI 已发布到 npm。稳定版本应直接从 registry 安装；仅在验证尚未发布的源码变更时使用 GitHub 安装。

      安装组件包

      安装包

      npm
      npm install @a3s-lab/ui@0.2.0
      pnpm
      pnpm add @a3s-lab/ui@0.2.0
      bun
      bun add @a3s-lab/ui@0.2.0

      导入 Tailwind 和 A3S UI

      @import "tailwindcss";
@import "@a3s-lab/ui";

      默认导出包含基础设计令牌、所有组件与 A3S 视觉风格。请在 Tailwind 之后加载，避免后续 Preflight 重置组件边界或控件样式。

      加载交互组件

      大多数组件只需要 CSS。当应用使用菜单、Select、Tabs、Split Pane 或其他交互式复合组件时，再导入完整运行时。

      import "@a3s-lab/ui/all";

      也可以只导入基础运行时与实际使用的控制器。

      import "@a3s-lab/ui/runtime";
import "@a3s-lab/ui/tabs";
import "@a3s-lab/ui/split-pane";

      使用语义标记

      <header class="workspace-header">
  <div data-workspace-identity>
    <h1>Production gateway</h1>
    <span>Configuration saved</span>
  </div>
  <div data-workspace-actions>
    <button type="button" class="btn">Deploy</button>
  </div>
</header>

      CSS 导入

      导入内容
      @a3s-lab/ui默认的完整 A3S 样式包
      @a3s-lab/ui/a3s显式指定的完整 A3S 样式包
      @a3s-lab/ui/{style}完整的 vega、nova、maia、lyra、mira、luma、sera 或 rhea 样式包
      @a3s-lab/ui/base基础令牌、语义工具类与组件结构，不包含视觉风格
      @a3s-lab/ui/components所有组件结构，不包含基础令牌与视觉风格
      @a3s-lab/ui/components/button.css单个组件的结构样式
      @a3s-lab/ui/styles/a3s.cssA3S 视觉基础；与 base 组合使用
      @a3s-lab/ui/compat可选的旧版本兼容别名

      拆分导入

      当应用 CSS 已经自行管理依赖关系时，可使用拆分导入。

      @import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/button.css";
@import "@a3s-lab/ui/components/app-shell.css";
@import "@a3s-lab/ui/styles/a3s.css";

      JavaScript 导入

      导入控制器
      @a3s-lab/ui/all运行时和所有自动初始化控制器（图表除外）
      @a3s-lab/ui/runtime共享生命周期与组件注册机制
      @a3s-lab/ui/accordion折叠面板增强
      @a3s-lab/ui/combobox组合框
      @a3s-lab/ui/command命令面板
      @a3s-lab/ui/drawer抽屉
      @a3s-lab/ui/dropdown-menu下拉菜单
      @a3s-lab/ui/popover弹出窗口
      @a3s-lab/ui/range范围输入视觉状态
      @a3s-lab/ui/select选择
      @a3s-lab/ui/sidebar侧边栏
      @a3s-lab/ui/split-pane可调整大小的分割窗格
      @a3s-lab/ui/tabs选项卡和功能区导航
      @a3s-lab/ui/toastToast
      @a3s-lab/ui/chartChart 辅助 API；Chart.js 仍需单独安装

      公共运行时命名空间为 window.a3sUI。它会在页面加载时初始化已注册组件，并观察后续插入的 DOM。

      window.a3sUI.initAll();
window.a3sUI.initAll({ force: true });
window.a3sUI.refresh(document.querySelector(".split-pane"));

      服务器渲染模板

      可选的 Nunjucks 和 Jinja 模板随软件包一起提供。

      Nunjucks
      cp -R node_modules/@a3s-lab/ui/templates/nunjucks ./templates/a3s-ui
      Jinja
      cp -R node_modules/@a3s-lab/ui/templates/jinja ./templates/a3s-ui

      宏参数请参阅模板。

      图标

      A3S UI 不捆绑图标。文档示例使用内联、兼容 Lucide 的 SVG，应用可以替换为任意图标系统。只有图标而没有文字的控件必须提供可访问名称。