is属性仅对规范白名单原生标签(如button、video等)有效,需配合customelements.define()的{extends}选项注册,且大小写、连字符、拼写必须完全匹配;类必须继承对应html接口并constructor中调用super();is在html解析时决定实例化构造器,不可动态更改。

直接说结论:is 属性不是“加了就能扩展”的装饰性属性,它只在特定原生标签上生效,且必须配合 customElements.define() 的 { extends: "xxx" } 选项注册,否则完全无效。
哪些标签能用 is 扩展?
浏览器只允许对 WHATWG 规范白名单里的原生标签使用 is,包括但不限于:button、canvas、video、table、tr、td、p。其他标签如 div、span、section 加 is 属性毫无作用——解析后仍是普通 HTMLDivElement 等,生命周期钩子不会触发,自定义类也不会实例化。
常见错误现象:<div is="my-thing"></div> 在控制台里 el instanceof HTMLElement 为 true,但 el instanceof MyThing 永远是 false。
is 值和 customElements.define() 必须严格一致
匹配是大小写+连字符+拼写全敏感的。注册时写 customElements.define("my-video", MyVideo, { extends: "video" }),HTML 中就必须写 <video is="my-video"></video>。
-
<video is="MyVideo"></video>→ 不匹配,退化为普通HTMLVideoElement -
<video is="myvideo"></video>→ 缺连字符,不匹配 -
<video is="my-video "></video>→ 尾部空格,不匹配 -
<video data-is="my-video"></video>→ 浏览器完全忽略,只是个普通字符串属性
Vue 模板里混用更危险:<button is="my-btn"></button> 在 Vue 2 中可能被模板编译器当成组件语法糖劫持,而 Web Components 注册又未触发,结果 DOM 是个既没原生表单能力、也没自定义逻辑的残缺按钮。
扩展内置元素时,类继承和 super() 是硬性门槛
想让 <video is="my-video"></video> 真正生效,你的类必须继承 HTMLVideoElement(不能只继承 HTMLElement),且 constructor 第一行必须调 super():
class MyVideo extends HTMLVideoElement {
constructor() {
super(); // 必须!否则 this.src、this.play() 全部失效
}
connectedCallback() {
// 这里可以加逻辑,但不能直接 this.play()
}
}
漏掉 super() 的典型症状:
-
this.src读出来是undefined,但this.getAttribute("src")能取到值 -
this.play()报TypeError: Illegal invocation -
this.width、this.height永远为0(对canvas同理)
注意:super() 只能在 constructor 里调,connectedCallback 里补无效;也不能在 super() 前给 this.xxx 赋值,否则浏览器可能抛 Illegal constructor。
is 是解析阶段决策,不是运行时开关
is 的作用发生在 HTML 字符串被浏览器解析成 DOM 树的那一刻。它决定用哪个构造器来实例化该节点——这个选择不可逆,也无法靠 JS 动态更改。
所以这些操作都无效:
-
el.setAttribute('is', 'my-button')→ 已挂载的元素改is属性不会切换类 - SSR 渲染出带
is的 HTML,但 JS 注册代码在DOMContentLoaded之后才执行 → 页面初始就是普通原生元素,hydrate 阶段也不会自动“升级” - 试图用
document.createElement('button')再设is属性 → 创建出来就是HTMLButtonElement,后续加is不会改变其原型链
真正可靠的方案:确保 customElements.define() 在任何含 is 的 HTML 被解析前就同步执行,比如放在 <script></script> 标签里,且位于相关 HTML 上方。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











