PDF.js 源码解读: api

export {
  build,
  getDocument,
  PDFDataRangeTransport,
  PDFDocumentLoadingTask,
  PDFDocumentProxy,
  PDFPageProxy,
  PDFWorker,
  RenderTask,
  version,
};

function getDocument(src = {}) {
  const task = new PDFDocumentLoadingTask();
  const { docId } = task;
 
  const url = src.url ? getUrlProp(src.url) : null;
  const data = src.data ? getDataProp(src.data) : null;
  // ... 35+ 个局部变量
  const useWorkerFetch =
    typeof src.useWorkerFetch === "boolean"
      ? src.useWorkerFetch
      : (typeof PDFJSDev !== "undefined" && PDFJSDev.test("MOZCENTRAL")) ||
        !!(
          BinaryDataFactory === DOMBinaryDataFactory &&
          cMapUrl && cMapPacked && standardFontDataUrl && wasmUrl &&
          isValidFetchUrl(cMapUrl, document.baseURI) &&
          // ...
        );

const docParams = {
  docId,
  apiVersion: /* BUNDLE_VERSION */,
  data,
  password,
  disableAutoFetch,
  rangeChunkSize,
  docBaseUrl,
  enableXfa,
  evaluatorOptions: {
    maxImageSize, disableFontFace, ignoreErrors,
    isOffscreenCanvasSupported, isImageDecoderSupported,
    canvasMaxAreaInBytes, fontExtraProperties, useSystemFonts,
    useWasm, useWorkerFetch, cMapUrl, cMapPacked, iccUrl,
    standardFontDataUrl, wasmUrl,
    hasGPU: false, // 占位，worker 就绪后回填
  },
};
const transportParams = {
  ownerDocument,
  pdfBug,
  styleElement,
  enableHWA,
  loadingParams: { disableAutoFetch, enableXfa },
};

let networkStream;
if (data) {
  // 整份 PDF 已在内存，不需要网络流
} else if (rangeTransport) {
  networkStream = new PDFDataTransportStream({
    pdfDataRangeTransport: rangeTransport, disableRange, disableStream,
  });
} else if (url) {
  const NetworkStream = getNetworkStream(url); // 优先 fetch，回退 XHR
  networkStream = new NetworkStream({
    url, httpHeaders, withCredentials, rangeChunkSize, disableRange, disableStream,
  });
} else {
  throw new Error("getDocument - expected either `data`, `range`, or `url` parameter.");
}

Promise.all([worker.promise, gpuPromise])
  .then(function ([, hasGPU]) {
    if (worker.destroyed) throw new Error("Worker was destroyed");
    docParams.evaluatorOptions.hasGPU = hasGPU;
 
    const workerIdPromise = worker.messageHandler.sendWithPromise(
      "GetDocRequest", docParams, data ? [data.buffer] : null
    );
    // ... 建 networkStream
    return workerIdPromise.then(workerId => {
      const messageHandler = new MessageHandler(docId, workerId, worker.port);
      const transport = new WorkerTransport(
        messageHandler, task, networkStream, transportParams, transportFactory, pagesMapper
      );
      task._transport = transport;
      if (task.destroyed) throw new Error("Loading aborted");
      messageHandler.send("Ready", null);
    });
  })
  .catch(task._capability.reject)
  .finally(task._setupCapability.resolve);
 
return task;

class PDFDocumentLoadingTask {
  static #docId = 0;
 
  _capability = Promise.withResolvers();
  _setupCapability = Promise.withResolvers();
  _transport = null;
  _worker = null;
 
  docId = `d${PDFDocumentLoadingTask.#docId++}`;
  destroyed = false;
  onPassword = null;
  onProgress = null;
 
  get promise() {
    return this._capability.promise;
  }
}

async destroy() {
  this.destroyed = true;
  // 启动链稍后会用 "Loading aborted" reject _capability；先认领这个 rejection，
  // 避免被当成未处理的 promise 拒绝
  this._capability.promise.catch(() => {});
 
  try {
    // 必须同步设置：后续对共享 workerPort 的 PDFWorker.create() 要立即看到并抛错
    if (this._worker?.port) this._worker._pendingDestroy = true;
    // 等启动链结束，保证 _transport 已设置，"Terminate" 消息才发得出去
    await this._setupCapability.promise;
    await this._transport?.destroy();
  } catch (ex) {
    if (this._worker?.port) delete this._worker._pendingDestroy;
    throw ex;
  }
  this._transport = null;
  this._worker?.destroy();
  this._worker = null;
}

class PDFDataRangeTransport {
  #capability = Promise.withResolvers();
  #listener = null;
 
  constructor(length, initialData, progressiveDone = false, contentDispositionFilename = null) { ... }
 
  onDataRange(begin, chunk) {
    this.#listener({ type: "range", begin, chunk });
  }
 
  onDataProgressiveRead(chunk) {
    this.#capability.promise.then(() => {
      this.#listener({ type: "progressiveRead", chunk });
    });
  }
 
  transportReady(listener) {
    this.#listener = listener;
    this.#capability.resolve();
  }
 
  requestDataRange(begin, end) {
    unreachable("Abstract method PDFDataRangeTransport.requestDataRange");
  }
  abort() {}
}

