自定义HTML标签在模板克隆时无法实例化对应类的问题咨询

现象原因 #

1. 模板内容的特殊状态：<template>的content是脱离主DOM树的DocumentFragment，浏览器不会自动处理其中的自定义元素升级——自定义元素的自动升级机制仅对已挂载到主文档DOM树的元素生效。
2. 克隆节点的未升级状态：直接克隆模板内容得到的<test-tag>本质上只是普通HTMLElement，因为它从未进入主文档，浏览器没有触发升级流程。
3. customElements.upgrade()的使用误区：你之前调用无效，是因为该方法需要直接作用于目标元素本身（或包含它的节点），但你注释了调用逻辑，且未确保元素被正确定位后执行升级。

解决方法 #

方法一：先挂载片段到主文档，自动升级 #

把克隆的DocumentFragment挂载到主DOM树后，浏览器会自动扫描并升级其中的自定义元素：

customElements.define("test-tag", TestTag);
customElements.whenDefined("test-tag").then(() => {
    console.log("test-tag defined");
    var tag = document.createElement("test-tag") as TestTag;
    console.log(tag.Property);

    var template = document.getElementById("test") as HTMLTemplateElement;
    var clone = template.content.cloneNode(true) as DocumentFragment;
    // 先将片段挂载到主文档
    document.body.appendChild(clone);
    // 此时查询到的元素已完成升级
    var tag2 = document.querySelector<TestTag>(".test-id");
    if(tag2 == null){
        console.error("tag2 is null");
    } else {
        if(!(tag2 instanceof TestTag)){
            console.error("WTF?!"); // 不会执行到此处
        }
        console.log(tag2.Property); // 输出 Hello
    }
});

方法二：挂载前手动升级元素 #

如果不需要立即挂载到主文档，可以直接对克隆后的元素调用customElements.upgrade()，强制触发升级：

customElements.define("test-tag", TestTag);
customElements.whenDefined("test-tag").then(() => {
    console.log("test-tag defined");
    var tag = document.createElement("test-tag") as TestTag;
    console.log(tag.Property);

    var template = document.getElementById("test") as HTMLTemplateElement;
    var clone = template.content.cloneNode(true) as DocumentFragment;
    var tag2 = clone.querySelector<TestTag>(".test-id");
    if(tag2 == null){
        console.error("tag2 is null");
    } else {
        // 手动升级目标元素
        customElements.upgrade(tag2);
        if(!(tag2 instanceof TestTag)){
            console.error("WTF?!"); // 不会执行到此处
        }
        console.log(tag2.Property); // 输出 Hello
        // 后续可正常挂载到文档
        document.body.appendChild(clone);
    }
});

补充说明 #

自定义元素确实支持通过HTML标记复用行为，但需注意：

• 只有当元素进入主DOM树（或被手动升级）时，才会被实例化为对应的自定义元素类。
• <template>仅用于存储惰性DOM内容，本身不会触发任何元素的初始化或升级，必须通过克隆并挂载（或手动升级）才能激活其中的自定义元素。

内容的提问来源于stack exchange，提问作者Abstraction