z-index 失效的根本原因是自定义元素默认 position: static 且其父容器易意外创建层叠上下文；必须显式设置 :host { position: relative; }，并避免 transform、opacity < 1 等触发新上下文的属性。
z-index 不起作用，不是因为写得不够大，而是因为自定义元素（custom element）默认是 position: static，且其宿主容器极易意外创建层叠上下文——这是最常被忽略的根源。
为什么自定义元素的 z-index 总是失效
自定义元素（如 <my-card>、<modal-dialog>）本身不带定位属性，浏览器按 static 处理，此时无论你给它写 z-index: 9999 还是 z-index: -1，都会被直接忽略。
- 必须显式设置
position: relative（哪怕只是微调位置，也不能只靠top/left） - 如果自定义元素被包裹在
transform、opacity < 1或filter的父容器里，它就只能在该父容器内部比高低，盖不住外部兄弟元素 - 用 DevTools 的 Layers 面板检查，会发现它的层叠上下文边界卡在父级，而不是整个页面
自定义元素中嵌套子元素的层级陷阱
很多自定义元素内部封装了弹窗、下拉菜单等浮动内容，这类子元素的 z-index 只在自定义元素自身的层叠上下文中生效——也就是说，即使子元素设了 z-index: 10000，也跨不出它的宿主边界。
- 临时解法：把关键子元素（如
<my-dialog>内部的<dialog>）用document.body.append()移出宿主 DOM - 长期解法：避免在自定义元素的根节点上使用
transform或opacity；若必须用动画，改用scale+will-change: transform，并确保父级未触发新上下文 - 验证方式：在 DevTools 中选中该子元素，看 Computed →
z-index是否显示为auto，以及layer字段是否指向一个孤立的“Paint Layer”
用 :host 和 :host-context() 精准控制宿主层叠行为
在自定义元素的 Shadow DOM 样式中，:host 是唯一能影响宿主元素自身定位与层叠的入口。靠它才能让整个组件“参与全局堆叠”。
立即学习“前端免费学习笔记（深入）”；
- 必须写：
:host { position: relative; }，否则所有子元素的z-index都无效 - 需要响应外部状态时，用
:host-context(.theme-dark) { z-index: 1050; }比硬编码更可控 - 慎用
:host([open]) { z-index: 1000; }—— 如果多个同类型组件同时 open，它们会互相覆盖，应配合document.activeElement或全局栈管理 - 不要在
:host上设transform或opacity，除非你明确知道它会隔离内部层级
真正难的不是给自定义元素加 z-index，而是看清它落在哪个层叠上下文里——DOM 层级、Shadow DOM 边界、CSS 属性隐式创建的上下文，三者叠加后，一个 z-index: 2 可能比外面的 9999 还低。