class PDFDocumentProxy {
  constructor(pdfInfo, transport) {
    this._pdfInfo = pdfInfo;
    this._transport = transport;
    // TESTING / INTERNAL_VIEWER 构建下再动态挂 getRawData 等方法
  }
}

get isPureXfa() {
  return shadow(this, "isPureXfa", !!this._transport._htmlForXfa);
}

if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
  Object.defineProperty(this, "getNetworkStreamName", {
    value: () => this._transport.getNetworkStreamName(),
  });
  // getXFADatasets / getStartXRefPos / getAnnotArray 同理
}

getOptionalContentConfig({ intent = "display" } = {}) {
  const { renderingIntent } = this._transport.getRenderingIntent(intent);
  return this._transport.getOptionalContentConfig(renderingIntent);
}

cleanup(keepLoadedFonts = false) {
  return this._transport.startCleanup(keepLoadedFonts || this.isPureXfa);
}

constructor(pageIndex, pageInfo, transport, pagesMapper, pdfBug = false) {
  this._pageIndex = pageIndex;
  this._pageInfo = pageInfo;
  this._transport = transport;
  /** @type {PDFObjects} */
  this.commonObjs = transport.commonObjs; // 文档级共享：字体、跨页图片
  this.objs = new PDFObjects();           // 页面级私有：本页图片与图案
 
  this._intentStates = new Map();
  // ...
}

const intentState = this._intentStates.getOrInsertComputed(cacheKey, makeObj);

render({ canvasContext, canvas = canvasContext.canvas, viewport, intent = "display", ... }) {
  const intentArgs = this._transport.getRenderingIntent(intent, annotationMode, ...);
  const { renderingIntent, cacheKey } = intentArgs;
  this.#pendingCleanup = false; // 有渲染在跑，取消挂起的清理
 
  optionalContentConfigPromise ||=
    this._transport.getOptionalContentConfig(renderingIntent);
 
  const intentState = this._intentStates.getOrInsertComputed(cacheKey, makeObj);
  if (intentState.streamReaderCancelTimeout) {
    clearTimeout(intentState.streamReaderCancelTimeout); // 取消延迟中止
    intentState.streamReaderCancelTimeout = null;
  }
 
  if (!intentState.displayReadyCapability) {
    // 首次渲染：建好 operatorList 容器，立刻开始向 worker 泵取
    intentState.displayReadyCapability = Promise.withResolvers();
    intentState.operatorList = { fnArray: [], argsArray: [], lastChunk: false, separateAnnots: null };
    this._pumpOperatorList(intentArgs);
  }
  // ... 建 InternalRenderTask，登记进 intentState.renderTasks

  Promise.all([
    intentState.displayReadyCapability.promise,
    optionalContentConfigPromise,
  ]).then(([transparency, optionalContentConfig]) => {
    if (this.destroyed) { complete(); return; }
    if (!(optionalContentConfig.renderingIntent & renderingIntent)) {
      throw new Error("Must use the same `intent`-argument ...");
    }
    internalRenderTask.initializeGraphics({ transparency, optionalContentConfig });
    internalRenderTask.operatorListChanged();
  }).catch(complete);
 
  return renderTask; // 同步返回，不等任何 promise
}

