A2UI 元件庫參考資料

這個頁面提供所有可用 A2UI 元件的完整參考資料，包括版面配置、顯示、互動和容器元件，以及常見屬性。

常見屬性

無論具體類型為何，所有元件都共用一組可設定的通用屬性：

屬性 必填 說明
id 是 目前介面中元件的專屬 ID。
accessibility 否 改善無障礙功能的屬性，例如標籤和角色。
weight 否 在 Row 或 Column 版面配置中使用的值，可控制元件相對於同層級元件所占用的空間大小，類似於 flex-grow。

如要查看所有屬性的完整規格 (包括通用和元件專屬屬性)，請參閱「標準目錄定義 (JSON 結構定義)」。

版面配置元件

版面配置元件可用來在使用者介面中建構及排列其他元件。以下是可用的版面配置元件：

列

Row 是版面配置元件，用於從左到右水平排列子項元件。可做為容器，並排放置多個元件。使用 distribution 和 alignment 屬性，即可控制子項在資料列中的確切間距和位置。

下表列出 Row 元件可用的屬性：

屬性 類型/值 說明
children explicitList或template 要在 Row 中水平排列的子項元件。
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 要在 Column 中垂直排列的子項元件。
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 元件會顯示指定網址的圖片，並提供選項來控制圖片在容器中的顯示方式。

下表列出 Image 元件可用的屬性：

屬性 類型/值 說明
url BoundValue 要顯示的圖片網址。
fit 字串 圖片配合容器大小調整的方式 (例如「cover」)。
usageHint 字串 使用提示 (例如「主頁橫幅」)。

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 (例如「文字」元件)。
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" }
      ]
    }
  }
}