基本使用

表单由若干表单项（l-form-item）和表单项下的输入组件构成，每一个表单项代表一个字段，由name属性指定字段名称，支持链式路径（如a.b.c, d[0]）和数组（['a', 'b', 'c']）

l-form-item下放置输入组件，目前仅支持内部的输入组件。只要表单项设置了name，输入组件的值将由表单管控，无需手动设置。部分属性既在表单项存在也在输入组件上存在，如type, min, max等等，可以直接在表单项上设置，无需在输入组件上重复设置

表单由useForm产生的实例进行管控，该实例可被多个表单共享，其用于方便管理表单的数据、状态、方法以及事件。如果不指定instance，那么内部会创建一个

实例的属性和方法都会暴露到组件 DOM 节点本身，ts 类型过长暂不列出，你可以在控制台选中节点，通过dir($0)查看有哪些属性和方法

注

React 中推荐使用useReactForm，通过renderOnUpdate选项，使得在React中渲染 data 和 formState 也可以响应式更新

表单布局

l-form的以下属性影响布局，它们均支持响应式断点：

• cols: 指定表单列数
• layout: 指定表单布局，可以为grid, inline-grid, flex, inline-flex，默认为 grid。grid 布局的好处在于 label 能够更容易对齐，且能带来更强大的布局控制
• labelWidth: 标签宽度，当为 grid 布局时，它会赋给 grid-template-columns，当为 flex 布局时，它会赋给 flex-basis。默认 grid 布局时为 max-content，这意味着标签总能完整展示，而且能同一列的标签取最大宽度，使得表单整体对齐，不用手动给某列每个元素设置 labelWidth
• labelLayout: 设置表单标签的布局，可选值有：
  • vertical：标签在输入元素的上方
  • horizontal：标签与输入元素在同一行
  • none：不显示标签相关内容（包括 label，requiredMark，colon 等等）

l-form-item的以下属性影响布局，首先列出grid 布局下可使用的属性

• labelWidth: 标签宽度，其为响应式断点属性
• colSpan: 指定字段占据的列数
• rowSpan: 指定字段占据的行数
• newLine: 字段换行展示
• endLine: 字段置于当前行末尾
• fullLine: 字段换行并占据一整行，比 colSpan 优先级更高
• preferSubgrid: 当浏览器支持时，优先使用CSS Subgrid实现上面的特性，仅在labelLayout为horizontal的时候有区别

当为 flex 布局时，上面的属性仅labelWidth, colSpan和fullLine可以使用

注

若浏览器不支持 subgrid 或 preferSubgrid为 false 时，则会使用 display: contents，将 label 和 content 视为单独的两列来兼容实现上面的布局，但是有些特性我找不到合适的方法完美兼容。

以下面的 label3 为例，其 colSpan 为 2，当标签布局为 horizontal 时，若支持 subgrid，这一行放不下，其应该在下一行，但是不使用 subgrid 时，它的 label 和 input 被拆开成两行来。这种情况可以手动为该字段添加newLine来避免，或者使用非horizontal标签布局

不管何种布局，谨慎往表单下添加其他内容或包裹什么元素，这会直接影响表单项的布局

公共属性与默认插槽

通过itemProps可以给表单下所有的l-form-item设置公共属性，itemProps还可以为函数以便于动态设置

type itemProps =
  | Partial<Omit<FormItemSetupProps, 'deps'>>
  | ((params: {
      formContext: CollectorContext<FormSetupProps, FormItemSetupProps, FormProvideExtra> | undefined;
      formItemProps: FormItemSetupProps;
    }) => Partial<Omit<FormItemSetupProps, 'deps'>>);

l-form-item的默认插槽用于放置输入组件，只要配置了name属性，其下的输入组件便可以自动获取和设置表单的值（表单支持的组件可见左侧菜单“输入组件”）

另外，l-form-item也可以通过element属性和elementProps属性直接设置其下渲染的组件，其中elementProps也可以设置为函数。如果设置了element，l-form-item的默认插槽下的内容便会渲染到输入组件的默认插槽下

type elementProps =
  | object
  | ((param: {
      formContext: CollectorContext<FormProps, FormItemProps, FormProvideExtra> | undefined;
      formItemProps: FormItemSetupProps;
    }) => any);

动态的公共属性某些时候会非常有用，能够减少很多重复的设置，而单个字段也可由自己的属性覆盖，可以看下面的示例查看效果

所有表单组件

注

数组字段必须在l-form-item上设置array属性，其下的输入元素需要自行渲染，不可通过element属性设置，输入元素无需自行更新和设置 value，其会根据 dom 顺序确定在数组中的 index 并取值或更新

依赖字段

l-form-item可通过deps属性可设置该字段依赖的其他字段，其值为其他字段的 name 字符串或 name 数组。当其依赖字段的值发生变化后，可自动控制该字段清除、禁用、必输、校验，具体可通过以下属性进行控制

• clearWhenDepChange: 当其为true时，依赖字段的值变化后，本字段值清空

• disableWhenDep: 控制当依赖的字段值什么情况下本字段变为禁用，必须要有依赖的字段本属性才会生效，可选值有：

  • all-truthy: 当依赖的所有字段值均为 truthy 时，本字段禁用
  • some-truthy: 当依赖的所有字段值中有任一为 truthy，本字段禁用
  • all-falsy: 当依赖的所有字段值均为 falsy 时，本字段禁用
  • some-falsy: 当依赖的所有字段值中有任一为 falsy，本字段禁用

  可以为数组，数组设置多个值，必须全部满足。目前这些条件适合设成数组的只有['some-truthy', 'some-falsy']，意味着必须同时存在真值和假值

• requireWhenDep: 控制当依赖的字段值什么情况下本字段变成必选，可选值与disableWhenDep相同

• validateWhen、revalidateWhen: 校验的时机中有可选值depChange，当依赖值变化后触发校验

校验

• 部分校验属性与输入组件也有关（如type, min, max, step, precision），它们可以直接在l-form-item上设置，其下的输入组件会自动继承，无需额外设置
• 设置数字的校验属性也可以设置为其他字段的值，可以这样设置的属性有min, max, step, precision, moreThan, lessThan, len

说明

下例中的字段“已使用”，其 max="total"，意味着如果“总量”字段有值且为数字的时候，它的 max 取值则为“总量”的值，另外，下面所有的数字字段 step 和 precision 属性都直接设为了“布长”和“精度”字段的值