_pumpOperatorList({ renderingIntent, cacheKey, annotationStorageSerializable, modifiedIds }) {
  const { map, transfer } = annotationStorageSerializable;
  const readableStream = this._transport.messageHandler.sendWithStream(
    "GetOperatorList",
    {
      pageId: this.#pagesMapper.getPageId(this._pageIndex + 1) - 1,
      pageIndex: this._pageIndex,
      intent: renderingIntent,
      cacheKey,
      annotationStorage: map,
      modifiedIds,
    },
    /* queueingStrategy = */ undefined,
    transfer
  );
  const reader = readableStream.getReader();
  const intentState = this._intentStates.get(cacheKey);
  intentState.streamReader = reader;
 
  const pump = () => {
    reader.read().then(({ value, done }) => {
      if (done) { intentState.streamReader = null; return; }
      if (this._transport.destroyed) return;
      this._renderPageChunk(value, intentState); // 追加进 fnArray/argsArray，唤醒各渲染任务
      pump();
    }, reason => { /* 出错：标记 lastChunk，唤醒并 reject 各 capability */ });
  };
  pump();
}

if (reason instanceof RenderingCancelledException) {
  let delay = RENDERING_CANCELLED_TIMEOUT; // 100ms
  if (reason.extraDelay > 0 && reason.extraDelay < 1000) {
    delay += reason.extraDelay;
  }
  intentState.streamReaderCancelTimeout = setTimeout(() => {
    intentState.streamReaderCancelTimeout = null;
    this._abortOperatorList({ intentState, reason, force: true });
  }, delay);
  return;
}

if (intentState.renderTasks.size > 0) return;

#tryCleanup() {
  if (!this.#pendingCleanup || this.destroyed) return false;
  for (const { renderTasks, operatorList } of this._intentStates.values()) {
    if (renderTasks.size > 0 || !operatorList.lastChunk) return false;
  }
  this._intentStates.clear();
  this.objs.clear();
  this.#pendingCleanup = false;
  return true;
}

static {
  if (isNodeJS) {
    // Node.js 不支持这里的 Worker 用法，直接禁用
    this.#isWorkerDisabled = true;
    GlobalWorkerOptions.workerSrc ||= PDFJSDev.test("LIB")
      ? "../pdf.worker.js"
      : "./pdf.worker.mjs";
  }
  this._isSameOrigin = (baseUrl, otherUrl) => { /* 非同源或非 http 返回 false */ };
  this._createCDNWrapper = url => {
    const wrapper = `await import("${url}");`;
    return URL.createObjectURL(new Blob([wrapper], { type: "text/javascript" }));
  };
}

const sendTest = () => {
  const testObj = new Uint8Array();
  // 验证 postMessage 的 transfer 能力：Uint8Array 到 worker 侧仍是 Uint8Array
  messageHandler.send("test", testObj, [testObj.buffer]);
};
sendTest(); // 立即发一次
// worker 的 "ready" 消息到达后再发一次；worker 只处理先到的那条

