HTML自定义元素扩展原生HTML API指南

浏览器对原生标签的保护远比想象中严格——直接重定义 button、canvas 这些标签，会被浏览器无情拒绝。那如果想给按钮加个加载状态、或者让自定义元素继承原生表单能力，该怎么办？唯一合法路径是用 { extends: "button" } 配合 is 属性。独立自定义元素虽然看起来更自由，但原生 API 一个都拿不到，事件、属性、表单能力全得手动桥接。

直接重定义 button、canvas 等原生标签会报错

尝试执行 customElements.define("button", ButtonClass) 时，浏览器会直接抛出错误：Failed to execute 'define' on 'CustomElementRegistry': "button" is not a valid custom element name。这并非兼容性问题，而是浏览器在解析阶段就将其拦截。所有已知的 HTML 标签名（如 button、input、canvas、table 等，大约 20 个）都被硬编码在拒绝名单中。即便尝试修改原型链或动态替换，最终生成的节点依然是 HTMLButtonElement 实例，自定义类根本不会被实例化。

扩展现有元素必须用 is 属性 + extends 配置

若想让 具备加载状态管理能力，唯一可行路径是组合使用 is 属性和 { extends: "button" }。遗漏任何一环，属性、方法、事件都会失效。以下细节必须严格遵循：

• class LoadingButton extends HTMLButtonElement —— 必须继承对应的内置类，不能只继承 HTMLElement。
• 构造函数第一行必须是 super()，否则会报 Failed to construct 'HTMLButtonElement'，且 this.value、this.disabled 等属性全部变为 undefined。
• customElements.define("loading-button", LoadingButton, { extends: "button" }) —— 其中 { extends: "button" } 不可省略。
• HTML 中只能写 Submit，写成 或 均无效。
• is 的值（如 "loading-button"）必须与 define() 的第一个参数完全一致，大小写和连字符都不能出错。

独立自定义元素无法自动继承原生 API

使用 虽然看起来更自由，但其本质是 HTMLElement 实例，不具备 click()、focus()、form 关联、value 属性等原生按钮能力。这些能力需要手动实现：

• 通过 attachShadow({ mode: "open" }) 封装内部的 ，再透传事件和属性。
• 不会自动设置内部 的 value，必须在 attributeChangedCallback 中手动同步：this.querySelector("button").value = this.getAttribute("value")。
• 若需要表单参与能力（例如被 form.elements 捕获），必须启用 formAssociated: true 并调用 this.attachInternals()，否则 reportValidity() 和提交值均不可用。
• 不支持 is 属性的原生标签（如
  、）无法通过此方式扩展，只能走独立封装路径。

  旧浏览器必须加 polyfill，且加载时机不能错

  Chrome 67+、Firefox 63+、Safari 10.1+ 原生支持 v1 规范，但 IE 和旧版 Edge 完全不支持。若不引入 polyfill，自定义元素在这些环境中会沦为普通未知标签，connectedCallback 不会触发，customElements.define() 甚至可能静默失败。

  • 推荐使用官方维护的 @webcomponents/custom-elements，CDN 地址：https://unpkg.com/@webcomponents/custom-elements@1.1.2/custom-elements.min.js。
  • polyfill 必须在任何 customElements.define() 调用之前加载，放在 末尾或 开头最为稳妥。
  • 若 DOM 已解析完成后再加载 polyfill，已存在的自定义标签不会自动升级，需要手动调用 customElements.upgrade()。

  真正能获取 getContext()、value、checkValidity() 等原生 API 的，只有 is 扩展路径；而独立标签看似灵活，实则每项原生能力都需要自己桥接，稍有遗漏就会导致表单失联、焦点异常或验证失效。最容易被忽略的是：浏览器对配置错误几乎不报错，只会安静地将其当作普通元素处理——必须通过 el instanceof HTMLButtonElement 或 el.value !== undefined 主动验证是否真正生效。