spz-form 表单

何时使用

用于收集信息。
需要对输入的数据进行校验时。

组件是如何判断表单是spz-form？

表单的用法和原生的form一样，都是直接用<form>标签而不是<spz-form>标签，组件会根据<form>标签是否带有以下两个标识中的一个来判断是否将当前表单作为spz-form：

带有 is="spz-form" 属性
带有 action-xhr 属性

代码演示

基本用法

最基本的用法，在表单内控件的使用与原生的 form 表单用法一致。

<form
    action-xhr="/api/customers/sign_in"
    method="POST"
    custom-validation="change-interact-and-first-submit"
    back-to-referrer
    record-referrer
    @submitError="..."
  >
    <div class='form_item'>
      <input
        id="email"
        type="text"
        name="email"
        autofocus
        required
        pattern="[a-zA-Z0-9!#$%&'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?"
      >
      <label for="email">Email</label>
    </div>
    <div class='form_item'>
      <input
        id="password"
        type="password"
        name="password"
        required
        minlength="6"
        maxlength="16"
        pattern='[\s\S]{6,16}'
      >
      <label for="password">Password</label>
    </div>

    <button type="submit">Login</button>
  </form>

错误信息

展示错误信息。当报告表单有错误信息时，会去找带有 validation-for 和 visible-when-invalid 属性的元素，且 validation-for 的值与控件的ID一致，visible-when-invalid 的值与无效的校验状态一致时，会移除当前元素的 hidden 属性，并加上 visible 类。

校验状态

状态	描述
valueMismatch	如果控件有`required`属性，且值为空时
patternMismatch	如果控件有`pattern`属性，当用户输入的值与不符合`pattern`属性的约束条件时

<form
  action-xhr="/api/customers/sign_in"
  method="POST"
  custom-validation="change-interact-and-first-submit"
  back-to-referrer
  record-referrer
  @submitError="..."
>
  <div class='form_item'>
    <input
      id="email"
      type="text"
      name="email"
      autofocus
      required
      pattern="[a-zA-Z0-9!#$%&'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?"
    >
    <label for="email">Email</label>

    <div validation-for="email" visible-when-invalid="valueMissing" hidden>Email is required</div>
    <div validation-for="email" visible-when-invalid="patternMismatch" hidden>Please enter a valid email.</div>
  </div>
  <div class='form_item'>
    <input
      id="password"
      type="password"
      name="password"
      required
      minlength="6"
      maxlength="16"
      pattern='[\s\S]{6,16}'
    >
    <label for="password">Password</label>
    <div validation-for="password" visible-when-invalid="valueMissing" hidden>Password is required.</div>
    <div validation-for="password" visible-when-invalid="patternMismatch" hidden>Password must be between 6-16 characters long.</div>
  </div>

  <button type="submit">Login</button>
</form>

属性

属性名	说明	类型	默认值	是否必需
is	标注表单为spz表单，当不存在`action-xhr`属性时必需, 可选值`spz-form`	string	-	否
action-xhr	处理表单提交的URL	string	-	否
initial-xhr	初始化表单数据的URL。当表单内的元素控件的 `name` 值与返回的数据 `key` 一致时可以初始化该控件的默认值	string	-	否
items	获取初始化表单数据对象的路径	string	`.`	否
method	使用HTTP方式来提交表单，可选：`GET` \| `POST` \| `PATCH` \| `DELETE`	string	`GET`	否
content-type	设置请求headers里面`Content-Type`字段的值，可选值：`application/json`\|`application/x-www-form-urlencoded`	string	`application/x-www-form-urlencoded`	否
custom-validation	表单校验类型，可选：`show-all-on-submit` \| `show-first-on-submit` \| `input-interact-and-submit` \| `change-interact-and-submit` \| `change-interact-and-first-submit`	string	`input-interact-and-submit`	否
confirm-before-submit	在点击提交按钮且提交表单前，弹出一个带有该属性值文案的对话框，当用户点击确认按钮时，提交表单	string	-	否
refresh-when-submit-success	如果该属性存在，当表单提交成功时刷新页面	-	-	-
redirect-when-submit-success	当表单提交成功时，跳转到指定的路径	string	-	否
back-to-referrer	如果该属性存在且没有配置`redirect-when-submit-success`属性时，当表单提交成功时，会跳转到上一次访问的页面	-	-	-
record-referrer	如果该属性存在，会将 `document.referrer` 的值写入 `localStorage` 的 `__REFER_FROM` 字段值中	-	-	-
novalidate	如果该属性存在，不会校验表单数据的有效性	-	-	-
initial	当正在初始化表单数据时，根元素会自动添加该属性	-	-	-
initial-success	当初始化表单数据成功时，根元素会自动添加该属性	-	-	-
initial-error	当初始化表单数据失败时，根元素会自动添加该属性	-	-	-
submitting	当正在提交表单时，根元素会自动添加该属性	-	-	-
submit-success	当表单提交成功时，根元素会自动添加该属性	-	-	-
submit-error	当表单提交失败时，根元素会自动添加该属性	-	-	-
has-value	当控件的值不为空时，控件会自动加入这个属性	-	-	-

