HTML Academy · 课时

reportValidity 与 setCustomValidity

Q: 「reportValidity 与 setCustomValidity」这节课中我会学到什么？

触发浏览器验证界面并设置自定义错误消息 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

触发浏览器验证界面并设置自定义错误消息

reportValidity 与 setCustomValidity 是 CoddyKit 上的免费 HTML Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

用于内置用户体验的两个接口

约束验证接口提供了两个可以驱动浏览器内置验证界面的方法：reportValidity（显示提示框）和 setCustomValidity（提供自定义错误消息）。二者结合使用，可以自定义消息，同时保留原生显示方式。

reportValidity 与 checkValidity

checkValidity() 会静默返回 true 或 false，不会产生界面副作用。reportValidity() 会执行相同的检查，但还会将焦点置于第一个无效字段，并显示浏览器的验证提示框。希望免费获得原生用户体验时，请选择 reportValidity。

document.forms.signup.addEventListener("submit", (e) => {
  if (!e.target.reportValidity()) {
    e.preventDefault();
    // browser already focused first invalid field and showed tooltip
  }
});

程序化验证

对于多步骤流程，请在进入下一步之前验证当前步骤中的每个字段：if (step.reportValidity()) { next(); }。浏览器会处理错误显示，并将焦点置于需要注意的字段，从而省去重新实现焦点管理的工作。

setCustomValidity 覆盖消息

默认消息（“请填写此字段”）可能与您的语气不一致。input.setCustomValidity("Username is required") 会用您提供的文本替换默认消息。在清除该消息之前，输入控件都会被视为无效。

清除自定义消息

input.setCustomValidity("") 会移除自定义消息，并重新启用正常验证。每次重新验证时都应调用它，否则即使用户已经修复问题，过时的自定义消息仍会保留。

input.addEventListener("input", () => {
  if (input.value.length < 3) {
    input.setCustomValidity("Must be at least 3 characters");
  } else {
    input.setCustomValidity("");
  }
});

异步验证

对于服务端检查（例如用户名是否唯一、优惠券是否有效），请在异步响应后使用 setCustomValidity：const ok = await checkUsername(value); input.setCustomValidity(ok ? "" : "Already taken");。浏览器会立即获取新的有效性状态。

结合自定义错误界面

如果希望使用自己的错误显示，同时保留有效性跟踪，请监听 invalid 事件并调用 e.preventDefault() 来禁止原生提示框：input.addEventListener("invalid", (e) => { e.preventDefault(); showError(input, input.validationMessage); })。

多个自定义约束

setCustomValidity 一次只能支持一条自定义消息。若要强制执行多条规则，请逐一检查，并按照优先级顺序使用 setCustomValidity 设置最相关的消息。显示的是第一条失败规则对应的消息。

不要与内置验证重叠

如果为一个空的必填字段设置自定义消息，您的消息可能会与默认消息冲突。每个字段请选择一种方式：要么禁用内置约束（使用 type="text" 而不是 type="email"，并通过 setCustomValidity 进行验证），要么完全信任内置验证。

表单级自定义验证

对于跨字段验证（例如确认密码是否匹配），请将 setCustomValidity 应用于相关字段：confirmInput.setCustomValidity(confirmInput.value === passInput.value ? "" : "Passwords do not match")。只有两者匹配时，表单才有效。

国际化

内置消息会根据用户语言由浏览器进行本地化。通过 setCustomValidity 设置的自定义消息必须由您自行使用正确的语言编写——读取 navigator.language 或您自己的国际化状态，并提供相应的翻译。

测试

打开 DevTools，尝试每条无效路径：提交空表单、输入不完整的内容、格式不匹配以及异步失败。确认显示了正确的消息，修复问题后消息会被清除，并且提交有效表单后能够继续。对于粘贴无效格式内容、浏览器自动填充等边界情况，应编写专门的测试。

知识检查

调用 input.setCustomValidity("Already taken") 后，如何告知浏览器该输入控件再次有效？

总结

reportValidity 会触发浏览器内置的验证界面（焦点和提示框），非常适合程序化检查。setCustomValidity 会用您的文本覆盖默认消息——再次有效时，请使用空字符串清除它。使用 preventDefault 监听 invalid 事件，即可完全自定义错误显示。它适用于跨字段验证、异步检查以及本地化的自定义消息。

常见问题解答

「reportValidity 与 setCustomValidity」课时是免费的吗？

是的 — 「reportValidity 与 setCustomValidity」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「reportValidity 与 setCustomValidity」这节课中我会学到什么？

触发浏览器验证界面并设置自定义错误消息你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「reportValidity 与 setCustomValidity」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy