# @a2ui/web\_core 中文文档

规范地址：https://npmcn.com/package/%40a2ui/web_core/

版本：0\.15\.0
npm 元数据更新时间：2026-11-02T02:44:15.215Z
中文译文更新时间：2026-11-05T16:54:44.069Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40a2ui/web_core
原文对照：https://npmcn.com/package/%40a2ui/web_core/?lang=original
项目主页：https://a2ui.org/
源码仓库：https://github.com/a2ui-project/a2ui

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

- 包体积（解压后）：8.6 MB，1095 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-03-04T19:55:15.482Z
- 最新版本发布：2026-11-02T02:44:15.018Z
- 近 30 天下载量：3894695（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

A2UI 核心库

## 安装

```sh
npm install @a2ui/web_core
```

也可以使用：`pnpm add @a2ui/web_core`、`yarn add @a2ui/web_core`、`bun add @a2ui/web_core`

## README

# @ a2ui/ web core (韩语)

这个 `@a2ui/web_core` 软件包为 A2UI 框架提供状态管理、协议解析和计划生成。 它具有框架不可知性,为Angular,React等渲染器包提供基础引擎.

## 特征

-   **协议处理**:在所有支持的协议版本中执行 A2UI 规格消息验证和状态处理.
-   **州管理层**: 使用 `@preact/signals-core`。 。 。 .
-   **数据语句**: 数据绑定、范围界定和职能评价以及依赖跟踪.
-   **目录系统**: 支持运行时验证和计划生成的组件和函数目录.
-   **Schema- Driven 代码生成**: 从规格JSON schemas直接取自自自动生成的Zod schemas和TypeScript组件/函数定义.

## 建筑

渲染是由一个 `SurfaceGroupModel` 及其组成 `SurfaceModel` 实例 `DataModel` 管理反应状态, `DataContext` 提供表达评价 `MessageProcessor` 验证并应用收到的协议消息.

## Schema 代码生成( C)

协议信件计划,常见类型和目录定义直接由 JSON 计划生成 `specification/` 目录.

### 运行代码生成

重新生成所有 Zod 计划和目录 API :

```bash
# Generate all protocol Zod schemas and versioned Basic Catalog APIs
yarn generate-zod-schemas

# Or run individual version generators directly
node src/v0_9/scripts/generate-catalog.mjs
node src/v1_0/scripts/generate-catalog.mjs
```

### Catalog Schema 合同

代码生成器使用 **斯克马平板电脑** 保留版本 目录 和类型不可知性 Schema文件坚持以下结构:

#### 1\. 目录JSON`catalog.json`(中文(简体) )

-   **顶级词典**数字 :
    -   `components`: 将组件名称映射到 JSON schema 对象.
    -   `functions`:将函数名称映射到 JSON schema 对象.
-   **歧视者**数字 :
    -   衍生自 `catalog.discriminator.propertyName` (违约) `"component"`) (中文(简体) ).
    -   歧视者的财产和 `"id"` 在生成的属性计划中省略,因为它们是由运行时组件信封处理的.
-   **继承和内涵**数字 :
    -   可使用组件 `allOf` 参考通用信封(例如: `ComponentCommon` 或者说 `CatalogComponentCommon`) (中文(简体) ). 生成器递归解决 `$ref` 指向并合并 `allOf` 枝入平地产袋.
-   **职能**数字 :
    -   函数指定 a `returnType` (例如:. `"string"`, (中文(简体) ), `"number"`, (中文(简体) ), `"boolean"`, (中文(简体) ), `"validationResult"`)在根一级,并定义其中的参数 `args` 或者说 `parameters` 对象属性.

#### 2\. 可重复使用的类型定义(`common_types.json`(中文(简体) )

-   **`$defs` 范围**数字 :
    -   可再利用类型计划 `$defs`。定义名称没有硬编码;任何定义都存在于 `$defs` 可在引用时动态解决.
-   **参考说明**数字 :
    -   当组件属性引用时 `$defs/<DefName>`,生成器将它映射到 `<DefName>Schema` 并附有 `.describe('REF:#/$defs/<DefName>|<description>')` 注释.
    -   跑步时, `generateValidationSchema` 检查这些标记以发出 `$ref` 未使用的指针和树摇 `$defs` 定义.
-   **儿童参考资料**数字 :
    -   单身儿童参考书目和收集儿童资料时,应注明 `$defs` 参考指标或说明表明儿童构成关系(例如提及 `ComponentId`, (中文(简体) ), `Child`,或 `ChildList`) (中文(简体) ).

## 目录序列化

A 类 `Catalog` 有三个序列化切入点:

-   `Catalog.fromJson(json, protocolVersion?, catalogId?)` 将目录文档装入目录模型。 每个条目都是 `JsonComponentApi` 或者说 `JsonFunctionApi` 其模型是其书面的JSON Schema定义`jsonSchema`));其佐德 `schema` 来源于关于第一使用的定义。 目录保留文档级别字段(元数据,命名为 `$defs`,其他顶级密钥). `protocolVersion`,当给出时,优先于文档宣布的版本并选择加载规则,同时 `toJson` 仍然写文档的自己 `protocolVersion`;没有它,文档的版本适用,那么 `DEFAULT_PROTOCOL_VERSION`。 。 。 . `catalogId` 替换文档本身的ID.
-   `catalog.toJson()` 从模型组装未分解的目录文档,计算 `anyComponent` 财务报告和审定财务报表 `anyFunction` 工会。 装入目录 `fromJson` 返回其文档时未修改(减去文档中遗漏的任何条目) `anyComponent.oneOf` 或者说 `anyFunction.oneOf` 工会,其中 `fromJson` 装入时过滤). 在代码中定义的条目, Zod 计划用 `spec()` 在目录协议版本的布局中从模型中计算出它的定义; 代码中定义的任何其他条目都来自它的Zod schema. 计算结果为每个目录一次;每次呼叫返回一份新副本.
-   `catalog.validationSchema` 是用于验证有效载荷的自成一体的计划:常见类型和目录本身 `$defs` 捆绑到 `$defs` 和每个 `$ref` 当地。 每个目录计算一次;每个目录读出一份新副本.