#setupFakeWorker() {
  if (!PDFWorker.#isWorkerDisabled) {
    warn("Setting up fake worker.");
    PDFWorker.#isWorkerDisabled = true; // 后续文档不再尝试真 worker
  }
  PDFWorker._setupFakeWorkerGlobal.then(WorkerMessageHandler => {
    if (this.destroyed) { /* reject */ return; }
    const port = new LoopbackPort();
    const id = `fake${PDFWorker.#fakeWorkerId++}`;
    const workerHandler = new MessageHandler(id + "_worker", id, port);
    WorkerMessageHandler.setup(workerHandler, port);
    this.#messageHandler = new MessageHandler(id, id + "_worker", port);
    this.#resolve();
  });
}

static create(params) {
  const cachedPort = this.#workerPorts.get(params?.port);
  if (cachedPort) {
    if (cachedPort._pendingDestroy) {
      throw new Error(
        "PDFWorker.create - the worker is being destroyed.\n" +
        "Please remember to await `PDFDocumentLoadingTask.destroy()`-calls."
      );
    }
    return cachedPort;
  }
  return new PDFWorker(params);
}

#pageCache = new Map();      // pageIndex -> PDFPageProxy
#pagePromises = new Map();   // pageIndex -> Promise<PDFPageProxy>
#pageRefCache = new Map();   // "12R0" -> pageIndex

#cacheSimpleMethod(name, data = null) {
  return this.#methodPromises.getOrInsertComputed(name, () =>
    this.messageHandler.sendWithPromise(name, data)
  );
}

let renderingIntent = RenderingIntentFlag.DISPLAY;
switch (intent) {
  case "any":   renderingIntent = RenderingIntentFlag.ANY; break;
  case "print": renderingIntent = RenderingIntentFlag.PRINT; break;
}
switch (annotationMode) {
  case AnnotationMode.DISABLE:         renderingIntent += RenderingIntentFlag.ANNOTATIONS_DISABLE; break;
  case AnnotationMode.ENABLE_FORMS:    renderingIntent += RenderingIntentFlag.ANNOTATIONS_FORMS; break;
  case AnnotationMode.ENABLE_STORAGE:
    renderingIntent += RenderingIntentFlag.ANNOTATIONS_STORAGE;
    annotationStorageSerializable = annotationStorage.serializable; // 序列化表单数据随消息走
    break;
}
if (isEditing) renderingIntent += RenderingIntentFlag.IS_EDITING;
if (isOpList)  renderingIntent += RenderingIntentFlag.OPLIST;
 
const { ids: modifiedIds, hash: modifiedIdsHash } = annotationStorage.modifiedIds;
const cacheKeyBuf = [renderingIntent, annotationStorageSerializable.hash, modifiedIdsHash];
return { renderingIntent, cacheKey: cacheKeyBuf.join("_"), ... };

messageHandler.on("commonobj", ([id, type, exportedData]) => {
  if (this.commonObjs.has(id)) return null; // 去重
  switch (type) {
    case "Font": {
      const font = new FontFaceObject(new FontInfo(exportedData), inspectFont, ...);
      this.fontLoader.bind(font)
        .catch(() => messageHandler.sendWithPromise("FontFallback", { id }))
        .finally(() => {
          if (!font.fontExtraProperties) font.clearData(); // 挂进 DOM 后立即释放字体字节
          this.commonObjs.resolve(id, font);
        });
      break;
    }
    case "CopyLocalImage": /* 跨页复用图片：在页面缓存里找到同 ref 的数据，structuredClone 一份 */ break;
    case "FontPath": this.commonObjs.resolve(id, new FontPathInfo(exportedData)); break;
    case "Image":    this.commonObjs.resolve(id, exportedData); break;
    case "Pattern":  this.commonObjs.resolve(id, new PatternInfo(exportedData).getIR()); break;
  }
  return null;
});

if (pageProxy._intentStates.size === 0) {
  imageData?.bitmap?.close(); // 页面已清理，直接释放 ImageBitmap
  return;
}

