下拉列表小组件 (可应用主题)
 |
此小组件将替换旧式列表小组件的组合框视图。
|
下拉列表小组件可用于添加下拉菜单，从而在运行时打开项列表。可为单项或多项选择配置小组件。选定项存储在小组件 SelectedText 属性中，用户可将其作为其他小组件、功能或数据服务的输入进行绑定。可通过创建一个返回信息表的数据服务来定义项及其状态。以下是可使用小组件属性执行的配置示例：
• 将项标签与下拉列表的左侧、右侧或中心对齐
• 启用单项或多项选择
• 添加筛选框以便用户能够在较长的列表中更加快速地查找所需项
• 将样式格式化应用于列表项
| | “下拉列表”小组件可在平台中作为标准版小组件使用，也可用作 web 组件 (可从 SDK 导入)。 |
数据格式
要配置下拉列表小组件的列表项，必须创建一个数据服务，以返回具有以下字段定义的信息表：
显示字段 | 值字段 | 状态字段 | |
|---|---|---|---|
基本类型 | STRING | STRING | STRING |
说明 | 为下拉列表中的项显示的标签。 | 要用于每个项的实际值。绑定到其他小组件或数据服务后，该值将用于小组件 SelectedItems 属性。 | 可选字段，用于指定是启用还是禁用项。支持的值：Enabled 或 Disabled |
行示例 | English | en | Enabled |
信息表中的每一行定义了下拉列表中的一个项。可将数据服务配置为以静态方式生成项，或基于其他小组件或数据服务的输入以动态方式生成。
绑定列表项数据
要将配置数据绑定到下拉小组件，请执行以下步骤：
1. 使用“数据”面板为列表项添加包含数据服务的事物。
2. 将服务的 All Data 属性绑定到小组件 Data 属性。
3. 将服务绑定到 Loaded 混搭事件。
4. 在“属性”面板上，指定要用于配置下拉列表项的信息表列：
◦ DisplayField - 选择要用于项标签的列。
◦ ValueField - 选择要用于项的实际值的列。
◦ StateField - 选择要用于项状态的列。
5. 单击“保存”，然后单击“查看混搭”。
在运行时，打开下拉列表后会显示列表项。
设置列表和下拉列表间的间距
使用小组件 ListMarginTop 属性指定下拉列表和项列表之间的间距。间距的默认设置为 8 个像素。要移除间距，请将属性值设置为 0。
添加项以清除选择
默认情况下，下拉列表小组件不允许用户在运行时清除列表选择。要允许用户在运行时清除选择，请启用 ClearSelectionItem 属性。随后将向列表中添加一个带有默认标签 (“无”) 的附加项。用户可选择此项以避免在下拉列表中进行选择。
小组件属性
属性名称 | 说明 | 基本类型 | 默认值 | 是否可绑定? (Y/N) | 是否可本地化? (Y/N) | ||
|---|---|---|---|---|---|---|---|
HintText | 显示用于说明字段中应输入内容的占位符文本。 | STRING | Select... | Y | Y | ||
Label | 以小组件标签形式显示的文本。 | STRING | 不适用 | Y | Y | ||
LabelAlignment | 可用于靠左、靠右或居中对齐标签。 | STRING | 左 | Y | N | ||
Alignment | 可用于在下拉列表中将文本项靠左、靠右或居中对齐。 | STRING | 左 | Y | |||
ClearSelectionItem | 将空白选择项添加到下拉列表中。使用户能够清除选择。 | BOOLEAN | True | Y | |||
ClearSelectionLabel | 为下拉列表中的清除选择项指定自定义文本。默认情况下，将其设置为“无”。 | STRING | 无 | Y | Y | ||
Disabled | 使用此属性可以禁用混搭中的小组件。小组件会显示在混搭中，但无法单击。 | BOOLEAN | False | Y | N | ||
ShowListFilter | 用于在下拉列表内添加筛选器，且可供您在运行时筛选列表项。 | BOOLEAN | False | N | N | ||
FilterHintText | 显示下拉列表筛选器的提示文本。 | STRING | 不适用 | Y | Y | ||
ListMaxHeight | 可用于为显示的下拉列表设置最大高度。 如果下拉列表中的项数大于设置的列表高度，则会在显示中添加一个滚动条。 | NUMBER | 不适用 | Y | N | ||
ListMaxWidth | 用于设置下拉列表的最大宽度。该值必须大于等于文本字段宽度。 | NUMBER | 不适用 | Y | N | ||
StateField | 表示下拉列表中行项状态的信息表。 此属性可用于启用或禁用下拉列表中的行项。 | INFOTABLE | 不适用 | N | N | ||
MultiSelect | 使用户能够选择下拉列表中的多个项。 | BOOLEAN | False | N | N | ||
AutoSelectFirstRow | 用于将第一行设置为下拉列表中的选定选项。
| BOOLEAN | False | N | N | ||
RowHeight | 用于设置单行的行高。 | NUMBER | 34 | Y | N | ||
CustomClass | 用于定义要应用于小组件顶层 div 的 CSS 类。可以输入多个类，以空格作为分隔符。 | STRING | 不适用 | Y | N | ||
TabSequence | 当用户按下 Tab 键时，内容将在其中突出显示的小组件序列。 | NUMBER | 不适用 | N | N | ||
Data | 信息表数据源。 | INFOTABLE | 不适用 | Y | N | ||
DisplayField | 表示数据值的信息表字段。 | 不适用 | 不适用 | N | N | ||
ValueField | 用于 SelectedText 的字段。 | 不适用 | 不适用 | N | N | ||
SelectedText | 此属性有以下两种工作方式，具体取决于使用单一选择模式时的绑定方向： • In - 选择标签与属性值相匹配的项。 • Out - 检索列表中选定项的文本。
| STRING | 不适用 | Y | Y | ||
SelectedItems | 列表中选定项的信息表数据源。 | INFOTABLE | 不适用 | Y | N | ||
ListFormat | 打开一个对话框，您可通过该对话框为小组件数据指定呈现和格式化规则。 | 呈现器和状态格式 | 不适用 | N | N | ||
ListMarginTop | 设置下拉列表和项列表之间的间距。 | NUMBER | 8 | N | N | ||
TooltipField | 当您将鼠标悬停在与下拉列表关联的标签以及下拉列表中当前选定值上方时，会显示工具提示文本。 | STRING | 不适用 | Y | Y | ||
TooltipIcon | 设置下拉列表小组件工具提示的图标图像。 | MEDIA ENTITY | 不适用 | N | N |
验证下拉列表小组件数据
可通过验证属性验证运行时的项选择操作是否符合要求。例如，可要求在下拉列表中进行选择，若未进行任何选择，则显示一条错误消息。
有关验证属性的详细信息，请参阅将验证应用于小组件。
下表列出了“验证”面板上提供的验证属性。
属性 | 说明 | 基本类型 | 默认值 | 是否可绑定 (Y/N) | 是否可本地化 (Y/N) |
|---|---|---|---|---|---|
CriteriaMessage | 有关验证条件以及验证失败时显示的消息。 | STRING | 不适用 | Y | Y |
CriteriaMessageDetails | 针对验证条件和失败消息显示的详细信息。 | STRING | 不适用 | Y | Y |
RequiredMessage | 必需值设置为 true 且未选择任何项时显示的消息。 | STRING | 选择内容为必需 | Y | Y |
ShowValidationCriteria | 从下拉列表中选择项时，会显示有关所需输入的提示消息。 | BOOLEAN | False | Y | N |
ShowValidationFailure | 当输入的值验证失败时，显示失败消息。 | BOOLEAN | False | Y | N |
ShowValidationState | 一种可绑定服务，用于在运行时用户与小组件进行交互前显示验证状态。默认情况下，验证状态仅在用户交互后显示。 | 服务 | 不适用 | In | N |
ShowValidationSuccess | 当输入的值验证成功时，显示成功消息。 | BOOLEAN | False | Y | N |
SuccessMessage | 验证成功时显示的消息。 | STRING | 不适用 | Y | Y |
SuccessMessageDetails | 二级消息，显示关于验证成功消息的更多信息。 | STRING | 不适用 | Y | Y |
Validate | 更改小组件值时触发的可绑定事件。将此事件绑定至服务或函数以应用验证模式或表达式。 | 事件 | 不适用 | Y | N |
ValidationCriteriaIcon | 针对关于验证条件的提示消息，设置在其中显示的 SVG 图标。 | IMAGELINK | info | N | N |
ValidationFailureIcon | 设置验证失败时显示在状况消息中的 SVG 图标。 | IMAGELINK | error | N | N |
ValidationOutput | 检索小组件验证的输出。返回值为 Undefined、Valid、Unvalidated 或 Invalid。 | STRING | 不适用 | Y | N |
ValidationState | 用于设置验证状态的可绑定属性。可将此属性设置为 Undefined、Valid、Unvalidated 和 Invalid。 | STRING | Undefined | Y | N |
ValidationSuccessIcon | 选择验证成功时显示在消息中的 SVG 图标。 | IMAGELINK | success | N | N |
ValueRequired | 需要选择列表内的其中一项。 | BOOLEAN | False | Y | N |