A2UI 组件库参考文档

此页面全面介绍了所有可用的 A2UI 组件，包括布局、显示、互动和容器组件，以及通用属性。

通用属性

所有组件（无论其具体类型如何）都共享一组可配置的通用属性：

属性 必需 说明
id 是 当前界面中组件的唯一标识符。
accessibility 否 用于提升无障碍功能的属性，例如标签和角色。
weight 否 在 Row 或 Column 布局中使用的值，用于控制组件相对于其同级组件所占用的空间大小，类似于 flex-grow。

如需查看所有属性（包括通用属性和 组件专用属性）的完整规范，请参阅标准目录定义（JSON 架构）。

布局组件

布局组件用于在界面中构建和排列其他组件。可用的布局组件如下：

行

Row 是一种布局组件，用于从左到右水平排列其子组件。它充当一个容器，您可以在其中并排放置多个组件。可以使用 distribution 和 alignment 属性控制行中子项的确切间距和位置。

下表列出了 Row 组件可用的属性：

属性 类型/值 说明
children explicitList 或 template 要在 行中水平排列的子组件。
distribution start、center、end、 spaceBetween、spaceAround、spaceEvenly 控制子组件沿水平 轴的分布方式。
alignment start、center、end、stretch 控制子组件在垂直轴上的对齐方式。

JSON

{
  "id": "toolbar",
  "component": {
    "Row": {
      "children": { "explicitList": ["btn1", "btn2", "btn3"] },
      "distribution": "spaceBetween",
      "alignment": "center"
    }
  }
}

列

Column 是一种布局组件，用于从上到下垂直排列其子组件。它充当一个容器，您可以在其中上下放置多个组件。可以使用 distribution 和 alignment 属性控制列中子项的确切间距和位置。

下表列出了 Column 组件可用的属性：

属性 类型/值 说明
children explicitList 或 template 要在列中垂直排列的子组件。
distribution start、center、end、spaceBetween、spaceAround、 spaceEvenly 控制子组件沿垂直 轴的分布方式。
alignment start、center、end、 stretch 控制子组件在水平 轴上的对齐方式。

JSON

{
  "id": "content",
  "component": {
    "Column": {
      "children": { "explicitList": ["header", "body", "footer"] },
      "distribution": "start",
      "alignment": "stretch"
    }
  }
}

列表

List 是一种布局组件，用于显示可滚动的项列表。它支持静态子项和动态模板，以便根据数据生成项。 滚动方向可以是垂直或水平。

下表列出了 List 组件可用的属性：

属性 类型/值 说明
children explicitList 或 template 要在列表中显示的项。
direction vertical、horizontal 列表的滚动方向。
alignment start、center、end、stretch 控制列表项在交叉轴上的对齐方式。

JSON

{
  "id": "message-list",
  "component": {
    "List": {
      "children": {
        "template": {
          "dataBinding": "/messages",
          "componentId": "message-item"
        }
      },
      "direction": "vertical"
    }
  }
}

显示组件

显示组件用于向用户呈现信息。可用的显示组件如下：

文本

Text 组件用于显示文本内容，并支持各种样式提示，例如标题、说明文字和正文。

下表列出了 Text 组件可用的属性：

属性 类型/值 说明
text BoundValue 要显示的文本内容。
usageHint h1、h2、h3、h4、h5、caption、body 文本的样式提示。

JSON

{
  "id": "title",
  "component": {
    "Text": {
      "text": { "literalString": "Welcome to A2UI" },
      "usageHint": "h1"
    }
  }
}

图片

Image 组件用于显示指定网址中的图片，并提供用于控制图片如何适应其容器的选项。

下表列出了 Image 组件可用的属性：

属性 类型/值 说明
url BoundValue 要显示的图片的网址。
fit 字符串 图片应如何适应其容器（例如“cover”）。
usageHint 字符串 使用提示（例如“hero”）。

JSON

{
  "id": "hero",
  "component": {
    "Image": {
      "url": { "literalString": "https://example.com/hero.png" },
      "fit": "cover",
      "usageHint": "hero"
    }
  }
}

图标

Icon 组件用于显示目录中定义的标准集中的图标。

下表列出了 Icon 组件可用的属性：

属性 类型/值 说明
name BoundValue 要显示的图标的名称（例如“check”）。

JSON

{
  "id": "check-icon",
  "component": {
    "Icon": {
      "name": { "literalString": "check" }
    }
  }
}

分隔线

Divider 组件用于显示可视分隔线，该分隔线可以是水平或垂直的。

下表列出了 Divider 组件可用的属性：

属性 类型/值 说明
axis horizontal、vertical 分隔线的方向。

JSON

{
  "id": "separator",
  "component": {
    "Divider": {
      "axis": "horizontal"
    }
  }
}

互动组件

借助互动组件，您可以与应用互动，例如提供输入或触发操作。可用的互动组件如下：

