PDF.js 源码解读: math_clamp.js

前言

本篇分析 src/shared/math_clamp.js，这是 PDF.js 中最小的模块之一。除去许可证与迁移说明，它只有一个三行函数。

文件很小，作用却不容忽视。PDF.js 反复需要把值限制在 PDF 规范要求的定义域中，或限制在浏览器 UI 允许的范围内：采样函数输入、输出范围、颜色分量、加载百分比、批注坐标和整数存储都使用同一种边界约束操作。

在标准 Math.clamp 提案尚未普遍可用时，MathClamp 集中承载这一操作。因此，这个模块是一处临时的兼容接缝，而不是一套新的数学框架。

模块总览

文件没有状态、类、依赖或 PDF 对象解析。它的全部契约就是两个内建数值运算的顺序与行为。

MathClamp(v, min, max)：应用双重边界

function MathClamp(v, min, max) {
  return Math.min(Math.max(v, min), max);
}

嵌套顺序很关键。Math.max(v, min) 先把低于下界的值抬高；随后 Math.min(..., max) 再把高于上界的值压低。对于满足 min <= max 的普通数值输入，这就是常见的闭区间 clamp。

由实现可以直接得出两条调用契约：

• 辅助函数不会验证或修复参数。 调用方应提供有意义的上下界。反向边界不会自动交换，非法数值输入也不会由本模块替换成回退值。
• 辅助函数不会取整或做其他变换。 数值强制转换和特殊数值行为直接继承自 Math.max 与 Math.min；取整、向下取整、缩放和插值仍由调用方负责。

这种最小化在规范实现中很重要：clamp 可以是更大算法中的一个步骤，而不会悄悄变成另一种运算。

真实调用方：同一操作，多个领域

同一个辅助函数同时出现在 worker 侧解析代码与主线程显示代码中。具有代表性的调用方说明了通用契约的价值：

这些例子也展示了 MathClamp 不做什么。采样函数代码仍负责插值；颜色转换仍负责缩放和格式化分量；setSafeInt16 仍通过 DataView 写入。辅助函数只拥有边界约束这一步。

该模块还通过 src/pdf.js 再次导出，因此它的用途并不局限于某一层的私有实现细节。

为什么独立成模块？

源码中有明确的迁移说明：TC39 的 Math.clamp 提案普遍可用后，替换所有调用并删除本文件。这条说明同时解释了文件名与设计意图。

独立模块让所有现有调用方共享同一个实现，也为未来迁移提供清晰目标，同时避免核心层与显示层各自复制一份顺序容易写错的表达式。实现这一目标不需要额外抽象：一个函数、一个导出就足够了。

Math.min 上方的 ESLint 抑制注释也是一条线索。它让这处兼容实现不受“优先使用标准 clamp 操作”的项目规则限制，并不是额外的运行时分支或功能。

总结

MathClamp 刻意保持小巧，但其语义仍值得精确阅读：

1. 先应用下界，再应用上界。
2. 普通值被限制在闭区间内，不附加取整或缩放。
3. NaN 会传播，反向边界不会被纠正，合法输入仍由调用方负责。
4. 真实调用方把它用于 PDF 定义域与值域、UI 进度与几何、颜色分量以及定宽存储。
5. 独立文件是标准 Math.clamp 提案的共享临时替代，并为目标平台能力就绪后的直接移除保留路径。

这里的设计启示不是“每个单行表达式都需要一个模块”，而是：一个反复出现且有明确标准化迁移计划的操作，值得拥有一个精确、可见的统一契约。

StreamPDF 的设计原则: 能前置处理的绝对不放到解析的时候才做, 由服务端一次解决所有性能问题. 浏览器只获取&渲染必须数据.