position 定位与 z-index 渲染：dompdf.js 叠加层完全指南

定位是 CSS 布局中最容易出问题的部分，在 PDF 渲染里更是如此：absolute 到底相对谁定位、fixed 会不会在每一页重复出现、z-index 为什么有时不生效，这些问题几乎每个开发者都遇到过，排查起来往往要花掉大半天。dompdf.js 对 position 定位体系提供支持，static、relative、absolute、fixed 四类定位与 z-index 层叠都能按标准 CSS 渲染，其中 fixed 定位元素会在每一页重复出现，这正是水印、页眉、角标等跨页元素的实现基础，也是文档型 PDF 与网页最不同的特性之一。本文从定位体系的四类取值讲起，深入解析包含块与层叠上下文的规则，给出水印、角标、悬浮徽章等场景的完整代码，并讲解特殊场景的处理方式与常见坑点，帮助你精确控制元素在 PDF 中的位置与层级，不再被定位问题折磨。文章覆盖从基础定位到多页叠加的完整知识链，配合代码示例与排查清单，可即学即用。

定位体系：static、relative、absolute 与 fixed

position 有四类基础取值：static 是默认值，元素按正常文档流排布，偏移属性不生效；relative 保留元素在文档流中的位置，同时允许用 top、left 等偏移属性相对原位置移动，常用于微调与作为 absolute 的定位基准。

absolute 让元素脱离文档流，相对最近的已定位祖先（position 非 static）定位，没有则相对页面根；fixed 同样脱离文档流，但相对页面视口定位。dompdf.js 中两者的关键区别在于分页：absolute 跟随所在页的内容流，fixed 则在每一页重复渲染。

理解脱离文档流的影响很重要：absolute 与 fixed 元素不再参与父容器的尺寸计算，父容器可能因此塌陷；模板中如果需要定位元素又不想影响布局，可以给父容器设置显式高度，或者用 relative 加偏移代替，两种思路各有适用场景。

选择哪种定位方式取决于需求：微调位置用 relative，跟随内容流的悬浮元素用 absolute，跨页固定元素用 fixed；理解三类定位的适用边界，可以避免过度使用 fixed 导致每页都出现本应只出现一次的元素。

定位与文档流的交互还有一层：absolute 元素脱离文档流后，其后的兄弟元素会向上填补空位；模板中如果希望占位保留，可以在原位置放置一个同尺寸的占位元素，或者直接用 relative 加偏移，保持布局稳定。

包含块与偏移属性

包含块决定了 absolute 元素的定位基准：最近的已定位祖先的 padding 盒。常见的坑是祖先元素没有设置 position，absolute 元素直接相对页面根定位，位置与预期相差甚远；给祖先加 position: relative 是立竿见影的修复。

偏移属性 top、right、bottom、left 控制元素相对包含块的位移，可以组合使用：top: 10px; left: 10px 定位到左上角，left: 0; right: 0 配合 margin: auto 可以让固定宽度的元素水平居中，这是居中定位的经典技巧，在 PDF 模板中同样有效。

absolute 加百分比偏移会相对包含块尺寸计算：top: 50% 是包含块高度的一半，配合 transform: translateY(-50%) 可以实现精确垂直居中；这种组合在卡片角标、弹层提示等场景中非常实用，代码简短且不依赖具体尺寸。

偏移属性的单位选择也影响布局稳定性：百分比相对包含块尺寸，px 是绝对距离；响应式模板推荐百分比加 transform 的组合，固定版式用 px 更直观；同一模板内尽量统一单位，避免混用导致的维护困惑。

auto 值在偏移属性中有特殊语义：left: auto 时元素保持静态位置，配合 right 与 margin 可以实现右对齐；理解 auto 与显式值的差异，可以写出更简洁的定位代码，减少不必要的偏移计算。

z-index 与层叠上下文

z-index 控制定位元素的层叠顺序，数值越大越靠上；只有定位元素（position 非 static）的 z-index 才生效，普通流元素会被定位元素覆盖。dompdf.js 按标准规则处理层叠，水印、角标、遮罩等叠加场景可以放心使用。

层叠上下文是理解 z-index 失效的关键：设置了 z-index 的定位元素、透明度小于 1 的元素、transform 元素都会创建独立的层叠上下文，内部元素的 z-index 只在该上下文内比较，无法跨上下文参与排序。

排查 z-index 不生效时，先检查是否形成了层叠上下文：父元素如果有 opacity、transform 等属性，子元素的 z-index 会被限制在父上下文内部；给需要置顶的元素移除父级上下文属性，或把元素提升到外层，即可恢复预期层级。

