# @adia-ai/web-components 中文文档

规范地址：https://npmcn.com/package/%40adia-ai/web-components/

版本：0\.8\.66
npm 元数据更新时间：2026-09-14T17:24:19.332Z
中文译文更新时间：2026-11-06T14:11:27.041Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adia-ai/web-components
原文对照：https://npmcn.com/package/%40adia-ai/web-components/?lang=original
项目主页：https://github.com/adiahealth/gen-ui-kit#readme
源码仓库：https://github.com/adiahealth/gen-ui-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：21.6 MB，1470 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：13 个
- 首次发布：2026-04-21T05:27:57.611Z
- 最新版本发布：2026-09-14T17:24:19.142Z
- 近 30 天下载量：3031（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：220（近 12 个月 220 个）

## 中文简介

AdiaUI网络组件——香草自定义元素. A2UI 运行时间( 发送、 注册、 流、 接线) 生活在 @adia- ai/ a2ui .

## 安装

```sh
npm install @adia-ai/web-components
```

也可以使用：`pnpm add @adia-ai/web-components`、`yarn add @adia-ai/web-components`、`bun add @adia-ai/web-components`

## README

# @adia-ai/web-组件

AdiaUI的香草网络组件. **~130 光度- DOM 自定义元素** (单位:千美元)`ls components | wc -l` 是人口普查)+ **56个可变特性**,反应核(信号+标记-模板渲染器),形式相联的形式控制,并被集成到A2UI生成管.

