html自定义元素不支持异步加载，需先占位后升级：用customelements.whendefined()等待定义就绪，再调用customelements.upgrade()激活已存在节点，注意shadow dom查询范围及ssr下的fouc问题。
HTML 自定义元素（Custom Elements）本身不支持“异步加载”或“懒实例化”——浏览器解析到 <my-button></my-button> 时，若对应 customElements.define() 尚未执行，该标签会保持为未知元素（HTMLUnknownElement），既不渲染也不触发生命周期；所谓“异步加载”，实际是控制 define() 的时机与依赖加载的配合问题。
为什么直接 import() + define() 会失败
常见错误是写成这样：
customElements.define('x-chart', () => import('./chart.js').then(m => m.XChart))
这会报错：TypeError: Class constructor XChart cannot be invoked without 'new'。因为 customElements.define() 第二个参数必须是**同步返回的类**，不能是 Promise 或工厂函数。
-
define()不接受异步回调，也不支持延迟注册 - 即使你用
await import()包裹，在模块顶层执行仍可能因执行顺序导致注册晚于 HTML 解析 - 动态
import()在非模块环境（如 script 标签未加type="module"）下直接报错：Failed to resolve module specifier
可靠方案：先占位，后升级（upgrade）
核心思路是让自定义元素在 DOM 中先以“无行为”的状态存在，等模块加载完成、define() 执行后，再手动触发升级。这依赖两个关键点：customElements.whenDefined() 和 customElements.upgrade()。
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 所有自定义元素标签必须在
define()前已存在于 DOM（比如 SSR 渲染或静态 HTML 写死） - 用
customElements.whenDefined('x-chart')等待定义就绪，然后调用customElements.upgrade(node)激活已有节点 - 升级只对当前已挂载的节点生效，新插入的节点会自动升级（前提是已定义）
示例：
// chart-loader.js
async function loadAndDefineChart() {
const mod = await import('./chart.js');
customElements.define('x-chart', mod.XChart);
// 升级所有已存在的 x-chart 节点
document.querySelectorAll('x-chart').forEach(el => customElements.upgrade(el));
}
loadAndDefineChart();
结合动态 import 的构建注意事项
Webpack/Vite 对 import() 的处理会影响实际加载行为，不是所有写法都等效：
- 路径必须是静态字符串（如
import('./chart.js')），不能是拼接变量，否则打包器无法生成 chunk - Vite 默认将
import()拆分为独立 chunk，但若chart.js里又import('./utils.js')，可能产生嵌套 chunk，需检查 network 面板确认是否多请求 - 使用
/* webpackChunkName: "chart" */注释可命名 chunk，便于调试和缓存控制（Vite 也识别该注释） - 不要在
define()外层包裹if (!customElements.get('x-chart'))—— 它不能防止重复 define，反而可能漏掉并发加载场景下的竞态
真正容易被忽略的细节
最常被跳过的不是语法，而是 DOM 生命周期与升级时机的耦合：
- 如果自定义元素在 Shadow DOM 内（比如父组件是另一个自定义元素），
document.querySelectorAll('x-chart')查不到它，得用shadowRoot.querySelectorAll()配合遍历 - SSR 渲染的页面中，若服务端未预加载 JS，客户端首次 upgrade 可能滞后于首屏绘制，造成短暂“无样式内容闪现”（FOUC）——此时应配合
<link rel="preload" as="script">提前拉取关键模块 -
upgrade()不会重触发connectedCallback，但会补全属性、响应式更新和 slot 分发逻辑；若组件内部依赖connectedCallback初始化数据，需额外设计初始化守卫
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
