跳到主要内容
支持地域：上海

表单容器

WdForm

实践指南​

适用场景​

快捷实现表单数据的提交与展示场景。绑定数据源后，可根据字段类型自动生成单行输入、下拉选择、提交按钮等组件

基础能力说明​

  1. 通过表单容器进行表单数据的新增、更新或查看
  2. 支持绑定数据模型或 APIs 类型的数据源，来实现前后端的数据交互
  3. 通过字段属性，可控制内部表单组件的排序、显隐，和切换字段映射的组件类型
  4. 更多实践说明，可查阅表单常见场景的实践指南

扩展场景说明​

在表单中对用户输入数据进行计算展示​

示例

下面是一个复杂的值计算场景

  • formArr1： 是一个数组，每一行的 c 值是 a，b 的和
  • formArr2： 是一个数组，每一行的 c 值是 a，b 的和
  • sum1： formArr1 的 c 值累加
  • sum2： formArr2 的 c 值累加

配置方法

  1. 如图拖入表单容器和嵌套组件，按需配置

    图片 9a2e1e3d99aa8e1ce1931589fa39569d

    嵌套组件中的 c 值为 a,b 的和表达式实现如下：

    Number($w.formArr1.value[$w.index_formArr1].a)*Number($w.formArr1.value[$w.index_formArr1].b)

  2. sum1 是数组 formArr1 的 c 值累加

    图片 e3461104a29516b7bfafb1ca54584416

    表达式实现如下：

    $w.form1.value?.formArr1?.reduce((sum, v) => sum +Number(v.c), 0)

  3. sum1+sum2

    图片 dd63df6118051e3652d2b38618a5a82c

    表达式实现如下：

    Number($w.form1.value.sum1)+Number($w.form1.value.sum2)

  4. sum1/sum2

    图片 a72ab48035b44579d8ff17f20f2be687

    表达式实现如下：

    Number($w.form1.value.sum1)/Number($w.form1.value.sum2)

使用 1 个表单容器组件动态实现数据新增、更新和查看场景​

示例

为表单容器的「表单场景」属性绑定变量，为变量赋不同值实现新增、更新和查看场景

配置方法

  1. 创建一个 string 类型的变量，命名为 sence

    图片 24db506c64fe53a88dab706c1d46c164

  2. 表单容器绑定一个所需数据模型，渲染生成表单组件，然后将表单容器的「表单场景」属性绑定该 sence 变量

    图片 fecb6f338bb78bc8311917fe30cc6a75

  3. 在不同业务下，为 sence 变量赋不同值，表单容器可实现不同作用

    1. 赋值 create→ 表单容器为新增场景，用于数据的新增提交
    2. 赋值 edit→ 表单容器为更新场景，用于已有数据的编辑更新
    3. 赋值 read→ 表单容器为查看场景，用户已有数据的回显查看

绑定表达式​

表达式可为静态数据、变量。您可通过 Query 连接内置数据表和外部 APIs 等，然后在表达式中选择 query 进行绑定。

数据源类型为 APIs 时，方法参数的格式要求（最新版本已下架）​

  1. 表单场景为「新增」时，需配置

    1. 新增方法：要求业务所需的表单字段平铺放在入参根节点中，例： 图片 8a176555dfbc0c8bbea16d2fcd1ece6e

  2. 表单场景为「更新」时，需配置

    1. 查询方法：要求表单字段平铺放在出参根节点中，例： 图片 bc60e088438a500031a936f83e81cf46
    2. 更新方法：要求业务所需的表单字段平铺放在入参根节点中，例： 图片 cc296a413d5be4b50f2f95dc8b69fe56

  3. 表单场景为「查看」时，需配置

    1. 查询方法：要求表单字段平铺放在出参根节点中，例： 图片 bc60e088438a500031a936f83e81cf46

属性​

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

属性名
属性标识
类型
说明
表单场景formTypestring

默认值："create"

数据源datasourceTypestring

默认值："model"

数据模型dataSourceNamestring

示例：""

字段管理fieldsarray
数据标识(_id)_idstring

示例：""

表单值valueobject

自动填充表单输入数据。每个键值都分配给具有匹配的表单数据键的输入。

查询方法methodGetItemstring

示例：""

查询入参paramGetItemobject

直接输入对象字面量, 如 {status: 1}

示例：{}

新增方法methodCreatestring

示例：""

更新方法methodUpdatestring

示例：""

PC端表单列数colNumstring

默认值："1"

PC端组件宽度lgWidthstring

尺寸配置仅对PC端生效

默认值："hundred"

示例："md"

标题位置layoutstring

设置当前容器内表单类组件的标题和输入选择区域为左右布局或上下布局

默认值："horizontal"

事件​

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

