自定义元素的 constructor 中禁止操作属性或 DOM，所有初始化应严格遵循生命周期规范：className 等属性赋值必须推迟至 connectedCallback，否则在同步 createElement() 或已注册标签解析时将触发 NotSupportedError。
自定义元素的 `constructor` 中禁止操作属性或 dom，所有初始化应严格遵循生命周期规范：`classname` 等属性赋值必须推迟至 `connectedcallback`，否则在同步 `createelement()` 或已注册标签解析时将触发 `notsupportederror`。
在 Web Components 开发中，一个常见却极易被忽视的陷阱是：在自定义元素的 constructor 中直接设置 HTML 属性（如 this.className = "hi"、this.id = "foo" 或 this.setAttribute("data-ready", "true")）——这不仅违背规范，更会在特定场景下导致运行时异常。
根据 HTML 规范 §4.13.2 Custom element conformance 第 5 条明确要求：
The element must not gain any attributes or children.
这意味着：constructor 的唯一合法职责是调用 super()、创建 Shadow DOM（this.attachShadow()）、初始化私有字段（如 this._rendered = false），而绝不能触碰任何属性、子节点或 DOM 查询操作。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
❗为什么 this.className = "hi" 在某些情况下“看似有效”，却实为危险？
关键在于元素实例化方式与注册时机的组合：
| 场景 | 是否报错 | 原因说明 |
|---|---|---|
| ✅ <bazooka-show> 标签出现在 customElements.define() 之前（脚本在 </body> 后或未 defer） | ❌ 不报错（但行为异常） | 浏览器先将其解析为 HTMLUnknownElement，后续升级（upgrade）时调用 constructor，此时属性已由 HTML 解析器写入，规范检查被绕过；但 connectedCallback 可能不触发，Shadow DOM 无法挂载。 |
| ⚠️ document.createElement('bazooka-show') 在 define() 之后调用 | ✅ 报 NotSupportedError | DOM 规范在 create-an-element 步骤 6.5 明确检查：若新元素已有属性（包括 className 这类反射属性），立即抛出异常。 |
| ⚠️ <bazooka-show class="explicit"> 且 define() 已提前执行 | ✅ 报 NotSupportedError | HTML 解析器识别到已注册标签，直接走标准构造流程，constructor 中设 className 触发规范校验失败。 |
? 补充说明：className 是 HTMLElement.className 的反射属性（reflected attribute），其底层等价于 this.setAttribute('class', 'hi')。因此，它完全受上述“禁止在 constructor 中增删属性”规则约束。
✅ 正确实践：属性操作统一移交至 connectedCallback
class Bazooka extends HTMLElement {
#shadow;
#rendered = false;
constructor() {
super(); // ✅ 必须第一行
this.#shadow = this.attachShadow({ mode: 'open' }); // ✅ 允许：仅创建 Shadow Root
// ❌ 禁止：this.className = "hi";
// ❌ 禁止：this.setAttribute('role', 'region');
}
connectedCallback() {
// ✅ 安全：此时元素已挂载，DOM 上下文就绪
if (!this.#rendered) {
this.className = 'hi'; // ✅ 合法：class 属性可设
this.setAttribute('aria-live', 'polite'); // ✅ 合法：普通属性可设
const template = document.querySelector('.test');
if (template && template.content) {
this.#shadow.appendChild(template.content.cloneNode(true));
}
this.#rendered = true;
}
}
// 若需响应属性变更（如 data-xxx），需配合 observedAttributes
static get observedAttributes() {
return ['data-theme'];
}
attributeChangedCallback(name, oldValue, newValue) {
if (name === 'data-theme' && newValue !== oldValue) {
this.#shadow.querySelector('style')?.textContent =
`:host { --theme-color: ${newValue}; }`;
}
}
}
customElements.define('bazooka-show', Bazooka);⚠️ 重要注意事项
- connectedCallback 可能被多次调用（如元素被移出再插入 DOM），务必使用标志位（如 this.#rendered）防重复渲染；
- 不要在 constructor 中访问 this.shadowRoot 或调用 querySelector —— 此时其值恒为 null；
- className、id、style 等反射属性与 setAttribute() 具有同等语义，均受规范限制；
- 若需预设初始状态，应在 connectedCallback 中读取 this.getAttribute('xxx') 或检查 this.hasAttribute('xxx')，而非依赖 constructor 赋值。
✅ 总结：三原则守则
| 原则 | constructor | connectedCallback |
|---|---|---|
| DOM 操作 | ❌ 禁止（shadowRoot 为空，querySelector 返回 null） | ✅ 允许（元素已挂载，上下文完整） |
| 属性设置 | ❌ 禁止（触发 NotSupportedError） | ✅ 允许（className / setAttribute / dataset 均安全） |
| 事件监听 | ❌ 禁止（无有效 this 绑定目标） | ✅ 推荐（绑定至 this 或 this.#shadow） |
遵循这一规范，不仅能规避隐蔽的运行时错误，更是构建可维护、可测试、符合 Web Standards 的现代 Web Components 的基石。
