跳到主要内容

下拉单选

WdSelect

适用场景

以列表形式展示选项,用户可进行搜索和选择操作。(原下拉选择组件)

基础能力

绑定「关联关系、主子明细、枚举-单选、文本」字段

  1. 表单容器绑定数据模型后,模型中的「关联关系、主子明细、枚举」字段会自动渲染为下拉选择组件,实现数据的选择录入
  2. 表单容器绑定数据模型后,在表单容器的字段属性中,可将文本字段映射生成的组件切换为下拉选择

选项配置

选项配置中,选项名称为页面中展示的选项业务名称,选项值为表单提交保存时向接口传参、落库保存的实际存储值

  1. 通过表单容器中的「关联关系、关联关系」字段生成渲染出下拉选择组件时,组件会自动根据字段绑定的关联模型生成选项列表,并额外提供数据筛选属性,支持对选项进行筛选过滤(该情况下,选项名称强制为关联模型的主列字段,选项值强制为关联模型的数据标识字段)
  2. 通过表单容器中的「枚举-单选」字段生成渲染出下拉选择组件时,组件会自动根据字段绑定的通用选项集生成选项列表(该情况下,选项名称强制为关联选项集的选项值,选项值强制为关联选项集的选项标识)
  3. 其他情况下,支持手动配置选项列表

选中值属性

  1. 选中值属性表示组件的默认表单值,可绑定变量或表达式实现选中值的动态变更
  2. 选中值需填入对应的选项值;填入选项名称无效

扩展场景

通过 Query 生成动态选项列表

以班级数据为示例,为下拉单选/下拉多选组件配置动态的选项列表

  1. 创建 1 个班级数据模型,在其中新建一个班级名称字段

  2. 在数据管理后台中,在该模型中录入几个班级的示例值(需注意数据管理后台左上角的数据环境,体验数据仅在编辑器开发预览、体验版应用中可用;正式版应用中使用时,需提前录入正式数据)

  3. 在编辑器左下角代码区点击+,新建微搭数据表查询,完成以下配置后,点击右上角保存按钮

    1. 数据表:选择刚才创建的班级模型

    2. 触发方式:选择入参变化时自动执行(实现页面加载时自动执行一次,查询出相关数据)

    3. 筛选条件、排序方式:可按需配置或保持为空

  4. 点击下拉单选/下拉多选组件选项属性右侧的数据绑定模式按钮

  5. 点击变量属性右侧的数据绑定按钮,变量属性绑定 $w.query1.data.records

  6. 标签名称和标签值属性选择或输入数据模型中班级名称字段的字段标识

  7. 完成以上配置后,下拉单选/下拉多选组件的选项列表,即可加载展示数据模型中的数据,实现选项列表的动态控制

其他场景实践

查阅表单场景实践指南,可学习了解关于表单的各类支持场景和实现方案

示例

交互式预览

组件输入状态

样式 API 示例

#wd-page-root .wd-form-item .wd-select-select {
border-color: cyan;
background-color: black;
border-width: 2px;
border-radius: 6px;
color: cyan;
}

属性

组件接收的外部传入的属性

属性名
属性标识
类型
说明
显示标题labelVisibleboolean

默认值:true

标题对齐labelAlignstring

表单场景下默认会跟随表单容器的标题对齐配置

标题换行labelWrapboolean

如果标题内容过长关闭时只显示一行、溢出省略;开启时换行展示。表单场景下默认会跟随表单容器的标题换行配置

标题位置layoutstring

设置标题在表单组件的展示位置,表单场景下默认会跟随表单容器的标题的位置配置

标题宽度labelWidthstring

您可以输入数值 + px、%等单位,示例:200px

表单场景下默认会跟随表单容器的标题宽度配置

标题提示labelTipsstring

PC/H5端生效

配置标题的工具提示内容

显示清空按钮clearableboolean

开启后提供快捷清空按钮

默认值:true

前缀文字beforestring

表单输入框显示前缀文字,表单提交场景下前缀文字会作为表单内容一起提交到数据模型中

后缀文字afterstring

表单输入框显示后缀文字,表单提交场景下后缀文字会作为表单内容一起提交到数据模型中

前缀图标类型prefixTypestring

选择图标的类型

示例:""

前缀图标prefixIconstring

表单输入框中展示前图标

示例:"success"

前缀图标prefixSrcstring

设置自定义图标地址

后缀图标类型suffixTypestring

选择图标的类型

示例:"fixed"

后缀图标suffixIconstring

表单输入框中展示后图标

示例:"success"

后缀图标suffixSrcstring

设置自定义图标地址

下方提示extrastring

配置后提示内容常显在输入框下方

移动端显示下划线borderedH5boolean

关闭后移动端不显示底部下划线

默认值:true

PC端显示输入边框borderedPcboolean

