CSS 颜色与渐变渲染详解：dompdf.js 让 PDF 告别单调

很多开发者用 dompdf.js 导出 PDF 时只满足于黑字白底，其实颜色和渐变是让文档专业起来最快的手段：报表表头加上品牌色，卡片用渐变背景，状态标签用不同颜色区分，视觉品质立刻上一个台阶。颜色写得好不好，直接决定阅读效率和品牌一致性，也影响文档在客户和领导眼中的专业程度。本文系统讲解 dompdf.js 对 CSS 颜色与渐变系列（linear-gradient、radial-gradient、repeating 系列）的支持范围与写法细节，从基础色值、透明度讲到渐变角度与颜色节点，配合真实可渲染的代码示例，并给出降级方案与常见坑点。无论你是做报表、发票、简历还是产品说明书，掌握这些知识都能让导出的 PDF 视觉质量明显提升，同时避免浏览器里好看、PDF 里变样的尴尬，减少反复调试的时间成本。文中每个知识点都配有可直接运行的示例，代码注释也解释了为什么这样写，照着抄就能在项目里落地。

颜色值的写法与支持范围

dompdf.js 直接解析 CSS 颜色，支持命名颜色（red、skyblue 等）、十六进制（#3498db）、rgb/rgba 与 hsl/hsla 函数式写法，与浏览器行为一致。日常开发怎么写，PDF 里就怎么渲染，不需要任何转换层，学习成本几乎为零，从网页迁移到 PDF 模板时可以原样保留颜色代码。

十六进制写法最常用也最精确，适合精确定义品牌色；rgba 的第四个参数控制透明度，是渐变、水印和叠加效果的基础；hsl 用色相、饱和度、亮度描述颜色，适合做色系统一，比如由品牌主色衍生出浅色背景与深色文字等变体，保证整套文档色调协调。

需要提醒的是，颜色最终会被转换到 PDF 色彩空间，建议统一使用 sRGB 色值，避免极端饱和色在不同显示器与打印设备上出现偏差。对品牌色严格的场景，最好用打印样张核对一次，以实际输出为准，而不是只相信屏幕预览，这样可以避免交付后才发现色差问题。

实际开发中，颜色写法的一致性比技巧更重要：项目里最好约定一种主用写法（推荐十六进制加 rgba 组合），并在代码规范里写明；这样可以减少团队成员各自用不同写法导致的混乱，也让模板的样式更统一、更容易维护。

另外要注意颜色的对比度问题：正文与背景的对比度不足时，打印出来的文档阅读困难，尤其对视力不好的用户不友好；WCAG 建议正文对比度达到 4.5:1 以上，模板里可以借助对比度工具提前校验，从源头保证文档可读性。

线性渐变 linear-gradient 详解

linear-gradient 是使用频率最高的渐变类型，让背景从一种颜色平滑过渡到另一种颜色。dompdf.js 支持角度与方向关键字，比如 to right、to bottom、135deg，也支持任意数量的颜色节点与百分比位置，写法与浏览器标准完全一致，已有的网页样式可以无缝复用。

