表單結構定義總覽

在 Service Catalog 中，Deployment Manager 設定是一種支援的解決方案。為協助您建立及部署 Deployment Manager 設定，我們提供表單結構定義。

表單結構定義用於在 HTML 表單中排版使用者介面 (UI) 元件。具體來說，這項功能可讓雲端管理員和開發人員在建立新的執行個體或雲端部署時，提供可輸入參數的 UI。

Cloud 管理員可使用表單架構建立表單，讓使用者在推出解決方案前，先自訂 Deployment Manager 範本解決方案。舉例來說，使用者可以選取虛擬機器的機器類型、磁碟大小、區域和 CPU 數量。這些表單的樣式與 Cloud Marketplace 中使用的表單相同。

下圖為部署表單的外觀：

部署作業表單

表單結構定義的替代方案

表單結構定義是建立 UI 表單的替代方法，稱為「顯示中繼資料」。

與顯示中繼資料相比，表單結構定義的彈性更高，且為開放原始碼。

與 JSON 結構定義的關係

表單結構定義是建構在 JSON 表單結構定義之上，這是以 JSON 編寫的開放原始碼結構定義，可用於指定及驗證一組參數。

表單結構定義會參照 JSON 結構定義中的欄位，並繼承該結構定義的屬性。

您可以在 form 屬性中加入 form entry 物件的陣列，藉此在 JSON 結構定義中加入表單結構定義，如以下範例所示：

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {...}
      "form": [
        ...Form List goes here...
      ]
    }

如何指定表單結構定義例項

您可以使用 YAML 格式指定表單結構定義例項。

您建立的結構定義檔案會按照 UI 中應顯示的順序排列 UI 小工具。這個架構檔案的副檔名為 .py 或 .jinja，如Deployment Manager 說明文件所述。

接著，將檔案加入 Deployment Manager 範本的 ZIP 封存檔，然後上傳該封存檔。

表單結構定義如何融入 Service Catalog 工作流程

Cloud 管理員可透過以下方式使用表單結構定義與服務目錄：

  1. 建立 Deployment Manager 範本。
  2. 指定 JSON 結構定義，以定義或驗證 Deployment Manager 範本設定的 UI 中可使用的輸入欄位。
  3. 在表單結構定義中定義特定解決方案應包含哪些欄位，以及這些欄位的顯示順序。除了排序功能之外，您還可以使用表單結構定義，為列舉欄位 (例如下拉式選單) 和群組欄位提供友善的文字，並搭配使用區段標題。

表單清單

form entry 物件的陣列。每個物件都代表表單中的 UI 元件。無論欄位在結構定義中的實際位置為何，您都應按照您希望欄位在表單中顯示的順序指定欄位。

表單輸入

表單項目會指定表單中 UI 元件的外觀。可以是字串，指定 JSON 結構定義中欄位的鍵，或物件。如果表單項目是字串，外觀的預設值會繼承自 JSON 結構定義項目。

如果表單項目是物件，key 屬性會參照 JSON 結構定義項目。使用半形點 . 分隔巢狀值的節點。舉例來說，您可以使用 name.first 參照 name 物件中的 first 欄位。其他所有欄位皆為選用，並在指定時繼承 JSON 結構定義的預設值。

欄位
key*String
指定 JSON 結構定義中的欄位定義。
widgetWidget
：指定要為這個欄位使用的 UI 小工具。預設：根據欄位類型對應。
titleString
欄位標題。從結構定義繼承 title。
notitleBoolean
是否要隱藏標題。預設值為 false。
descriptionString
用於欄位的提示或工具提示。從結構定義繼承 description。
validationMessageString
當欄位無效時顯示的訊息。
placeholderString
欄位預留位置。注意：Material Design 會改用 title 做為預留位置。
readonlyBoolean
欄位是否為唯讀。從結構定義繼承 readonly。
conditionString
邏輯運算式，用於決定是否顯示欄位。
titleMapTitle map
為 checkboxes、radio 和 select 小工具中的選項提供文字標籤。

* 必填

類型的特殊處理

物件

對於 object 類型，additionalProperties 欄位會定義是否可以使用額外屬性。這個欄位的值可以是 true (允許任何屬性)、false (不允許額外屬性)，或是限制允許的額外屬性的 JSON 結構定義。如果值為 false 或不存在，系統會針對 items 屬性中列出的欄位顯示小工具。對於其他值 (true 或 JSON 結構定義)，系統會顯示文字方塊，供您輸入 JSON 值。

類型與小工具對應

如果表單結構定義中未指定小工具，系統會根據欄位的 JSON 結構定義類型使用預設值，如下所示：

