Microsoft.Common.DropDown UI 元素Microsoft.Common.DropDown UI element

一个包含下拉列表的选择控件。A selection control with a dropdown list. 可以允许选择一个项(单选)或多个项(多选)。You can allow selection of only a single item or multiple items. 还可以选择在项中包含说明。You can also optionally include a description with the items.

UI 示例UI sample

DropDown 元素提供不同的选项,用于确定其在门户中的视觉效果。The DropDown element has different options which determine its appearance in the portal.

当只允许选择单个项时,控件将显示为:When only a single item is allowed for selection, the control appears as:

Microsoft.Common.DropDown 单项选择

当包含说明时,控件将显示为:When descriptions are included, the control appears as:

带有说明的 Microsoft.Common.DropDown 单项选择

启用多选时,控件将添加“全选”选项和用于选择多个项目的复选框:When multi-select is enabled, the control adds a Select all option and checkboxes for selecting more than one item:

Microsoft.Common.DropDown 多选

启用多选时可以包含说明。Descriptions can be included with multi-select enabled.


启用筛选后,控件包含用于添加筛选值的文本框。When filtering is enabled, the control includes a text box for adding the filtering value.

带有说明的 Microsoft.Common.DropDown 多项选择


    "name": "element1",
    "type": "Microsoft.Common.DropDown",
    "label": "Example drop down",
    "placeholder": "",
    "defaultValue": "Value two",
    "toolTip": "",
    "multiselect": true,  
    "selectAll": true,  
    "filter": true,  
    "filterPlaceholder": "Filter items ...",  
    "multiLine": true,  
    "defaultDescription": "A value for selection",  
    "constraints": {
        "allowedValues": [
                "label": "Value one",
                "description": "The value to select for option 1.",
                "value": "one"
                "label": "Value two",
                "description": "The value to select for option 2.",
                "value": "two"
        "required": true
    "visible": true

示例输出Sample output



  • 使用 multiselect 指定用户是否可以选择多个项。Use multiselect to specify whether users can select more than one item.
  • 默认情况下,启用多选时,selectAlltrueBy default, selectAll is true when multi-select is enabled.
  • 通过 filter 属性,用户能够在众多选项中进行搜索。The filter property enables users to search within a long list of options.
  • constraints.allowedValues 的标签是项的显示文本,并且当选中时,其值是元素的输出值。The label for constraints.allowedValues is the display text for an item, and its value is the output value of the element when selected.
  • 如果已指定,则默认值必须是 constraints.allowedValues 中存在的一个标签。If specified, the default value must be a label present in constraints.allowedValues. 如果未指定,则将选择 constraints.allowedValues 中的第一个项。If not specified, the first item in constraints.allowedValues is selected. 默认值为 nullThe default value is null .
  • constraints.allowedValues 必须至少有一项。constraints.allowedValues must have at least one item.
  • 若要模拟一个不需要的值,请向 constraints.allowedValues 添加一个具有标签且值为 ""(空字符串)的项。To emulate a value not being required, add an item with a label and value of "" (empty string) to constraints.allowedValues.
  • defaultDescription 属性用于不带说明的项。The defaultDescription property is used for items that don't have a description.
  • placeholder 属性是帮助文本,当用户开始编辑后会消失。The placeholder property is help text that disappears when the user begins editing. 如果同时定义了 placeholderdefaultValue,会优先显示 defaultValueIf the placeholder and defaultValue are both defined, the defaultValue takes precedence and is shown.

后续步骤Next steps