安装

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

安装组件包

安装包

npm

npm install @a3s-lab/ui@0.4.0

pnpm

pnpm add @a3s-lab/ui@0.4.0

bun

bun add @a3s-lab/ui@0.4.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/app-shell";
import "@a3s-lab/ui/tabs";
import "@a3s-lab/ui/split-pane";
import "@a3s-lab/ui/task-workspace";

使用语义标记

<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.css`	A3S 视觉基础；与 `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/app-shell`	桌面导航与有边界的紧凑抽屉
`@a3s-lab/ui/bulk-action-bar`	已选范围、异步操作与完成反馈
`@a3s-lab/ui/code-editor`	原生代码编辑器回退
`@a3s-lab/ui/combobox`	组合框
`@a3s-lab/ui/command`	命令面板
`@a3s-lab/ui/context-menu`	右键与键盘上下文菜单
`@a3s-lab/ui/data-grid`	数据排序与选择状态
`@a3s-lab/ui/device-simulator`	响应式 iframe 与原生设备预览桥接
`@a3s-lab/ui/drawer`	抽屉
`@a3s-lab/ui/dropdown-menu`	下拉菜单
`@a3s-lab/ui/filter-bar`	分段筛选与当前条件
`@a3s-lab/ui/file-explorer`	文件选择、筛选、命令与内联重命名
`@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/task-workspace`	响应式任务检查器与焦点归还
`@a3s-lab/ui/toast`	Toast
`@a3s-lab/ui/chart`	Chart 辅助 API；Chart.js 仍需单独安装

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

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

Dockview 布局集成

需要可停靠工作区时，安装 Dockview 8.1 的 MIT 包与宿主框架适配器。该集成独立于 116 个语义组件，不会进入默认 CSS 或 JavaScript 运行时。

npm install @a3s-lab/ui@0.4.0 dockview@8.1.0
npm install dockview-react@8.1.0 react react-dom # React
npm install dockview-vue@8.1.0 vue             # Vue

导入	内容
`@a3s-lab/ui/dockview`	原生 Dockview、Gridview、Splitview、Paneview API，A3S 主题与布局持久化
`@a3s-lab/ui/dockview/react`	完整 React API、`useDockviewLayout`、`useGridview`、`useSplitview`、`usePaneview`
`@a3s-lab/ui/dockview/vue`	完整 Vue 3 API与对应 composable
`@a3s-lab/ui/dockview/css`	Dockview 基础样式与 A3S 明暗主题变量

完整能力和许可边界见 Dock 工作区。

服务器渲染模板

可选的 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

宏参数请参阅模板。

语义与框架适配器

包中还包含机器可读组件清单、小型 DOM 标注运行时，以及可选的 React 与 Vue 元素适配器。这些入口保持同一套语义 HTML 契约，不包含应用状态、任务传输或产品逻辑。

import { a3sAI } from "@a3s-lab/ui/ai";
import manifest from "@a3s-lab/ui/components.json" with { type: "json" };

a3sAI.scan(document);
console.log(manifest.components.length); // 116

React 与 Vue 均为可选 peer dependency。宿主应用只需安装正在使用的框架，然后从 @a3s-lab/ui/react 或 @a3s-lab/ui/vue 导入组件。

原生 HTML、React、Vue、组件清单、选择器、快照与确定性测试示例见集成。

图标

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

#安装

#安装组件包

安装包

导入 Tailwind 和 A3S UI

加载交互组件

使用语义标记

#CSS 导入

#拆分导入

#JavaScript 导入

#Dockview 布局集成

#服务器渲染模板

#语义与框架适配器

#图标

安装