HTML Academy · 课时

约束验证 API 基础

Q: 「约束验证 API 基础」这节课中我会学到什么？

使用约束验证 API 读取有效性状态并设置自定义消息 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用约束验证 API 读取有效性状态并设置自定义消息

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

什么是约束验证 API

约束验证 API 是一个用于读取和设置表单验证状态的 JavaScript 接口：

检查字段是否有效
读取具体哪个约束验证失败
设置自定义错误消息
以编程方式触发浏览器验证界面

validity 属性

每个表单控件都有一个包含特定布尔标志的 validity 对象：

const input = document.getElementById('email');
const v = input.validity;

console.log(v.valid);         // true if all constraints pass
console.log(v.valueMissing);  // true if required but empty
console.log(v.typeMismatch);  // true if type doesn't match (e.g. bad email)
console.log(v.patternMismatch); // true if pattern fails
console.log(v.tooShort);      // true if shorter than minlength
console.log(v.tooLong);       // true if longer than maxlength
console.log(v.rangeUnderflow); // true if less than min
console.log(v.rangeOverflow);  // true if more than max

checkValidity 方法

checkValidity() 返回 true/false，并触发 invalid 事件：

const form = document.getElementById('my-form');

// Check entire form:
if (!form.checkValidity()) {
  console.log('Form has errors');
}

// Check individual field:
const email = document.getElementById('email');
if (!email.checkValidity()) {
  console.log('Email is invalid');
}
// The 'invalid' event fires on invalid fields

reportValidity 方法

reportValidity() 会显示浏览器原生的验证界面：

const input = document.getElementById('username');

// Shows native browser error tooltip if invalid:
const valid = input.reportValidity();
console.log(valid);  // true or false

// On a form: validates all fields and shows first error:
document.getElementById('form').reportValidity();

validationMessage 属性

validationMessage 返回浏览器的错误消息字符串：

const email = document.querySelector('input[type=email]');
email.value = 'not-an-email';

console.log(email.validationMessage);
// e.g. "Please include an '@' in the email address..."

console.log(email.validity.typeMismatch); // true

setCustomValidity

setCustomValidity(message) 设置自定义验证错误：

const username = document.getElementById('username');

// Check availability on blur:
username.addEventListener('blur', async () => {
  const res = await fetch(`/check-username?name=${username.value}`);
  const { taken } = await res.json();

  if (taken) {
    username.setCustomValidity('This username is already taken.');
  } else {
    username.setCustomValidity('');  // empty string = clear the error
  }
});

清除自定义有效性

用户修复问题后，必须清除自定义有效性：

const input = document.getElementById('username');

input.addEventListener('input', () => {
  // Clear custom error when user starts typing again:
  input.setCustomValidity('');
});

input.addEventListener('blur', async () => {
  // Re-validate on blur:
  const taken = await checkUsername(input.value);
  input.setCustomValidity(taken ? 'Username taken' : '');
});

invalid 事件

验证失败的表单控件会触发 invalid 事件：

document.querySelectorAll('input').forEach(input => {
  input.addEventListener('invalid', (e) => {
    e.preventDefault();  // prevent default browser tooltip
    // Show your custom error UI instead:
    showError(input, input.validationMessage);
  });
});

will-validate 属性

如果元素参与约束验证，willValidate 就为 true：

document.querySelectorAll(':input').forEach(el => {
  if (el.willValidate) {
    console.log(el.name, 'will be validated');
  }
});
// Disabled, hidden, or output elements return willValidate = false

在自定义验证中使用 Validity

完整的自定义验证示例：

<form id="signup" novalidate>
  <input type="email" id="email" name="email" required>
  <span id="email-err" role="alert"></span>
  <button type="submit">Sign Up</button>
</form>

<script>
const form = document.getElementById('signup');
const email = document.getElementById('email');
const err = document.getElementById('email-err');

form.addEventListener('submit', (e) => {
  e.preventDefault();
  err.textContent = '';

  if (email.validity.valueMissing) {
    err.textContent = 'Email is required.';
    email.focus();
    return;
  }
  if (email.validity.typeMismatch) {
    err.textContent = 'Enter a valid email address.';
    email.focus();
    return;
  }
  // Submit...
});
</script>

ValidityState 标志总结

所有 ValidityState 标志：

valueMissing — 必填但为空
typeMismatch — 类型格式错误
patternMismatch — 模式正则表达式匹配失败
tooShort / tooLong — minlength/maxlength
rangeUnderflow / rangeOverflow — min/max
stepMismatch — 不是有效的步长值
customError — 已设置 setCustomValidity 消息
badInput — 浏览器无法解析该值

快速检查

如何以编程方式显示浏览器原生的验证错误弹窗？

回顾：约束验证 API

约束验证 API 要点：

input.validity — 包含特定标志的 ValidityState 对象
checkValidity() — 返回 true/false，并触发 invalid 事件
reportValidity() — 检查并显示原生错误界面
validationMessage — 浏览器的错误字符串
setCustomValidity(msg) — 设置自定义错误；使用空字符串清除错误

常见问题解答

「约束验证 API 基础」课时是免费的吗？

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

「约束验证 API 基础」这节课中我会学到什么？

使用约束验证 API 读取有效性状态并设置自定义消息你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

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

「约束验证 API 基础」课时需要多长时间？

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

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

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

此课程中的所有课时

← 返回 HTML Academy