```ts
import {Catalog} from '@a2ui/web_core';

const catalog = Catalog.fromJson(document);
const unchanged = catalog.toJson(); // deep-equals document
const schema = catalog.validationSchema; // bundled JSON Schema
```

这个 `Catalog` 构造器为 a `CatalogOptions` 对象作为其第五个参数 `themeSchema`,文档级字段(`instructions`, (中文(简体) ), `schemaUri`, (中文(简体) ), `schemaId`, (中文(简体) ), `title`, (中文(简体) ), `description`, (中文(简体) ), `declaredProtocolVersion`, (中文(简体) ), `declaresCatalogId`, (中文(简体) ), `declaresComponents`, (中文(简体) ), `functionsLayout`, (中文(简体) ), `unions`, (中文(简体) ), `defs`, (中文(简体) ), `extensionFields`这 `toJson` 发布,并且,对于代码定义的目录, `commonTypesUri`, (中文(简体) ), `themeLocation` 财务报告和审定财务报表 `defModels`。 。 。 . `catalog.withEntries(components, functions)` 返回具有相同字段和其他条目的目录,因为目录转换器需要.

`catalog.derive(options)` 返回自编号下新建目录,该目录由下列条目构建: `catalog` 和新来的。 单位 `components` 财务报告和审定财务报表 `functions`,一个名称保留该名称的条目,一个对象添加一个条目。 新目录没有保留源代码 `$id`,标题,描述或指示,因为基本目录的指示,例如,在其示例中标明其编号:

```ts
const chatCatalog = basicCatalog.derive({
  catalogId: 'https://example.com/catalogs/chat.json',
  components: ['Text', 'Image', 'Row', 'Column', 'Button', carousel],
  functions: ['openUrl'],
  instructions,
});
```

### 规格说明

`spec(schema, annotation)` 返回 Zod 的 schema 副本, 记录目录文件在 schema 本身之外所写的内容, 而无需更改验证 : `mixins` (常见类型,例如: `'ComponentCommon'`,则 `specDef()` 一个组件定义的模型 `allOf`, (中文(简体) ), `closure` (单位:千美元)`additionalProperties` 或者说 `unevaluatedProperties`, (中文(简体) ), `required` (会议顺序) `required` 清单), `allOf` (按照schema自己的方案,例如格式规则)和 `keywords` (例如: `format`) (中文(简体) ). `specDef(name, schema)` 命名文档中宣布的模型 `$defs`。描述来自 `.describe()`,以及来自 `REF:#/$defs/<Name>` 说明标记.

```ts
import {Catalog, spec, specDef} from '@a2ui/web_core/catalog';
import {z} from 'zod';

const Common = specDef('Common', z.object({weight: z.number().optional()}));
const Badge = {
  name: 'Badge',
  schema: spec(
    z
      .object({...Common.shape, label: z.string()})
      .describe('A badge.')
      .strict(),
    {mixins: ['ComponentCommon', Common]},
  ),
};
// Badge's definition composes ComponentCommon and #/$defs/Common with allOf,
// and $defs.Common is computed from the Common model.
const document = new Catalog('https://example.com/badges', '0.9', [Badge]).toJson();
```

内置的基本目录是用这种方式来建造的. 它们的组件和功能是 Zod 模型,由已出版的目录文件生成 `scripts/generate-catalog-schemas.mjs` (v0.9和v1)和 `src/v0_8/scripts/generate-catalog.mjs` (v0.8),作为 `yarn generate-zod-schemas`对于每一个计划节点, 生成器预测 JSON Schema `toJson` 来源于它发出的Zod代码, 并用与公布的策略的区别来注释节点. `toJson` 每个基本目录从模型中计算其已公布的文档; 包中不保存文档副本.

## 发展

### 大楼

软件包使用 `wireit` 用于构建管弦乐 :

```bash
yarn build
```

### 测试

运行单元测试 :

```bash
yarn test
```

运行符合性测试套件 :

```bash
node tests/conformance/conformance_test.mjs
```

运行时间大小写 `conformance/core/message_processor_scaling.yaml`,它检查处理许多小信息中发出的表面需要与其大小成正比的时间。 时间取决于机器及其负荷,所以 `yarn test` 将这些案件排除在外:

```bash
yarn test:timing
```

### 格式化和 Linting

```bash
yarn format
yarn lint
```

## 常见问题

### @a2ui/web\_core 是什么？

A2UI 核心库

### 如何安装 @a2ui/web\_core？

在项目目录运行 npm install @a2ui/web\_core，或使用 pnpm add / yarn add / bun add。

### @a2ui/web\_core 支持 TypeScript 吗？

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

### @a2ui/web\_core 支持 ESM 还是 CommonJS？

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

### @a2ui/web\_core 可以商用吗？

@a2ui/web\_core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @a2ui/web\_core 的下载量有多少？

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

### @a2ui/web\_core 还在维护吗？

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