customelements.define 仅注册标签名，不提供语义、无障碍或表单功能；需手动实现 role/aria、键盘交互、formassociated 接口及 connectedcallback 中安全初始化。
customElements.define 是让自定义元素真正参与语义化构建的入口，但直接注册一个标签名远远不够——它只是语法糖，不自带语义、无障碍或 DOM 行为保障。
为什么 customElements.define 本身不提供语义
浏览器只认标准 HTML 元素的语义含义：button 自带可聚焦、空格/回车触发、role="button" 隐式映射；input[type="checkbox"] 自动关联 aria-checked 状态。而 <my-toggle></my-toggle> 这类自定义标签默认被屏幕阅读器读作“generic”，键盘焦点不会自动进入，也无法被表单序列化。
这意味着：你写了 <my-toggle checked></my-toggle>，但 assistive technology 不知道这是个开关，form.elements 里也找不到它。
- 必须显式添加
role、aria-属性，并同步更新其值 - 必须手动实现键盘交互（
Space、Enter切换，Tab进出） - 必须在
connectedCallback中绑定事件，不能在constructor里操作 DOM 或监听
connectedCallback 是语义初始化的唯一安全时机
常见错误是把事件监听、aria- 初始化、Shadow DOM 渲染全塞进 constructor。此时元素还没插入文档，this.shadowRoot 可能为 null，this.children 为空，getAriaValueNow() 会读不到初始属性。
正确做法只在 connectedCallback 中做三件事：
- 调用
this.attachShadow({ mode: 'open' })（如需 Shadow DOM） - 用
this.hasAttribute('checked')同步设置内部input[type="checkbox"]的checked和aria-checked - 绑定
click、keydown事件，并确保preventDefault()对Space生效
如何让自定义元素被表单识别并提交数据
原生表单控件能被 form.submit() 序列化，是因为它们实现了 HTMLElement 的 formAssociated 接口。自定义元素必须显式启用：
- 在 class 定义中声明
static formAssociated = true - 在
constructor中调用this.internals_ = this.attachInternals()（注意下划线是私有约定，非 API） - 通过
this.internals_.setFormValue()设置提交值，例如切换时传this.checked ? 'on' : 'off' - 覆盖
valuegetter/setter，使其与setFormValue同步
否则，即使你把它放在 <form></form> 里，new FormData(form) 也完全忽略它。
避免用 <div> 包裹语义内容来“模拟”结构
<p>有人写 <code><my-card><div role="article">...</div></my-card>，以为加了 role 就够了。但问题在于：
-
role="article" 不继承父元素的语义上下文，<my-card></my-card> 仍是 generic
- 嵌套
role 容易破坏父子关系（比如 role="navigation" 里放 role="button" 没问题，但放 role="article" 就可能被忽略）
- 更好的方式是让
<my-card></my-card> 自身具有语义：在 connectedCallback 中设置 this.setAttribute('role', 'region')，再用 aria-labelledby 关联内部标题
role="article" 不继承父元素的语义上下文，<my-card></my-card> 仍是 genericrole 容易破坏父子关系（比如 role="navigation" 里放 role="button" 没问题，但放 role="article" 就可能被忽略）<my-card></my-card> 自身具有语义：在 connectedCallback 中设置 this.setAttribute('role', 'region')，再用 aria-labelledby 关联内部标题真正的语义增强，是从元素自身出发，而不是靠内部一个 div 去补救。
真正难的不是写个customElements.define，而是让每个自定义标签在 DOM 树里、在辅助技术中、在表单逻辑里，都像原生元素一样“存在”。这需要对 role 体系、internals API 和生命周期钩子有精确控制，而不是依赖样式或 JS 行为去掩盖语义缺失。
