Form Schema 概览

在 Private Catalog 中,一种受支持的解决方案是 Deployment Manager 配置。为了帮助您创建和部署 Deployment Manager 配置,我们提供了 Form Schema。

Form Schema 用于在 HTML 表单中布置界面 (UI) 组件。具体而言,借助 Form Schema,云管理员和开发者可以提供一个界面,用于在创建新实例或云部署时输入参数。

云管理员使用 Form Schema 来创建表单,以便用户在发布解决方案之前自定义基于 Deployment Manager 模板的解决方案。例如,用户可以选择虚拟机具备的机器类型、磁盘大小、区域和 CPU 数量。这些表单与 Cloud Marketplace 中使用的表单类似。

下面的屏幕截图展示了部署表单的外观:

部署表单

Form Schema 的替代方案

Form Schema 是创建界面表单(称为“显示元数据”)的另一种方法。

与显示元数据相比,Form Schema 更灵活,而且开放源代码。

与 JSON 架构的关系

Form Schema 以 JSON 架构表单为基础,后者是用 JSON 编写的开源架构,可用于指定和验证一组参数。

Form Schema 引用 JSON 架构中的字段,并继承其中的特性。

您可以在 JSON 架构内添加 Form Schema,方法是在 form 特性中加入 form entry 对象数组,如下例所示:

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

如何指定 Form Schema 实例

您可以采用 YAML 格式指定 Form Schema 实例。

您可以创建一个架构文件,该文件按照在界面中的显示顺序布置界面微件。此架构文件具有文件扩展名 .py 或 .jinja,如 Deployment Manager 文档中所述。

然后,您可以将这些文件添加到 Deployment Manager 模板 zip 归档文件中,并上传该 zip 归档文件。

Form Schema 在 Private Catalog 工作流中的位置

云管理员可以将 Form Schema 与 Private Catalog 搭配使用:

  1. 创建 Deployment Manager 模板。
  2. 指定 JSON 架构来定义或验证可以在 Deployment Manager 模板配置的界面中使用的输入字段。
  3. 在 Form Schema 中定义要为特定解决方案添加哪些字段以及这些字段的显示顺序。除了排序之外,您还可以使用 Form Schema 为枚举字段(如下拉列表)提供方便用户使用的文本,并将字段与部分标题一起分组。

表单列表

form entry 对象数组。每个对象都代表表单中的一个界面组件。您应按照您希望字段在表单中显示的顺序指定字段,而不考虑它们在架构中的位置。

表单条目

表单条目指定界面组件在表单中的外观。它可以是字符串(在其中指定 JSON 架构中的字段的键)或对象。当表单条目为字符串时,其外观的默认值继承自 JSON 架构条目。

当表单条目是对象时,key 特性引用 JSON 架构条目。使用点 . 分隔嵌套值的节点。例如,使用 name.first 引用 name 对象中的 first 字段。所有其他字段均为可选字段,并且在指定的地方从 JSON 架构继承默认值。

字段
key*String
指定 JSON 架构中的字段定义。
widgetWidget
指定此字段使用的界面微件。默认值:基于映射字段类型
titleString
字段的标题。从架构继承 title
notitleBoolean
是否隐藏标题。默认值:false。
descriptionString
用作字段的提示。从架构继承 description
validationMessageString
字段无效时显示的消息。
placeholderString
字段的占位符。注意:Material Design 使用 title 作为占位符。
readonlyBoolean
字段是否为只读。从架构继承 readonly
conditionString
用于确定是否显示字段的逻辑表达式。
titleMapTitle map
checkboxesradioselect 微件中的选项提供文本标签。

* 必需

类型的特殊处理

对象

对于 object 类型,字段 additionalProperties 指定是否可以显示额外属性。字段的值可以是 true(允许任何值)、false(不允许使用任何额外属性)或某种 JSON 架构(限制允许的其他属性)。如果值为 false 或不存在,则会显示 items 特性中列出的字段的微件。对于其他值(true 或 JSON 架构),会显示一个文本区域,用于输入 JSON 值。

“从类型到微件”映射

如果 Form Schema 中没有指定微件,则系统会根据字段的 JSON 架构类型使用默认值,如下所示:

架构类型 架构表单微件
字符串 文本
数字 数字
整数 数字
布尔值 复选框
对象 字段集
字符串 + 枚举 单选按钮(不超过 3 个选项)
字符串 + 枚举 选择(4 个或更多选项)
数组 + 枚举 复选框
数组 数组

微件

微件被指定为字符串,它引用以下任一数据结构。

数组

可添加行、移除行以及重新排列行的列表。JSON 架构允许 array 类型的 items 属性为架构或架构列表。Form Schema 不支持此列表。

包含基元项的数组

由于 Form Schema 要求所有表单条目都有一个键,而包含基元(非对象)项的数组没有引用它们的键,因此表单应使用以下保留关键字引用基元数组条目:“x-googleProperty”。

例如,您可以按如下方式定义包含字符串的 JSON 架构数组:

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

然后在 Form Schema 中按如下方式引用:

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

包含对象项的数组

包含对象的数组应指定项类型中应以表单呈现的每个键。

例如,假设有一个包含对象的 JSON 架构数组:

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

使用 someArrayItemAttribute 特性的输入创建表单数组所需的 Form Schema 如下:

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

复选框

checkbox 类型的输入字段。

复选框

checkbox 类型的输入字段列表。JSON 架构字段的类型应为 array,并且具有 enum 特性。要为选项提供标签,您可以指定 titleMap

扩展控件

与部分很相似,但将字段放置在扩展面板微件内,用户只需点击标题即可打开和关闭扩展面板微件。

数字

number 类型的输入字段。JSON 架构中的以下特性是字段验证器:minimummaximumexclusiveMinimumexclusiveMaximummultipleOf

密码

password 类型的输入字段。

无线网络

radio 类型的输入字段。对于 JSON 架构中包含 enum 列表或为布尔值类型的字段,请使用此类型。要为选项提供标签,您可以指定 titleMap

部分

此微件集合了一组字段。系统会忽略 key 字段。部分具有所需的 items 特性,该特性是一组表单条目对象。部分可以包含下列可选特性:titledescriptioncondition

选择

select 输入字段。对于 JSON 架构中包含 enum 列表或为布尔值类型的字段,请使用此类型。要为选项提供标签,您可以指定 titleMap

文本

text 类型的输入微件。如果 JSON 架构包含 pattern 特性,则该模式将用作正则表达式验证器。

文本区域

文本区域输入微件。在某些情况下,此微件直接输入了 JSON。请参阅对象

标题映射

可以为 checkboxesradioselect 类型的微件指定 titleMap 特性。其他微件会忽略该特性。

该特性是包含 valuename 两个特性的对象数组。value 特性是对字段的一个枚举值的引用。 name 特性是文本,用作界面微件中对应选项的标签。当微件是 radiocheckboxes 时,可选的 description 字段将作为该单选按钮或复选框的辅助字段添加。

如果未提供 titleMap,则使用枚举值。

不支持的功能

Form Schema 目前不支持以下功能:

  • 全局选项
  • 复杂的验证消息(仅支持一条消息)
  • 验证消息插值
  • 验证消息函数
  • 自定义验证
  • 不支持的微件:actionsfieldsetradios-inlineradiobuttonshelptemplatetabtabarray
  • 不支持的选项:onChangefeedbackdisabledSuccessStatedisabledErrorStatengModelOptionshtmlClassfieldHtmlClasslabelHtmlClass copyValueTodestroyStrategy
  • 后处理函数
  • 事件
  • 手动插入字段