> 这个包裹只运送UI原子. 复合贝壳(admin / chall / 编辑器 / 简单 / 主题) 活在 [`@adia-ai/web-modules`](https://npmcn.com/package/%40adia-ai/web-modules)A2UI 协议运行时间 [`@adia-ai/a2ui`](https://npmcn.com/package/%40adia-ai/gen-ui/a2ui); 生成管道+图案体 [`@adia-ai/gen-ui`](https://npmcn.com/package/%40adia-ai/gen-ui/engine); MCP 服务器在 [`@adia-ai/mcp`](https://npmcn.com/package/%40adia-ai/gen-ui/mcp) (数量) `gen-ui` (原始内容存档于2018-10-21). space.
> 
> **消费者指南:** [`USAGE.md`](https://npmcn.com/package/%40adia-ai/web-components/USAGE.md) ——财产反应,事件合同,形式参与,生命周期,注册,TypeScript. 如果你把AdiaUI 整合到一个应用程序里 就从这里开始.
> 
> **现场演示** 用于每个组件 [`https://ui-kit.exe.xyz/site/components/<name>`](https://ui-kit.exe.xyz/site/) —— 说 `<name>` 标记没有 `-ui` 后缀(例如:. [`button`](https://ui-kit.exe.xyz/site/components/button), (中文(简体) ), [`select`](https://ui-kit.exe.xyz/site/components/select), (中文(简体) ), [`slider`](https://ui-kit.exe.xyz/site/components/slider)) (中文(简体) ).

## 安装

```bash
npm install @adia-ai/web-components
```

对于复合弹壳(admin / calm / 编辑器 / 简单 / 主题集群),配对 [`@adia-ai/web-modules`](https://npmcn.com/package/%40adia-ai/web-modules)数字 :

```bash
npm install @adia-ai/web-components @adia-ai/web-modules
```

### 使用人工智能代理( Claude Code / Cursor / Windsurf / Claude 桌面)

使用 AI 编码代理编译 UI 时, 加载 **`adia-ui-kit` 技能** 在特工的绳子。 它编码:

-   完整组件目录( 其中 `*-ui` 标签做什么 + 当使用它时)
-   组成模式(admin shell、仪表板、表格、聊天、编辑器表面)
-   飞行前舱门(在撰写前捕获到"没有申报道由的进口")
-   Plan-Execut-Verify 纪律(将结果提交真正的演示以核实)

这个技能生活在 [`.agents/skills/adia-ui-kit/`](https://github.com/adiahealth/gen-ui-kit/tree/main/.agents/skills/adia-ui-kit) 在repo;活化短语包括"用AdiaUI来构建一页","组成这个UI","线上这些组件","使用AdiaUI组件来作曲"等,以及"一个管理员应用/仪表板/形式/聊天表面的规律是什么"等. 没有技能,一个代理就与这个README作对;凭借技能,它拥有推理阶梯+目录+每个组件的配方.

## CDN — 无捆绑器( CodePen, 营销页, 静态 HTML)

自兹 **(单位:千美元)**,这个包船 预膨胀 + 精密捆绑在下面 `dist/` 使用零积分工具。 把这些放入 HTML 页面 :

```html
<!-- CSS: all components, tokens, resets (443 KB raw / ~50 KB gzipped) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.css">

<!-- JS: registers every component (~250 KB gzipped via Brotli) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.js"></script>
```

这个 `@0.8` 范围跟踪最新 `0.8.x` 自动补丁( 不会跳到断开处) `0.9`) (中文(简体) ). 对于可复制的建筑,用精确的版本来取而代之——例如. `@adia-ai/web-components@0.8.7/dist/web-components.min.css`。 。 。 .

对于复合弹壳,添加来自 `@adia-ai/web-modules` 看到了吗 [其读物](https://npmcn.com/package/%40adia-ai/web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) 或 [CDN 使用指南](https://ui-kit.exe.xyz/site/cdn-usage)。厨房下沉路径是 `@adia-ai/web-modules/dist/everything.min.js` (所有组件+全部4个弹壳;~424 KB gziped)——CodePen演示的一个标记.

**选择一条捆绑的道路.** 相会(如. `everything.min.js` + 一个单独的 `web-components.min.js`原因 `customElements.define` 将“名称”丢入 dup-load 上。 选择树 :

-   HTML- first / CodePen / 市场营销 → `@adia-ai/web-modules/everything` (一个标签覆盖一切)
-   仅包括部件,无壳 → `@adia-ai/web-components/js/bundled`
-   维特/网包/建设-现有根导出(`import '@adia-ai/web-components'`; 计 数 `*/bundled` 出口是添加剂——捆绑者消费者没有看到变化.

## 快开始

仅限无害环境管理——捆绑者(Vite、esbuilt、webpack 5+、Rollup) `import` 两者 `.js` 财务报告和审定财务报表 `.css`; 在简单的 HTML 使用中 `<script type="module">` + 键 `<link rel="stylesheet">`。 。 。 .

```js
import '@adia-ai/web-components';          // registers every *-ui tag
import '@adia-ai/web-components/css';      // every component's CSS (one stylesheet)
```

或每个组件 树震动意识捆绑:

```js
import '@adia-ai/web-components/components/button';        // <button-ui> only
import '@adia-ai/web-components/components/button.css';    // its CSS
```

然后在标记中使用标记 :

```html
<card-ui>
  <header>
    <span slot="icon"><avatar-ui icon="user"></avatar-ui></span>
    <span slot="heading"><text-ui strong>Hello</text-ui></span>
  </header>
  <section>Composition works out of the box — no framework.</section>
</card-ui>
```

包裹 `sideEffects` 条目保持上方的导入不为 树形; 导入 `index.js` 副作用 - 登记每个组件.

## 版式

```
web-components/
├── core/           — Reactivity + base classes
│   ├── signals.js       signal() / computed() / effect() / batch() / untracked()
│   ├── template.js      tagged templates: html, css, repeat, stamp
│   ├── element.js       UIElement — light-DOM reactive base
│   ├── form.js          UIFormElement — form-associated + ElementInternals + validation
│   ├── provider.js      global provider registration + router-ui
│   ├── anchor.js        popover + anchor-positioning
│   ├── markdown.js      lightweight markdown renderer
│   ├── transport.js     SSE / streaming helpers for LLM adapters
│   └── data-stream.js   `data-stream-*` attribute trait (HTTP/SSE/WS,
│                        signal-backed, refcounted shared transports)
│
├── components/     — ~130 *-ui custom elements (components)
│   └── <tag>/
│       ├── <tag>.js       class definition (extends UIElement / UIFormElement)
│       ├── <tag>.css      @scope(tag-ui) two-block: tokens + styles
│       ├── <tag>.yaml     authoring contract (props, slots, events, examples)
│       └── <tag>.a2ui.json  generated — do NOT edit
│
│  Composite shells (admin-shell, chat-shell, editor-shell, simple-shell,
│  theme-panel, gen-root, a2ui-root) ship in the sibling
│  `@adia-ai/web-modules` package — see ADR-0012 for the three-tier
│  rationale.
│
├── traits/         — 56 composable behaviors via defineTrait() + the
│                     <traits-host> wrapper for raw-HTML declarative
│                     composition. Generated catalog at _catalog.json
│                     drives the MCP get_traits tool + per-trait demo
│                     pages. Full contract in .claude/docs/specs/traits.md.
│
└── styles/         — Global tokens and CSS layering
    ├── tokens.css              all --a-* design tokens
    ├── colors/                 primitives / semantics / scrims
    ├── typography.css, space.css, radius.css, shadow.css
    └── themes/*.css            8 themes (ocean, forest, sunset, …)
```

建设 + dev 公用事业(包括 `build-a2ui-data.mjs`, (中文(简体) ), `qa-training.mjs`, (中文(简体) ), `a2ui-to-html.cjs`, (中文(简体) ), `mcp-call.cjs`, (中文(简体) ), `mcp-pipeline.cjs`, (中文(简体) ), `screenshot.cjs`(中文(简体) ) 住在转场 `scripts/` 目录而不是此目录 软件包——它们横跨单列波(MCP服务器,a2ui-corpus数据, 组件目录),并且不只局限于网络组件.

## 使用组件(消费者指南)

完整的消费者表面——财产反应、事件合同、形式参与、生命周期、登记、TypeScript——生活在 [**`USAGE.md`**](https://npmcn.com/package/%40adia-ai/web-components/USAGE.md)。如果您正在将 AdiaUI 整合到一个应用程序中, 而不是编写一个新的组件, 请从那里开始 .

快速引用 :

```js
// Property reactivity — every prop is signal-backed
slider.value = 75;            // triggers re-render

// Event contract — CustomEvent with typed detail (since v0.4.5)
slider.addEventListener('change', (e) => console.log(e.detail.value));

// Form participation — 15 components extend UIFormElement
new FormData(document.getElementById('settings'));  // includes every <input-ui>, <select-ui>, etc.

// Lifecycle — UIElement provides connected/render/updated/disconnected hooks
class MyWidget extends UIElement {
  connected() { /* set up */ }
  render() { /* update DOM */ }
  disconnected() { /* tear down */ }
}

// Registration — conflict-safe via defineIfFree
import { defineIfFree } from '@adia-ai/web-components/core';
defineIfFree('my-widget', MyWidget);
```

TypeScript用户:自v.4.6.起在包件中为船型. `import type { UISlider, SliderChangeEvent } from '@adia-ai/web-components'` 手型处理器; `HTMLElementTagNameMap` 被扩充到 `document.querySelector('slider-ui')` 返回时 `UISlider`。 。 。 .

## 写入组件

如果你贡献了一个新的部件(而不是消耗的部件),这是给你的。 每个组件都是单文件类扩展 `UIElement` (或 `UIFormElement` 为窗体字段)。 所有造型都住在兄弟会里 `.css` 文件使用 **双块 `@scope`**数字 :

```css
@scope (button-ui) {
  :where(:scope) {
    /* Tokens only — zero specificity, parent overrides win */
    --button-bg:     var(--a-accent-bg);
    --button-fg:     var(--a-accent-fg);
    --button-radius: var(--a-radius);
  }
  :scope {
    /* Styles — consume component tokens only, never global directly */
    background: var(--button-bg);
    color:      var(--button-fg);
    border-radius: var(--button-radius);
  }
  :scope[variant="danger"] {
    --button-bg: var(--a-danger-bg);   /* variants override tokens, not styles */
  }
}
```

撰写规则(由 `ui-audit-coherence`:

1.  **无生色** 在组件CSS中——每种颜色都通过一个符号.
2.  **变体会改变符号,模式会改变布局.** 设置选择器 `display`, (中文(简体) ), `padding`, (中文(简体) ), `flex`, (中文(简体) ), `grid`等为 a _模式_ 需要一个 合同文件中的受制裁模式属性条目.
3.  **布尔道具默认为 `false`。 。 。 .** 如果预期的默认值是"在", 翻转名称( r)`closable` → `permanent`) (中文(简体) ).
4.  **活动听众在 `connected()` 有匹配 `removeEventListener` 内 `disconnected()`。 。 。 .** 手艺稳定 `#field` 箭头,永远不要 内线.
5.  **只有轻度DOM.** 没有 `::part()`, (中文(简体) ), `::slotted()`,阴之根也. 使用 儿童属性选择器 : `:scope > [slot="icon"]`。 。 。 .

### `static template` 是结束 —— 导入它提到的内容

这个 `static template` 属性是常规的 JavaScript 关闭(典型的标记模板字元 - `() => html` 随后是模板正文)。 任何信号,变量或函数 引用必须是 **范围方面的理论** 在定义类的文件。 这是 JavaScript 范围界定, 而不是任何 AdiaUI 的特异性 —— 但让作者惊讶的是, 它来自框架, 其中模板神奇地接收道具.

```js
// ❌ WRONG — ReferenceError at runtime: minL is not defined
//   (no import; the template function can't see minL just because
//    it's exported elsewhere in the monorepo)
class MyPanel extends UIElement {
  static template = () => html`<div>L: ${minL.value}</div>`;
}

// ✅ RIGHT — import the signal locally
import { minL } from './state.js';

class MyPanel extends UIElement {
  static template = () => html`<div>L: ${minL.value}</div>`;
}
```

浏览器控制台中的错误显示为 `ReferenceError: minL is not defined` 初出炉时——不是舱载时,不是 `tsc --noEmit`。 。 。 . **模板函数机构的跟踪点**,而不是在缺失的导入,这是不引向的部分.

如果你的组件需要 外部反应状态 不同每英寸, **把它暴露为财产** 而不是达到模块范围信号:

```js
// ✅ Best — per-instance reactive prop
class MyPanel extends UIElement {
  static properties = {
    minL: { type: Number, default: 0 },
  };
  static template = el => html`<div>L: ${el.minL}</div>`;
}

// Consumer:
<my-panel .minL=${minL}></my-panel>  // signal binds reactively per ADR-template-binding
```

这个 `el` 参数是元素实例——每个信号后置属性都是被动读取.

正式写作合同: [`.claude/docs/specs/component-token-contract.md`](https://npmcn.com/package/.claude/docs/specs/component-token-contract.md)。 。 。 . 这个 `adia-ui-authoring` 技能编码了20个不可谈判的规则.

## 卡-n/抽屉-Ui 构成均等

两个都接受赤裸 `<header>` 编号 : `<section>` 编号 : `<footer>` 标记或明确 `[slot="header|body|footer"]`。当 任何直接 `[slot="icon|heading|description|action"]` 存在孩子 (单位:千美元)`:has(> …)` ——只有直生子女). 绘图器支持多节正体 有粘相头/脚. 已工作的抽屉组件页面 实例.

## A2UI 运行时间

A2UI 运行时间生活在兄弟零依赖度 [`@adia-ai/a2ui`](https://npmcn.com/package/%40adia-ai/gen-ui/a2ui) 软件包; 此软件包是组件目录, 其渲染器解析标记对应 :

```javascript
import { A2UIRenderer } from '@adia-ai/a2ui';
import '@adia-ai/web-components';   // register the custom elements

const renderer = new A2UIRenderer(document.getElementById('canvas'));
renderer.process({
  type: 'updateComponents',
  components: [
    { id: 'root', component: 'Card', children: ['hdr', 'body'] },
    { id: 'hdr',  component: 'Header', slots: { heading: 'Generated UI' } },
    { id: 'body', component: 'Section', children: ['btn'] },
    { id: 'btn',  component: 'Button', attrs: { variant: 'primary' }, content: 'Click' },
  ],
});
```

核心消息类型 : `createSurface`, (中文(简体) ), `updateComponents`, (中文(简体) ), `updateDataModel`, (中文(简体) ), `wireComponents`, (中文(简体) ), `deleteSurface` (单位:千美元) `updateStyles`编号 :`removeStyles`) (中文(简体) ). 登记册使LLM的发送正常化 异名( 例如 ). `Carousel` → `swiper-ui`)所以生成的输出很强 以命名为漂流.

## 数据流通过 `data-stream-*` 属性

有固定表的任何元素 `.data` 财产——图表-i、表格-i、, 热映射-ui、stat-ui、list-ui等——可从支持中获取 仅通过属性来源。 无每个组件选入 :

```html
<!-- HTTP one-shot fetch, JSON -->
<chart-ui type="area" x="month" y="revenue"
          data-stream-src="/api/revenue?range=3m"
          data-stream-path="data"></chart-ui>

<!-- HTTP polling every 5s -->
<table-ui sortable striped
          data-stream-src="/api/orders"
          data-stream-interval="5000"></table-ui>

<!-- Server-Sent Events, append on each message -->
<heatmap-ui type="matrix" rows="7" cols="52"
            data-stream-src="/sse/activity"
            data-stream-mode="sse"
            data-stream-merge="append"></heatmap-ui>

<!-- Spread a multi-property response onto the element -->
<stat-ui data-stream-src="/api/kpi"
         data-stream-target="*"></stat-ui>
```

模式:HTTP(一发或投票), `sse` (单位:千美元)`EventSource`, (中文(简体) ), `ws` (单位:千美元)`WebSocket`。格式: `json` (违约), `csv`, (中文(简体) ), `tsv`, (中文(简体) ), `jsonl`, (中文(简体) ), `text` ——自动从URL扩展或内容类型中检测出. 两个 属性- 相同流的元素共享一个传输 (重新计算,信号支持);明确 `data-stream-id` 让我们 不相关的配置有意共享 。 通过程序访问 页:1 `streams` 从 `core/data-stream.js`。 。 。 .

执行: `core/data-stream.js` (~360行). 满 属性表 +活演示: [`/site/components/chart#data-stream`](https://npmcn.com/package/%40adia-ai/web-components/components/chart/chart.html)。 。 。 .

## 构建

```bash
npm run build:components    # regenerate all .a2ui.json from YAML
```

大楼也写着 `packages/gen-ui/a2ui/catalog/catalog-a2ui_1_0.json` 财务报告和审定财务报表 `catalog-a2ui_1_0_rules.txt` 平面文件目录 MCP 服务器和 生成引擎消耗(ADR- 0050:目录是 `@adia-ai/a2ui`是因为 (合同).

## 主题、密度、尺度

```html
<div theme="ocean" density="compact" size="sm">
  …all descendants re-theme / re-densify / re-scale automatically…
</div>
```

-   `[theme]` - 8个主题: `default`, (中文(简体) ), `ocean`, (中文(简体) ), `forest`, (中文(简体) ), `sunset`, (中文(简体) ), `lavender`, (中文(简体) ), `rose`, (中文(简体) ), `slate`, (中文(简体) ), `midnight`
-   `[density]` —— 说 `compact` · (0.85×) `spacious` (1.15×) (中文(简体) )
-   `[size]` —— 说 `sm`|`md`|`lg` 移动整个类型尺度+组件 维度
-   `[radius]` —— 说 `sharp` (0) · `rounded` (1) 妇女 `round` (二)

每个都是CSS可变的覆被;没有类切换,没有再入.

## 依赖方向

```
gen-ui (compose/) ──reads──>  gen-ui (corpus/)  ←─reads──  web-components
mcp               ──reads──>  gen-ui
```

网络组件从未从 `@adia-ai/gen-ui` 或者说 `@adia-ai/mcp`。A2UI 渲染器 使用一个协议,而不是一个生成器——任何释放有效的 A2UI 的 信息驱动它.

## 许可证

麻省理工学院

## 常见问题

### @adia-ai/web-components 是什么？

AdiaUI网络组件——香草自定义元素\. A2UI 运行时间\( 发送、 注册、 流、 接线\) 生活在 @adia- ai/ a2ui \.

### 如何安装 @adia-ai/web-components？

在项目目录运行 npm install @adia-ai/web-components，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 adia-ui-doc、adia-ui-audit-template-children，可以用 npx adia-ui-doc 直接运行。

### @adia-ai/web-components 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adia-ai/web-components 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adia-ai/web-components 可以商用吗？

@adia-ai/web-components 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @adia-ai/web-components 的下载量有多少？

根据 npm 官方下载统计，@adia-ai/web-components 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,031 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adia-ai/web-components 还在维护吗？

最新版本 0\.8\.66 发布于 2026/09/15（1 个月前）；至今共发布 220 个版本，其中过去 12 个月发布了 220 个；首次发布于 2026/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。