事件名
事件code
事件出参 event.detail
适用情况
说明
提交submit兼容三端

-

校验成功validateSuccessobject
  • errors: object 校验错误
    		兼容三端

    -

    校验失败validateFailobject
    • errors: object 校验错误
      		兼容三端

      -

      查询为空queryEmptyobject
      • data: object

        查询结果
        		兼容三端

        -

        查询成功querySuccessobject
        • data: object

          查询结果
          		兼容三端

          -

          查询失败queryFailobject
          • error: object 错误信息

            组件内部抛出的错误信息
            • requestid: string请求 id

              如果是接口相关错误会提供请求 id
            • message: string错误提示信息
            • code: string错误码
            • original: 原始错误
          		兼容三端

          -

          属性 API​

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

          只读属性名
          属性标识
          类型
          说明
          是否禁用提交isDisabledSubmitboolean

          表单是否禁用提交

          表单场景formTypestring
          数据模型dataSourceNamestring
          标题位置layoutstring

          设置当前容器内表单类组件的标题和输入选择区域为左右布局或上下布局

          错误信息errorsobject

          提交的校验错误信息对象

          数据源初始值remoteValueobject

          数据源初始化请求的初始值

          表单前端值valueobject

          当前前端表单状态值

          数据源类型信息dataSourceProfile

          数据源信息

          数据源方法提交入参submitParamsobject

          数据源方法提交入参, 绑定query的时候没有

          清除校验clearValidateobject

          清除校验

          方法 API​

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

          方法名
          方法标识
          参数
          方法说明
          设置值setValueobject
          • value: object 值

            表单的值

            通过 $w.form1.setValue({value:{a:'111'}}) 设置组件值

            提交submit

            通过 $w.<id>.submit() 触发表单提交

            置空clearValueobject
            • isImmediate: boolean是否开启防抖

            通过 $w.<id>.clearValue() 将表单置空

            清空校验clearValidate

            通过 $w.<id>.clearValidate() 清空校验

            校验validate

            通过 $w.<id>.validate() 触发表单提交

            禁用提交disableSubmit

            通过 $w.<id>.disableSubmit 设置禁用表单提交

            启用提交enableSubmit

            通过 $w.<id>.enableSubmit 设置启用表单提交

            样式 API​

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

            名称
            类名
            说明和示例
            根元素.wd-form表单组件根元素
            /* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-form {
  /* 在这里编写CSS 样式 */
}
            PC 端表单根元素.wd-pc-form可以为 PC 端的表单编写样式
            /* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-pc-form {
  /* 在这里编写CSS 样式 */
}
            H5 端表单根元素.wd-h5-form可以为 H5 端的表单编写样式
            /* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-h5-form {
  /* 在这里编写CSS 样式 */
}
            小程序端表单根元素.wd-mp-form可以为小程序端的表单编写样式
            /* :scope 指的是当前组件元素 */
/* 具体可参考样式 API 文档 */
:scope.wd-mp-form {
  /* 在这里编写CSS 样式 */
}

            了解样式 API

            常见问题​

            使用数据容器类组件，一定要将组件放在数据容器类组件内部么？​

            数据容器（Data Container）是页面与数据交互的核心组件，它能直接查询并展示数据。在我们的平台中，有多种数据容器组件可供选择，如数据列表（ListView）、数据详情（DataView）、表单容器（WdForm）以及数据表格（WdTable）。

            数据容器可实现数据与页面组件的深度整合。这大大简化了数据操作流程。除了提供数据，数据容器还支持常见的页面交互功能，例如分页加载、加载状态以及错误提示等。

            在使用数据容器时，若组件依赖于数据容器返回的数据，建议将组件置于数据容器类组件内部。例如，若要展示某条数据详情中的某个字段的图片，将组件放在相应的数据容器内部会更好。这样，数据容器可以自动处理加载中、加载失败等情况，无需关注渲染时机。

            如果只需使用数据容器获取数据，而无需进行 UI 交互，您可以直接使用 Query 功能来查询数据。

            如何防止表单重复提交？​

            在表单提交按钮上，可以创建一个布尔型的变量，默认为 false，绑定在按钮的禁用属性上。然后表单容器提交事件触发「变量赋值」，将这个变量置为 true，然后成功分支再调用数据源方法提交数据，提交成功后，再触发「变量赋值」，将这个变量再置为 false。这样提交过程中，变量值为 true，按钮会处于禁用状态，从而防止重复提交。

            如何在某个事件触发时刷新其他组件？​

            当需要在某个事件触发时刷新其他组件时，可以在目标组件的属性上绑定一个变量，例如筛选参数的表达式中引用这个变量。然后在触发事件中改变这个变量的值，从而重新更新对应的目标组件的内容。