层叠上下文还有一个实用的推论：把需要整体置顶的模块包进一个创建上下文的容器，内部元素的层级冲突就被隔离了；比如把水印层单独包装并设置 z-index，正文内的任何层级都不会干扰水印显示，模板更健壮。

z-index 的数值范围没有硬性限制，但建议用有规律的分档：基础层 0、内容层 10、浮层 100、水印层 999，一目了然；避免随意使用大数值，否则后期调整层级时无从下手，维护成本会随文档复杂度上升。

代码示例：水印、角标与悬浮徽章

import { DomPDF } from 'dompdf.js';

const html = `
  <style>
    .wrap { position: relative; padding: 24px; border: 1px solid #d5dbe3; }
    .badge {
      position: absolute;
      top: -10px; right: 16px;
      background-color: #e74c3c;
      color: #fff;
      border-radius: 4px;
      padding: 2px 10px;
      font-size: 12px;
      z-index: 10;
    }
    .corner {
      position: absolute;
      bottom: 8px; right: 12px;
      font-size: 11px;
      color: #999;
    }
    .watermark {
      position: fixed;
      top: 45%; left: 0; right: 0;
      text-align: center;
      font-size: 44px;
      color: #999;
      opacity: 0.12;
      transform: rotate(-45deg);
      z-index: 999;
    }
  </style>
  <div class='watermark'>机密 · 内部资料</div>
  <div class='wrap'>
    <span class='badge'>热卖</span>
    <h2>无线降噪耳机</h2>
    <p>产品说明与参数详情……</p>
    <span class='corner'>产品编号：P-2026-0817</span>
  </div>`;

const pdf = new DomPDF({ format: 'A4', margin: '20mm' });
pdf.addPage(html, { format: 'A4' });
pdf.save('position-demo.pdf');

fixed 定位与多页重复

fixed 定位元素在 dompdf.js 中会在每一页重复渲染，这是 PDF 文档与网页最大的行为差异，也是水印、页眉提示、每页角标等跨页元素的实现基础：一次声明，所有页面自动生效，不需要为每一页重复插入元素。

利用这个特性可以做出很多实用效果：每页固定的机密水印、每页右上角的版本号角标、每页底部的免责声明。配合透明度与 z-index 控制，这些元素既能稳定呈现，又不干扰正文阅读，文档的专业感和安全性同时提升。

注意 fixed 元素与 @page 边距盒的分工：fixed 适合内容相关的叠加层（水印、角标），@page 边距盒适合页眉页脚与页码；两者可以同时使用，互不冲突，选择哪个取决于元素语义，保持模板结构清晰即可。

fixed 元素的性能也值得关注：每页重复渲染意味着页面数增加时渲染指令成倍增长，水印这类跨页元素建议保持简单的样式（纯文字、低透明度），避免每页都绘制复杂图形，批量导出时性能差异明显。

fixed 元素的内容应当与页面无关：水印、版本号、免责声明都符合这个特征；如果某个元素的内容依赖所在页的数据（如页码），请改用 @page 边距盒，两者分工明确，模板结构也更清晰。

常见问题与坑点

Q: absolute 元素没有相对预期祖先定位？A: 检查祖先是否设置了 position: relative，这是最高频的定位问题；定位链上每一层都要确认，特别是嵌套组件内部，逐层排查即可快速定位。

Q: z-index 设置了却不生效？A: 检查元素是否真的处于定位状态（position 非 static），以及是否被父级层叠上下文限制；移除父元素上的 opacity、transform 等属性，或调整结构把元素放到外层，层级即可恢复。

Q: fixed 元素没有在每页重复？A: 确认使用的是 fixed 而非 absolute；absolute 元素只出现在内容所在的页面，如果页面内容恰好跨页，元素会跟随内容流动，改用 fixed 即可实现每页固定。

Q: 定位元素被分页截断？A: 定位元素超出页面边界时会被裁剪，检查 top、left 偏移是否超出页面内容区；fixed 元素使用百分比或居中的偏移更稳妥，避免依赖具体像素值导致不同页面尺寸下越界。

另一个高频坑是 fixed 元素超出页面边界：top、left 使用绝对值时，不同页面尺寸下可能越界被裁剪；建议 fixed 元素使用百分比偏移或结合 transform 居中，保证在各种纸张规格下都完整显示。

排查定位问题时建议启用元素轮廓：临时给定位元素加明显边框与背景色，渲染一次就能直观看到元素实际位置与覆盖范围，比反复读代码更高效；定位确认无误后再移除调试样式，恢复正式外观。