颜色节点是渐变的核心：linear-gradient(90deg, #3498db 0%, #2ecc71 100%) 表示从左到右由蓝过渡到绿，节点百分比控制过渡的节奏；三个以上节点可以做出分段过渡效果，比如渐变分隔线、数据条或色阶图，比纯色区块更有信息表现力。

写渐变时建议遵循先底色后渐变的顺序：background-color 放在前面作兜底，background-image 放渐变。即使引擎对某个复杂渐变处理异常，底色依然能保证页面不穿帮，这是所有渲染引擎通用的防御式写法，也是排查渐变问题时的第一道保险。

渐变方向也影响观感：从上到下的渐变符合自然光照习惯，适合大面积背景；对角渐变更有动感，适合标题与卡片；具体选择取决于内容气质，但同一份文档里渐变方向最好保持一致，避免视觉混乱。

多个颜色节点的位置还可以用关键词控制，比如 linear-gradient(90deg, red, yellow 50%, green) 让中间色固定在 50% 位置，过渡节奏更可控；调试时建议先在浏览器里预览确认效果，再原样搬到 PDF 模板，减少往返试错。

径向渐变与重复渐变

radial-gradient 从圆心向外扩散，适合做高光、光晕和按钮质感；可以指定形状（circle 或 ellipse）与圆心位置（at center、at top right）。dompdf.js 对径向渐变支持良好，常用于生成强调色块、圆形徽章底与装饰元素，让平面文档多一分立体感。

repeating-linear-gradient 与 repeating-radial-gradient 会按固定节奏重复渐变单元，适合做斜纹水印、条纹表头、进度条纹理和色带分隔，比手写多个色块高效得多，颜色过渡也更自然，是批量文档里提升质感的高性价比手段。

使用重复渐变时注意周期单位的统一：px 与百分比混用会导致条纹宽度在不同页面尺寸下不一致。固定尺寸容器建议用 px，自适应容器用百分比，输出效果更可预期；条纹宽度也要考虑打印缩放，避免过细条纹在打印时糊成一片。

径向渐变与重复渐变组合使用可以做出更丰富的装饰：比如圆形徽章用径向渐变做高光，底部用重复渐变做纹理，两个背景图层叠加，视觉层次立刻提升；但装饰元素不要过度，保持文档主体信息优先。

渐变还常用于图表类文档：进度条、数据条、热力色阶都可以用渐变实现，颜色过渡本身就在传达信息；配合透明度变化可以做出从实到虚的渐变效果，让数据可视化页面更生动，也更容易聚焦重点区域。

代码示例：品牌渐变卡片与状态标签

import { DomPDF } from 'dompdf.js';

const html = `
  <style>
    .card {
      background-color: #eaf2fb;  /* 兜底色：渐变异常时页面不穿帮 */
      background-image: linear-gradient(135deg, #3498db 0%, #2ecc71 100%);
      border-radius: 12px;
      padding: 24px;
      color: #fff;
    }
    .tag {
      display: inline-block;
      padding: 4px 12px;
      border-radius: 999px;
      font-size: 12px;
      color: #fff;
    }
    .tag-ok   { background-color: #27ae60; }
    .tag-warn { background-color: rgba(243, 156, 18, 0.85); }
    .bar {
      height: 14px;
      background-color: #ecf0f1;
      background-image: repeating-linear-gradient(
        90deg, #3498db 0 40px, #5dade2 40px 80px
      );
    }
  </style>
  <div class='card'>
    <h1>月度营收概览</h1>
    <p>渐变背景搭配兜底色，两种保险同时生效</p>
  </div>
  <p>
    <span class='tag tag-ok'>正常</span>
    <span class='tag tag-warn'>预警</span>
  </p>
  <div class='bar'></div>`;

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

颜色与渐变的实战场景

报表场景：表头用品牌色渐变，隔行用浅色交替（如 #f8f9fa），数字列用强调色突出；发票场景：金额用红色系，税率标签用绿色系；简历场景：标题栏加渐变，技能条用重复渐变。这些都是一两行 CSS 的事，但视觉提升立竿见影，客户感知差异非常明显。

渐变适合装饰性背景，正文文字颜色建议保持高对比度深色，保证打印清晰；大面积深色渐变背景上的白字，在部分打印设备上可能发灰，务必用样张验证。浅色渐变虽然安全，也要注意打印机的墨量表现，避免大面积区域出现色带或墨迹不均。

颜色在文档里还有语义作用：红色表示异常、绿色表示正常、橙色表示警告。建议在模板中统一管理色板，让颜色定义集中在一处，修改一处全局生效，避免散落各处的魔法色值难以维护，也方便后续按品牌规范统一调整。

还有一个高频场景是邮件与附件：导出的 PDF 作为附件发送时，颜色能帮助收件人快速定位信息，比如报销单里的红色超标金额、审批表里的绿色通过标记；建议在模板里把语义色集中定义，并配上文字说明，避免颜色歧义。

常见问题与降级方案

Q: 渐变在 PDF 里变成纯色？A: 检查是否在渐变前写了 background-color 兜底，以及渐变语法是否完整（方向、颜色节点、括号配对）；可以先去掉兜底色直接观察渐变是否渲染，再逐步定位问题，通常一两分钟就能找到原因。

Q: 颜色与浏览器显示不一致？A: 多为色彩空间差异所致，统一使用 sRGB 色值，避免显示器特有的广色域色值；十六进制与 rgba 写法最稳定，hsl 转换结果在不同引擎间可能存在微小差异，对色准要求高时优先用十六进制。

Q: 深色背景上的白字打印发灰？A: 这是打印设备墨量限制所致，建议降低背景饱和度，或改用浅色背景加深色文字的组合；也可以在模板里准备一份打印专用样式，在导出时切换，兼顾屏幕观感与打印效果。

降级总原则：颜色缺失不会导致渲染失败，只会退化为默认黑色或透明。因此任何关键视觉信息都不要只依赖颜色表达，配合图标、文字或边框做双重编码，文档在黑白打印、灰度环境下依然可用，这是专业文档的基本素养。

如果渐变输出出现色带（颜色过渡出现肉眼可见的分层），通常是颜色节点过少或间距过大，增加中间节点可以让过渡更平滑；配合低对比度的相邻色，色带现象会明显减轻，输出更细腻。