# @a2ui/angular 中文文档

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

版本：0\.14\.0
npm 元数据更新时间：2026-11-02T02:43:39.605Z
中文译文更新时间：2026-11-05T18:28:32.199Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.3 MB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@angular/core ^21\.2\.5，@angular/common ^21\.2\.5，@a2ui/markdown-it ^0\.2\.2，@angular/platform-browser ^21\.2\.5
- 首次发布：2025-12-16T01:30:54.262Z
- 最新版本发布：2026-11-02T02:43:39.432Z
- 近 30 天下载量：69742（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

角执行A2UI框架,提供代理生成的UI无缝地集成到角应用中.

## 安装

```sh
npm install @a2ui/angular
```

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

## README

# A2UI 角渲染器

角执行A2UI框架,提供代理生成的UI无缝地集成到角应用中.

## 特征

-   **反应渲染**:使用角信号来进行高效,精细的UI更新.
-   **动态组件分辨率**:通过可扩展目录将A2UI组件类型映射到Angular组件.
-   **地面管理**: 内建支持多个独立的UI在单个会话内表面.
-   **动作处理**:处理代理发送动作的简单回调集成.

## 安装

```bash
yarn add @a2ui/angular @a2ui/web_core
```

## 协议版本

A2UI支持多个协议版本,以确保随着框架的演化而后向相容. 词根 `@a2ui/angular` 软件包提供版本不可知的表面管理、组件托管和最新的标准目录.

```typescript
import {A2uiRendererService, A2UI_RENDERER_CONFIG, BasicCatalog} from '@a2ui/angular';
```

对于与先前协议版本的后向相容性,可提供特定版本的子路径:

-   `@a2ui/angular/v0_9`: v0. 9 协议和本地目录
-   `@a2ui/angular/v0_8`: v0. 8 协议和本地目录

## 基本设置

配置您的渲染器 `app.config.ts` 使用 `A2UI_RENDERER_CONFIG` 注射符号 :

```typescript
import {ApplicationConfig} from '@angular/core';
import {A2UI_RENDERER_CONFIG, A2uiRendererService, BasicCatalog} from '@a2ui/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: A2UI_RENDERER_CONFIG,
      useValue: {
        catalogs: [new BasicCatalog()],
        actionHandler: action => {
          console.log('Action received:', action);
        },
      },
    },
    A2uiRendererService,
  ],
};
```

## 使用量

### 绘制地表

最简单的制造A2UI表面的方法是使用 `SurfaceComponent`。此组件处理设置根 `ComponentHost` 给你的.

```typescript
import {Component} from '@angular/core';
import {SurfaceComponent} from '@a2ui/angular/v0_9';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [SurfaceComponent],
  template: ` <a2ui-v09-surface surfaceId="main-surface" /> `,
})
export class AppComponent {}
```

### 动态组件托管

对于更精细的控制,使用 `ComponentHostComponent` 在地表内产生特定成分:

```typescript
import {Component} from '@angular/core';
import {ComponentHostComponent} from '@a2ui/angular/v0_9';

@Component({
  selector: 'app-custom-layout',
  standalone: true,
  imports: [ComponentHostComponent],
  template: `
    <div class="user-sidebar">
      <a2ui-v09-component-host surfaceId="main-surface" componentId="sidebar-config" />
    </div>
  `,
})
export class CustomLayoutComponent {}
```

## 核心服务 : `A2uiRendererService`

这个 `A2uiRendererService` 是角成形器的心脏 它连接A2UI `MessageProcessor` 到Angular的反应系统.

-   **`processMessages(messages: Message[])`**:来自代理机的提示信息来更新UI表面.
-   **`surfaceGroup()`**: 返回 `SurfaceGroupModel` 包含所有表面的当前状态.

## 基本目录组件

这个 `@a2ui/angular/v0_9` 软件包包括一个 `BasicCatalog` 具有下列标准组件:

-   **版式**数字 : `Row`, (中文(简体) ), `Column`, (中文(简体) ), `List`, (中文(简体) ), `Card`, (中文(简体) ), `Tabs`, (中文(简体) ), `Modal`, (中文(简体) ), `Divider`
-   **内容**数字 : `Text`, (中文(简体) ), `Image`, (中文(简体) ), `Icon`, (中文(简体) ), `Video`, (中文(简体) ), `AudioPlayer`
-   **投入**数字 : `Button`, (中文(简体) ), `TextField`, (中文(简体) ), `CheckBox`, (中文(简体) ), `ChoicePicker`, (中文(简体) ), `Slider`, (中文(简体) ), `DateTimeInput`

## 警卫

> \[大 所提供的样本代码是用于演示目的,并说明了A2UI和A2A代理协议的力学. 在建立生产应用程序时,关键是要将任何在您直接控制之外运作的代理商视为一个潜在的不信任实体.

外部代理人提供的所有业务数据——包括其代理卡、信息、文物和任务状况——应作为不信任的投入处理。 例如,恶意代理可以在其领域提供被精心制作的数据(如名称,技能.description),如果在没有进行消毒的情况下用于构建大语言模型(LLM)的提示,可能会使您的应用暴露于即时注射攻击.

同样,所收到的任何UI定义或数据流都必须作为不信任处理. 恶意代理可能试图对合法接口进行套用来欺骗用户(fishing),通过属性值(XSS)来注入恶意脚本,或者产生过度的布局复杂来降低客户端性能(DoS). 如果您的应用程序支持可选的嵌入内容(如iframes或web视图),则必须额外注意防止被恶意外部网站曝光.

**开发者责任**:不能正确验证数据和严格地提供沙盒内容可能会造成严重的脆弱性。 开发者负责执行适当的安全措施,例如输入消毒、内容安全政策、对可选嵌入内容的严格隔离、以及确保证书处理,以保护他们的系统和用户.

## 常见问题

### @a2ui/angular 是什么？

角执行A2UI框架,提供代理生成的UI无缝地集成到角应用中\.

### 如何安装 @a2ui/angular？

在项目目录运行 npm install @a2ui/angular，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/core（^21\.2\.5）、@angular/common（^21\.2\.5）、@angular/platform-browser（^21\.2\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @a2ui/angular 支持 TypeScript 吗？

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

### @a2ui/angular 支持 ESM 还是 CommonJS？

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

### @a2ui/angular 可以商用吗？

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

### @a2ui/angular 的下载量有多少？

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

### @a2ui/angular 还在维护吗？

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