跳到主要内容
版本: 5.1

Subform 表单字段

TODO:: 重写 Jquery 和示例以使用 WebAssets。

子表单 表单字段类型提供了一种在 XML 表单内使用 XML 表单或在现有表单内重复使用表单的方法。如果属性 multiple 设置为 true，则包含的表单将是可重复的。

该字段有两个“预定义”布局，用于将子表单显示为表格或 div 容器，以及对自定义布局的支持。

  • type（必需）必须为subform。

  • name（必需）是字段的唯一名称。

  • label（必需）（可翻译）是字段的 HTML 标签。

  • formsource（必需）要包含的表单源。指向 xml 文件的相对路径（相对于已安装的 Joomla 站点根目录）或有效的表单名称，可以通过 Factory::getContainer()->get(FormFactoryInterface::class)->createForm($name, $options); 找到。

  • description（可选）（可翻译）是字段描述。

  • default（可选）是默认值，一个 JSON 字符串。

  • required（可选）提交表单之前必须填写该字段。

  • message（可选）将显示的错误消息，而不是默认消息。

  • multiple（可选）子表单字段是否可重复。

  • min（可选）多重模式下最小重复次数。默认值：0。

  • max（可选）多重模式下最大重复次数。默认值：1000。

  • groupByFieldset（可选）是否按其字段集对子表单字段进行分组（true 或 false）。默认值：false。

  • buttons（可选）在多重模式下显示哪些按钮。默认值：add,remove,move。

  • layout（可选）显示子表单字段时使用的布局的名称。
    可用布局

    joomla.form.field.subform.default - 在 div 容器中呈现子表单，不支持重复。单一模式的默认值。
    joomla.form.field.subform.repeatable - 在 div 容器中呈现子表单，用于多重模式。支持 groupByFieldset。
    joomla.form.field.subform.repeatable-table - 将子表单呈现为表格，用于多重模式。支持 groupByFieldset。默认情况下，每个字段都以表格列的形式呈现，但如果 groupByFieldset=true，则每个字段集都以表格列的形式呈现。

  • validate（可选）应设置为“Subform”（注意，区分大小写！）以确保子表单中的字段得到单独验证。默认值：即使指定了验证规则，子表单中的字段也不会被验证。

实现于：libraries/src/Form/SubformField.php

单一模式的示例 XML 参数定义：​

<field 
        name="field-name" 
        type="subform"
        formsource="path/to/exampleform.xml"
        label="Subform Field" 
        description="Subform Field Description" 
/>

多重模式的示例 XML 参数定义：​

<field 
        name="field-name" 
        type="subform"
        formsource="path/to/exampleform.xml" 
        multiple="true"
        label="Subform Field" 
        description="Subform Field Description" />

exampleform.xml 的示例 XML

<form>
    <field name="example_text" type="text" label="Example Text" />
    <field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</form>

带有字段集的 exampleform.xml 的示例 XML

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <fieldset name="section1" label="Section1">
        <field name="example_text" type="text" label="Example Text" />
        <field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
    </fieldset>
    <fieldset name="section2" label="Section2">
        <field name="example_list" type="list" default="1" class="advancedSelect" label="Example List">
            <option value="1">JYES</option>
            <option value="0">JNO</option>
        </field>
    </fieldset>
</form>

子表单 XML 也可以内联指定，作为将子表单 XML 放置在单独文件中的一种替代方案。以下示例说明了这一点

<?xml version="1.0" encoding="UTF-8"?>
<field
        name="field-name"
        type="subform"
        label="Subform Field"
        description="Subform Field Description"
        multiple="true"
        min="1"
        max="10"
>
    <form>
        <field
                name="example_text"
                type="text"
                label="Example Text"
        />
        <field
                name="example_textarea"
                type="textarea"
                label="Example Textarea"
                cols="40"
                rows="8"
        />
    </form>
</field>

示例 XML 参数定义​

以下表单允许上传最多 8 个图像文件

 <field
        name="mysubform-addingimages"
        type="subform"
        label="Add Images"
        description=""
        multiple="true"
        min="0"
        max="8"
>
  <form>
    <field
            name="image_file"
            type="file"
            class="file"
            accept="image/*"
    />
  </form>
</field>

Javascript​

如果子表单中的字段具有相关的 JavaScript 逻辑，则可能需要考虑如何在multiple="true" 模式下使之工作，因为子表单字段是动态添加的。

为了处理这个问题，您可以捕获“joomla:updated' 事件，该事件在动态添加子表单时触发

document.addEventListener('joomla:updated', (event) => {
  const updatedElement = event.target;
  /*... your code here to process fields in the new row ("updatedElement") ...*/
});

如果您在子表单的字段中设置了 javascript 验证（由 class="validate-xxx" 设置），则当焦点离开字段时，此验证不会触发，但验证会在表单提交之前运行。

这也适用于扩展 SubformField 的自定义字段。

服务器端验证和过滤器​

服务器端验证和过滤器按正常方式应用于子表单的字段，与这些字段不属于子表单时的方式相同。

这也适用于扩展 SubformField 的自定义字段。