initial-xhr 支持类型

类型	描述
API	接口API
`script:<scriptId>`	`application/json` 类型的脚本数据

custom-validation 可选值

show-all-on-submit

在点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告所有校验不符合的信息。当控件的值校验不符合后，用户输入/选择符合的值后，控件会被报告有效。

show-first-on-submit

在点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告第一个校验不符合的信息。当控件的值校验不符合后，用户输入/选择符合的值后，控件会被报告有效。

input-interact-and-submit

当用户正在输入时，会实时去校验当前控件的值是否有效。如果无效，实时报告校验不符合的信息。
当点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告所有校验不符合的信息。

change-interact-and-submit

当用户输入完成后，会去校验当前控制的值是否有效。如果无效，报告校验不符合的信息。
当点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告所有校验不符合的信息。

change-interact-and-first-submit

当用户输入完成后，会去校验当前控制的值是否有效。如果无效，报告校验不符合的信息。
当点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告第一个校验不符合的信息。

current-input-interact-and-first-submit

当用户正在输入时，会实时去校验当前控件的值是否有效。如果无效，实时报告校验不符合的信息。
当点击提交表单按钮后请求接口前，会去校验所有控件的值是否有效，如果有校验不符合的，报告第一个校验不符合的信息。

方法

init

重新初始化表单默认数据。

参数名	说明	类型	是否必需
initialXhr	修改 `initial-xhr` 属性并且重新初始化表单默认数据	string	是
actionXhr	修改 `action-xhr` 属性	string	否

submit

提交表单。

参数名	说明	类型	是否必需
actionXhr	修改 `action-xhr` 属性	string	否

clear

将表单中的所有输入重置为其初始值，不需要参数。

insert

更新某个表单控件的值。

参数名	说明	类型	是否必需
name	控件名称	string	是
value	控件值	string \| number	是

focus

给表单的第一个带有 autofocus 属性的元素获得焦点，不需要参数。

check

重新校验表单，不需要参数。

事件

submitSuccess

当表单提交成功时该事件会自动触发。event 对象数据为 action-xhr 配置的URL接口返回的数据。

submitError

当表单提交失败时该事件会自动触发。event 对象数据为 action-xhr 配置的URL接口返回的数据。

valid

当表单校验有效时该事件会自动触发。

invalid

当表单校验无效时该事件会自动触发。

AI 摘要（LLM Ready）

组件标识：spz-form
用途一句话：表单组件，包含数据录入、校验。
可识别属性条目：22
可识别方法小节：6
可识别事件小节：4
关键属性名（Top）：is、action-xhr、initial-xhr、items、method、content-type
关键方法名（Top）：init、submit、clear、insert、focus、check
关键事件名（Top）：submitSuccess、submitError、valid、invalid
阅读顺序建议：先看「何时使用」与「代码演示」，再核对属性/方法/事件。
关联文档：/guide/actions-and-events/ 、/guide/layouts/

spz-form 表单#

#何时使用

#组件是如何判断表单是spz-form？

#代码演示

#基本用法

#错误信息

#属性

#initial-xhr 支持类型

#custom-validation 可选值

#方法

#init

#submit

#clear

#insert

#focus

#check

#事件