saveDocument() {
  const { map, transfer } = this.annotationStorage.serializable;
  return this.messageHandler.sendWithPromise("SaveDocument", {
    isPureXfa: !!this._htmlForXfa,
    numPages: this._numPages,
    annotationStorage: map,
    filename: this.#fullReader?.filename ?? null,
  }, transfer).finally(() => {
    this.annotationStorage.resetModified(); // 无论成败都清「已改动」标记
  });
}

const copyLevel = copyLevels?.[v.pageIndex] ?? 0;
const sourceIdx = mapping[v.pageIndex] - 1;
if (sourceIdx !== v.pageIndex || copyLevel !== 0) {
  remapped.set(k, { ...v, pageIndex: sourceIdx, copyLevel });
  continue;
}

destroy() {
  if (this.destroyCapability) return this.destroyCapability.promise; // 幂等
  this.destroyed = true;
  this.destroyCapability = Promise.withResolvers();
  this.#passwordCapability?.reject(new Error("Worker was destroyed during onPassword callback"));
 
  const waitOn = [];
  for (const page of this.#pageCache.values()) waitOn.push(page._destroy()); // 等所有渲染收尾
  // ... 清缓存、resetModified
  const terminated = this.messageHandler.sendWithPromise("Terminate", null); // 等 worker 长任务结束
  waitOn.push(terminated);
 
  Promise.all(waitOn).then(() => {
    this.commonObjs.clear();
    this.fontLoader.clear();
    this.#methodPromises.clear();
    this.filterFactory.destroy();
    TextLayer.cleanup();
    this.#networkStream?.cancelAllRequests(new AbortException("Worker was terminated."));
    this.messageHandler?.destroy();
    this.messageHandler = null;
    this.destroyCapability.resolve();
  }, this.destroyCapability.reject);
  return this.destroyCapability.promise;
}

class RenderTask {
  onContinue = null; // 每次渲染暂停时调用，参数是「继续」函数
  onError = null;    // 渲染出错/被取消时同步调用
 
  get promise() {
    return this._internalRenderTask.capability.promise;
  }
 
  cancel(extraDelay = 0) {
    this._internalRenderTask.cancel(null, extraDelay);
  }
}

initializeGraphics({ transparency = false, optionalContentConfig }) {
  if (this.cancelled) return;
  if (this._canvas) {
    if (InternalRenderTask.#canvasInUse.has(this._canvas)) {
      throw new Error("Cannot use the same canvas during multiple render() operations. ...");
    }
    InternalRenderTask.#canvasInUse.add(this._canvas);
  }
  const canvasContext = this._canvasContext || this._canvas.getContext("2d", {
    alpha: false,
    willReadFrequently: !this._enableHWA,
  });
  this.gfx = new CanvasGraphics(canvasContext, this.commonObjs, this.objs, ...);
  this.gfx.beginDrawing({ transform, viewport, transparency, background });
  this.operatorListIdx = 0;
  this.graphicsReady = true;
  this.graphicsReadyCallback?.();
}

_scheduleNext() {
  if (this._useRequestAnimationFrame) {
    this.#rAF = window.requestAnimationFrame(() => {
      this.#rAF = null;
      this._nextBound().catch(this._cancelBound);
    });
  } else {
    Promise.resolve().then(this._nextBound).catch(this._cancelBound);
  }
}
 
async _next() {
  if (this.cancelled) return;
  this.operatorListIdx = this.gfx.executeOperatorList(
    this.operatorList, this.operatorListIdx, this._continueBound, this.stepper, this._operationsFilter
  );
  if (this.operatorListIdx === this.operatorList.argsArray.length) {
    this.running = false;
    if (this.operatorList.lastChunk) {
      this.gfx.endDrawing();
      InternalRenderTask.#canvasInUse.delete(this._canvas);
      this.callback(); // 回到 PDFPageProxy.render 里的 complete
    }
  }
}

const version = typeof PDFJSDev !== "undefined" ? PDFJSDev.eval("BUNDLE_VERSION") : null;
const build = typeof PDFJSDev !== "undefined" ? PDFJSDev.eval("BUNDLE_BUILD") : null;