关闭后PC端不显示输入边框

默认值:true

状态statusstring

示例:"edit"

必填requiredboolean
必填标识requiredFlagboolean

启用后,组件若要求必填,则会显示必填星号标记

默认值:true

必填校验提示requiredMsgstring

示例:"该项为必填项"

绑定字段namestring

表单字段的Key值,用于提交数据时,匹配数据模型字段标识。表单内需保证唯一。

标题内容labelstring

示例:"下拉单选"

选项rangearray

供用户进行选择的选项列表

示例:[ { "label": "选项名称", "value": "选项值" } ]

选项tipBlockstring
选项筛选wherearray

默认值:[]

选中值valuestring

示例:""

选项展示字段selectFieldTypestring

PC/H5端生效

默认展示主列字段

默认值:"primary"

自定义选择展示字段selectFieldsarray
占位文字placeholderstring

示例:"请选择"

搜索框占位文字searchPlaceholderstring

PC/H5端生效

示例:"搜索选项"

PC端组件尺寸sizestring

尺寸配置仅对PC端生效,表单场景下默认会跟随表单容器的组件尺寸配置

刷新按钮enableRelationalRefreshboolean

点击刷新下拉列表数据。仅选项来自关联关系字段时,支持配置刷新按钮,在编辑状态下展示。

默认值:true

设置按钮enableRelationalSettingboolean

开启后响应事件为:onSettingButtonClick。

仅选项来自关联关系字段时,支持配置设置按钮,在编辑状态下展示。

下拉选项跳转按钮enableRelationOptionJumpboolean

开启后响应事件为:onRelationOptionJump。

仅选项来自关联关系字段时,支持配置下拉选项跳转按钮,在编辑状态下展示。

新建按钮enableAddRelationButtonboolean

开启后响应事件为:onAddRelationButtonClick。

仅选项来自关联关系字段时,支持配置新建按钮,在编辑状态下展示。

新建按钮文案addRelationButtonTextstring

默认值:"去新建"

标签展示enableRelationTagboolean

开启后响应事件为:onRelationTagClick。

仅选项来自关联关系字段时,支持配置组件在只读状态下以标签形式展示。

默认值:true

事件

组件暴露的事件,可以监听组件的事件来触发一些外部的动作