結構定義類型 結構定義表單小工具
字串 文字
數字 number
整數 number
布林值 核取方塊
物件 fieldset
字串 + 列舉 radio (選項數量少於 3 個)
字串 + 列舉 選取 (4 個以上選項)
陣列 + 列舉 核取方塊
陣列 陣列

小工具

小工具會指定為字串，參照下列其中一個資料結構。

陣列

可新增、移除及重新排序資料列的清單。JSON 結構定義允許 array 類型的 items 屬性為結構定義或結構定義清單。表單結構定義不支援清單。

含有原始項目的陣列

由於表單結構定義要求所有表單項目都必須有一個鍵，而包含原始 (非物件) 項目的陣列則沒有可用來參照的鍵，因此表單應使用保留字參照原始陣列項目：'x-googleProperty'。

舉例來說，您可以定義包含字串的 JSON 結構定義陣列，如下所示：

    {
      'exampleArray': {
        'type': 'array',
        'items': {
          'type': 'string'
        }
      }
    }

接著，應在表單結構定義中以以下方式參照：

    [
      {
        'key': 'exampleArray',
        'widget': 'array',
        'items': [
          {
            'key': 'exampleArray.x-arrayPrimitive'
          }
        ]
      },
    ]

含有物件項目的陣列

包含物件的陣列應指定項目類型中的每個鍵，以便在表單中顯示。

舉例來說，請考慮包含物件的 JSON 結構定義陣列：

    {
      'exampleArray': {
        'type': 'array',
        'items': {
          'type': 'object',
          'properties': {
            'someArrayItemAttribute': {
              'type': 'string'
            }
          }
        }
      }
    }

如要建立表單陣列，並為 someArrayItemAttribute 屬性提供輸入內容，所需的表單結構定義如下：

    [
      {
        'key': 'exampleArray',
        'widget': 'array',
        'items': [
          {
            'key': 'exampleArray.someArrayItemAttribute'
          }
        ]
      },
    ]

核取方塊

輸入欄位的類型為 checkbox。

核取方塊

類型為 checkbox 的輸入欄位清單。JSON 架構欄位應為 array 類型，並具有 enum 屬性。如要為選項提供標籤，您可以指定 titleMap。

展開箭頭

與區段非常相似，但會將欄位放在展開式面板小工具中，使用者只要按一下標題即可開啟和關閉。

數字

輸入欄位的類型為 number。下列 JSON 架構屬性是欄位的驗證工具：minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf。

密碼

輸入欄位的類型為 password。

廣播

輸入欄位的類型為 radio。適用於 JSON 結構定義中含有 enum 清單的欄位，或屬於布林值類型的欄位。如要為選項提供標籤，您可以指定 titleMap。

區段

這個小工具會將一組欄位分組。系統會忽略 key 欄位。區段包含必填的 items 屬性，這是 表單項目物件的陣列。區段可包含下列選用屬性：title、description、condition。

選取

select 輸入欄位。適用於 JSON 結構定義中含有 enum 清單的欄位，或屬於布林類型的欄位。如要為選項提供標籤，您可以指定 titleMap。

文字

類型為 text 的輸入小工具。如果 JSON 結構定義包含 pattern 屬性，系統會使用模式做為規則運算式驗證工具。

Textarea

文字輸入區塊小工具。在某些情況下，系統會顯示這個小工具，讓您直接輸入 JSON。請參閱「物件」一文。

標題對應

titleMap 屬性可用於指定 checkboxes、radio 和 select 類型的小工具。其他小工具會忽略此屬性。

該屬性是物件陣列，其中包含兩個屬性：value 和 name。value 屬性是指向該欄位一個列舉值的參照。name 屬性是用於 UI 小工具中對應選項的標籤文字。如果小工具是 radio 或 checkboxes，系統會新增選用的 description 欄位，做為該圓形按鈕或核取方塊的副標題。

如果未提供 titleMap，系統會改用列舉值。

不支援的功能

表單結構定義目前不支援下列功能：

  • 全域選項
  • 複雜的驗證訊息 (僅支援一則訊息)
  • 驗證訊息內插
  • 驗證訊息函式
  • 自訂驗證
  • 不支援的小工具：actions、fieldset、radios-inline、radiobuttons、help、template、tab、tabarray
  • 不支援的選項：onChange、feedback、disabledSuccessState、disabledErrorState、ngModelOptions、htmlClass、fieldHtmlClass、labelHtmlClass、copyValueTo、destroyStrategy
  • 後置處理函式
  • 事件
  • 手動插入欄位