按钮

Button 组件是一个可点击的元素，用于触发应用中的特定操作或事件。

下表列出了 Button 组件可用的属性：

属性 类型/值 说明
child 组件 ID 要在按钮内显示的组件的 ID（例如 Text 组件）。
primary 布尔值 这是否是主要（强调）按钮。
action 对象 点击按钮时触发的操作。

JSON

{
  "id": "submit-btn",
  "component": {
    "Button": {
      "child": "submit-text",
      "primary": true,
      "action": {
        "name": "submit_form"
      }
    }
  }
}

TextField

TextField 是一种互动组件，可让您输入文本。它还支持可选验证。

下表列出了 TextField 组件可用的属性：

属性 类型/值 说明
label BoundValue 文本字段的标签。
text BoundValue 文本内容或绑定路径。
textFieldType shortText、longText、number、obscured、date 文本字段的类型。
validationRegexp 字符串 用于验证的正则表达式。

JSON

{
  "id": "email-input",
  "component": {
    "TextField": {
      "label": { "literalString": "Email Address" },
      "text": { "path": "/user/email" },
      "textFieldType": "shortText"
    }
  }
}

CheckBox

CheckBox 组件是一个布尔值切换开关，可让您开启或关闭设置。

下表列出了 CheckBox 组件可用的属性：

属性 类型/值 说明
label BoundValue 复选框的标签。
value BoundValue（布尔值） 复选框的值（true/false）或绑定路径。

JSON

{
  "id": "terms-checkbox",
  "component": {
    "CheckBox": {
      "label": { "literalString": "I agree to the terms" },
      "value": { "path": "/form/agreedToTerms" }
    }
  }
}

滑块

Slider 组件可让您从特定范围内选择一个数值。

下表列出了 Slider 组件可用的属性：

属性 类型/值 说明
value BoundValue（数值） 滑块的当前值或绑定路径。
minValue 数值 范围的最小值。
maxValue 数值 范围的最大值。

JSON

{
  "id": "volume",
  "component": {
    "Slider": {
      "value": { "path": "/settings/volume" },
      "minValue": 0,
      "maxValue": 100
    }
  }
}

DateTimeInput

DateTimeInput 组件可让您选择日期和时间。

下表列出了 DateTimeInput 组件可用的属性：

属性 类型/值 说明
value BoundValue 所选的日期/时间值或绑定路径。
enableDate 布尔值 是否启用日期选择。
enableTime 布尔值 是否启用时间选择。

JSON

{
  "id": "date-picker",
  "component": {
    "DateTimeInput": {
      "value": { "path": "/booking/date" },
      "enableDate": true,
      "enableTime": false
    }
  }
}

多项选择

MultipleChoice 组件可让您从列表中选择一个或多个选项。

下表列出了 MultipleChoice 组件可用的属性：

属性 类型/值 说明
options 对象数组 用户可选择的选项列表。每个选项都应有一个标签和一个值。
selections BoundValue 所选的值或绑定路径。
maxAllowedSelections 数值 允许选择的最大数量。

JSON

{
  "id": "country-select",
  "component": {
    "MultipleChoice": {
      "options": [
        { "label": { "literalString": "USA" }, "value": "us" },
        { "label": { "literalString": "Canada" }, "value": "ca" }
      ],
      "selections": { "path": "/form/country" },
      "maxAllowedSelections": 1
    }
  }
}

容器组件

容器组件用于对其他组件进行分组和整理。可用的容器组件如下：

卡片

Card 组件是一个具有高度、边框和内边距的容器，用于对相关内容进行分组。

下表列出了 Card 组件可用的属性：

属性 类型/值 说明
child 组件 ID 要在卡牌内显示的组件的 ID。

JSON

{
  "id": "info-card",
  "component": {
    "Card": {
      "child": "card-content"
    }
  }
}

Modal 组件是由入口点组件触发的叠加层对话框。

下表列出了 Modal 组件可用的属性：

属性 类型/值 说明
entryPointChild 组件 ID 触发模态窗口的组件的 ID（例如按钮）。
contentChild 组件 ID 要显示为模态窗口内容的组件的 ID。

JSON

{
  "id": "confirmation-modal",
  "component": {
    "Modal": {
      "entryPointChild": "open-modal-btn",
      "contentChild": "modal-content"
    }
  }
}

标签页

Tabs 组件提供了一个标签式界面，用于将内容整理到可切换的面板中。

下表列出了 Tabs 组件可用的属性：

属性 类型/值 说明
tabItems 对象数组 标签列表。每个项都应有一个 title 和一个 child（组件 ID）。

JSON

{
  "id": "settings-tabs",
  "component": {
    "Tabs": {
      "tabItems": [
        { "title": { "literalString": "General" }, "child": "general-tab" },
        { "title": { "literalString": "Privacy" }, "child": "privacy-tab" }
      ]
    }
  }
}