事件名
事件code
事件出参 event.detail
适用情况
说明
值改变changeobject
  • value: string

    选中值

  • context: object

    此次变更的更多上下文信息,其中 context.option 可以获得选中项的内容

    • option: object

      选中项

    兼容三端

    用户修改组件值时触发

    输入搜索内容searchobject
    • value: string搜索框输入值
    兼容三端

    -

    点击设置按钮onSettingButtonClick兼容三端

    -

    点击新建按钮onAddRelationButtonClick兼容三端

    -

    点击标签onRelationTagClickobject
    • item: object 选项值
      • label: string
      • value: string
    移动端,PC端

    -

    点击自定义关联关系下拉选项跳转onRelationOptionJumpobject
    • item: object 选项值
      • label: string
      • value: string
    移动端,PC端

    -

    属性 API

    通过属性 API,可以获取组件内部的状态和属性值,可以通过$w.componentId.propertyName 来访问组件内部的值,如 $w.input1.value ,详请请参考 属性 API

    只读属性名
    属性标识
    类型
    说明
    绑定字段namestring

    表单字段的Key值,用于提交数据时,匹配数据模型字段标识。表单内需保证唯一。

    标题内容labelstring
    选中值valuestring
    必填requiredboolean
    是否展示visibleboolean

    组件是否展示

    是否禁用disabledboolean

    组件是否禁用

    是否只读readOnlyboolean

    组件是否只读

    选中项名称selectedLabelstring

    选中项对应的文本名称

    选中项itemobject

    选中项对应的对象

    方法 API

    通过方法 API,可以通过程序触发组件内部的方法,比如提交表单,显示弹窗等, 可以通过$w.componentId.methodName来调用组件方法,如 $w.form1.submit()

    方法名
    方法标识
    参数
    方法说明
    设置值setValuestring

    通过 $w.id1.setValue("weda") 设置组件值

    设置显隐setVisibleboolean显示

    通过 $w.id1.setVisible(false) 设置组件为隐藏

    设置禁用setDisabledboolean禁用

    通过 $w.id1.setDisabled(true) 设置组件为禁用

    清空值clearValue

    通过 $w.id1.clearValue() 清空组件值

    设置只读setReadOnlyboolean只读

    通过 $w.id1.setReadOnly(true) 设置组件为只读

    触发校验handleValidate

    通过 $w.id1.handleValidate() 校验组件值

    清除校验clearValidate

    通过 $w.id1.clearValidate() 清除组件校验

    样式 API

    通过样式 API,可以覆盖组件中内部元素的样式来实现自定义,例如在低代码编辑器中中通过 #wd-page-root .wd-btn 即可为所有的按钮组件编写样式,通过 :scope 可以控制单个组件样式, 详细说明请参考样式 API

    名称
    类名
    说明和示例
    根元素.wd-select-root组件最外层元素
    /* :scope 指的是当前组件元素 */
    /* 具体可参考样式 API 文档 */
    :scope.wd-select-root {
      /* 在这里编写CSS 样式 */
    }
    H5 端根元素.wd-h5-select-root可设定 H5 端的根元素样式
    /* :scope 指的是当前组件元素 */
    /* 具体可参考样式 API 文档 */
    :scope.wd-h5-select-root {
      /* 在这里编写CSS 样式 */
    }
    PC 端根元素.wd-pc-select-root可设定 PC 端的根元素样式
    /* :scope 指的是当前组件元素 */
    /* 具体可参考样式 API 文档 */
    :scope.wd-pc-select-root {
      /* 在这里编写CSS 样式 */
    }
    小程序端根元素.wd-mp-select-root可设定小程序端的根元素样式
    /* :scope 指的是当前组件元素 */
    /* 具体可参考样式 API 文档 */
    :scope.wd-mp-select-root {
      /* 在这里编写CSS 样式 */
    }
    组件标题样式.wd-select-root .wd-form-item-wrap__label组件标题元素
    
    :scope .wd-form-item-wrap__label {
      font-size: 20px;
      color: gray;
      padding: 0;
      display: flex;
      align-items: center;
    }
    
    表单控件根节点样式.wd-select-root .wd-form-item-wrap__control设置表单控件根元素样式
    
    :scope .wd-form-item-wrap__control {
      font-size: 20px;
      color: gray;
      padding: 0;
      display: flex;
      align-items: center;
    }
    
    编辑态-选择框样式.wd-select-root .wd-form-input-wrap组件边框、边距样式、背景色、字体大小、字体颜色等
    
    :scope .wd-form-input-wrap {
      font-size: 20px;
      color: gray;
      text-align: right;
      height: 40px;
      width: 100%;
      background-color: lightgray;
      border-width: 2px;
      border-color: gray;
      border-radius: 0px;
    }
    
    编辑态-选择框样式(获取焦点).wd-select-root .wd-form-input-wrap.is-focused编辑态-选择框样式(获取焦点)
    
    :scope .wd-form-input-wrap.is-focused {
      background-color: lightgray;
      border-color: gray;
    }
    
    编辑态-占位文字样式.wd-select-root .wedatea2td-dropdown__value > span, .wd-select-root input::placeholder, .wd-select-root .weui-input__placeholder设置占位文字样式
    
        :scope .wedatea2td-dropdown__value > span, :scope input::placeholder, :scope .weui-input__placeholder {
          color: lightgray !important;
        }
        
    编辑态-校验信息.wd-select-root .wd-g-text-error设置组件校验信息样式
    
    :scope .wd-g-text-error {
        font-size: 20px;
        color: gray;
      }
    
    提示文字.wd-select-root .wd-form-item__help-text设置组件提示文字样式
    
    :scope .wd-form-item__help-text {
        font-size: 20px;
        color: gray;
      }
    
    禁用态-选择框样式.wd-select-root .wd-form-input-wrap.is-disabled组件禁用样式
    
    :scope .wd-form-input-wrap.is-disabled {
        font-size: 20px;
        color: gray;
        text-align: right;
        height: 40px;
        width: 200px;
        background-color: lightgray;
        border-width: 2px;
        border-color: gray;
        border-radius: 10px;
      }
    
    只读态-表单值样式.wd-select-root .wd-form-item__readonly-value设置组件只读状态
    
    :scope .wd-form-item__readonly-value {
        font-size: 20px;
        color: gray;
      }
    
    前缀文字样式.wd-select-root .wd-form-input-group__addon-left设置组件前缀文字样式
    
    :scope .wd-form-input-group__addon-left {
        font-size: 20px;
        color: gray;
        height: 40px;
        background-color: lightgray;
      }
    /* 仅PC端生效 */
    :scope.wd-pc-select-root .wd-form-input-group__addon-left {
        border-width: 2px;
        border-color: gray;
        border-radius: 10px 0 0 10px;
    }
    
    后缀文字样式.wd-select-root .wd-form-input-group__addon-right设置组件后缀文字样式
    
    :scope .wd-form-input-group__addon-right {
        font-size: 20px;
        color: gray;
        height: 40px;
        background-color: lightgray;
      }
    /* 仅PC端生效 */
    :scope.wd-pc-select-root .wd-form-input-group__addon-right {
        border-width: 2px;
        border-color: gray;
        border-radius: 10px 0 0 10px;
    }
    

    了解样式 API

    版本变化

    • 属性变化
    • 样式变化
    • widget api 变化