# @a2ui-sdk/types 中文文档

规范地址：https://npmcn.com/package/%40a2ui-sdk/types/

版本：0\.4\.0
npm 元数据更新时间：2026-02-02T07:39:42.261Z
中文译文更新时间：2026-11-05T18:24:15.407Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：21.6 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-01-13T07:35:07.945Z
- 最新版本发布：2026-02-02T07:39:42.129Z
- 近 30 天下载量：75830（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

A2UI 类型

## 安装

```sh
npm install @a2ui-sdk/types
```

也可以使用：`pnpm add @a2ui-sdk/types`、`yarn add @a2ui-sdk/types`、`bun add @a2ui-sdk/types`

## README

# @ a2ui- sdk/ 类型

A2UI协议的TypeScript类型定义. 这个包提供了与A2UI消息,组件和数据模型合作所需的所有类型定义.

## 安装

```bash
npm install @a2ui-sdk/types
```

## 使用量

### v0.9 (最晚) (中文(简体) )

```tsx
import type {
  // Message types
  A2UIMessage,
  CreateSurfacePayload,
  UpdateComponentsPayload,
  UpdateDataModelPayload,
  DeleteSurfacePayload,

  // Component types
  Component,
  TextComponent,
  ImageComponent,
  IconComponent,
  VideoComponent,
  AudioPlayerComponent,
  DividerComponent,
  RowComponent,
  ColumnComponent,
  ListComponent,
  CardComponent,
  TabsComponent,
  ModalComponent,
  ButtonComponent,
  TextFieldComponent,
  CheckBoxComponent,
  ChoicePickerComponent,
  SliderComponent,
  DateTimeInputComponent,

  // Value types
  DynamicValue,
  DynamicString,
  DynamicNumber,
  DynamicBoolean,
  DynamicStringList,
  ChildList,
  TemplateBinding,

  // Action types
  Action,
  ActionPayload,
  ActionHandler,

  // Validation types
  CheckRule,
  Checkable,
  ValidationResult,

  // State types
  ScopeValue,
  DataModel,
} from '@a2ui-sdk/types/0.9'
```

### v. 0.8 (中文(简体) )

```tsx
import type {
  // Message types
  A2UIMessage,
  BeginRenderingPayload,
  SurfaceUpdatePayload,
  DataModelUpdatePayload,
  DeleteSurfacePayload,

  // Core types
  Surface,
  SurfaceStyles,
  ComponentDefinition,
  ComponentProps,
  ValueSource,
  DataModel,
  DataModelValue,
  DataEntry,

  // Children types
  ChildrenDefinition,
  TemplateBinding,

  // Action types
  Action,
  ActionPayload,
  ActionHandler,
  ActionContextItem,

  // Component props
  BaseComponentProps,
  TextComponentProps,
  ImageComponentProps,
  IconComponentProps,
  VideoComponentProps,
  AudioPlayerComponentProps,
  DividerComponentProps,
  RowComponentProps,
  ColumnComponentProps,
  ListComponentProps,
  CardComponentProps,
  TabsComponentProps,
  ModalComponentProps,
  ButtonComponentProps,
  CheckBoxComponentProps,
  TextFieldComponentProps,
  DateTimeInputComponentProps,
  MultipleChoiceComponentProps,
  SliderComponentProps,

  // Layout types
  Distribution,
  Alignment,

  // State types
  ScopeValue,
} from '@a2ui-sdk/types/0.8'
```

### 命名空间导入

```tsx
import { v0_8, v0_9 } from '@a2ui-sdk/types'

// Use v0.9 types
type Message = v0_9.A2UIMessage
```

## 密钥类型

### A2UIMessage (v0.9) (英语)

从服务器发送到客户端的信件 :

```tsx
type A2UIMessage =
  | { createSurface: CreateSurfacePayload }
  | { updateComponents: UpdateComponentsPayload }
  | { updateDataModel: UpdateDataModelPayload }
  | { deleteSurface: DeleteSurfacePayload }
```

### 动态值( v0. 9)

可以静态或数据绑定的值:

```tsx
// Static string or path reference
type DynamicString = string | { path: string } | FunctionCall

// Static number or path reference
type DynamicNumber = number | { path: string } | FunctionCall

// Static boolean or logic expression
type DynamicBoolean = boolean | { path: string } | LogicExpression
```

### 数值来源(v0.8)

遗留值绑定 :

```tsx
type ValueSource =
  | { literalString: string }
  | { literalNumber: number }
  | { literalBoolean: boolean }
  | { literalArray: string[] }
  | { path: string }
```

### 动作付费负荷

从客户端发送到服务器的动作 :

```tsx
interface ActionPayload {
  name: string
  surfaceId: string
  sourceComponentId: string
  timestamp: string // ISO 8601
  context: Record<string, unknown>
}
```

### 范围值(v0.8+)

收集项目渲染的范围:

```tsx
interface ScopeValue {
  /**
   * Base path for relative path resolution.
   * null = root scope (no scoping)
   * string = scoped to a specific data path (e.g., "/items/0")
   */
  basePath: string | null
}
```

内部用于支持模板交接子的相对路径(列表,行,有模板绑定的列).

## 许可证

阿帕奇 - 2.0

## 常见问题

### @a2ui-sdk/types 是什么？

A2UI 类型

### 如何安装 @a2ui-sdk/types？

在项目目录运行 npm install @a2ui-sdk/types，或使用 pnpm add / yarn add / bun add。

### @a2ui-sdk/types 支持 TypeScript 吗？

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

### @a2ui-sdk/types 支持 ESM 还是 CommonJS？

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

### @a2ui-sdk/types 可以商用吗？

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

### @a2ui-sdk/types 的下载量有多少？

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

### @a2ui-sdk/types 还在维护吗？

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