customElements.define注册失败主因是名称不合法：必须含短横线且不以短横线开头或结尾，禁用纯数字、纯字母及大小写错误；Shadow DOM应选open模式以支持调试与测试；attributeChangedCallback需正确声明observedAttributes并用setAttribute触发；跨框架复用须用原生DOM事件与字符串属性传值，避免框架生命周期干扰。
customElements.define 注册失败的常见报错
直接写 customElements.define('html-runner', HtmlRunner) 报 Failed to execute 'define' on 'CustomElementRegistry': The name "html-runner" is not a valid custom element name？先确认名字是否含短横线且不以短横线开头或结尾——html-runner 合法，htmlrunner、-html-runner、html-runner- 全部非法。另外别用纯数字或纯字母名，比如 123 或 button 都会拒收。
Shadow DOM mode 选 open 还是 closed？在线运行器必须选 open
在线运行器组件（比如带编辑区、预览区、控制栏的容器）需要被外部脚本注入代码、触发重载、读取输出日志，甚至被 Puppeteer 自动化测试抓取内部 iframe 或 console 输出。这些操作全依赖 el.shadowRoot 可访问。选 mode: 'closed' 会让 shadowRoot 返回 null，调试器里看不到结构，querySelector 查不到按钮，Jest 测试直接失效。除非你明确要防 JS 探测（例如金融类沙箱），否则一律用 open。
attributeChangedCallback 不响应 HTML 字符串更新？检查 observedAttributes 和触发方式
想监听 <html-runner html="<h1>Hello</h1>"> 中的 html 属性变化，但回调没执行？三个关键点：
-
static get observedAttributes()必须返回['html']字符串数组，不是{html: true}或'html' - 属性名大小写敏感：
HTML≠html，浏览器只认小写声明 - JS 直接赋值
el.html = '<p>test</p>'不触发回调；必须用el.setAttribute('html', '<p>test</p>')或在标签里写死
推荐做法：把 HTML 字符串作为 attribute 声明，再在 attributeChangedCallback 里同步到 shadowRoot 内部的 <iframe> 或 <div>，避免手动 DOM 操作污染。
立即学习“前端免费学习笔记（深入）”；
如何让 <html-runner> 真正跨框架复用？别碰 React/Vue 的生命周期
在线运行器本质是“原生宿主”，不是框架子组件。React 里写 <html-runner html={code} onRun={handleRun}> 是错的——onRun 不会被识别为自定义事件，也不会自动绑定。正确姿势：
- 用标准 DOM 事件：
el.addEventListener('run', handler)，在组件内 dispatchnew CustomEvent('run', { detail: { result } }) - 属性传值只走 HTML attribute（字符串），复杂数据序列化成 JSON 字符串再 parse
- 避免在 React 的
useEffect里反复define同一个 tag——注册一次全局生效，重复调用会报错
真正容易被忽略的是样式穿透问题：即使用了 Shadow DOM，如果用户代码里写了 body { margin: 0 }，它依然会影响外部页面。解决方案是在 iframe 中运行预览内容，或用 :host { all: initial } 重置继承链——但这不能覆盖 @keyframes 或 @font-face，得靠 CSP 或 sandbox 属性兜底。
