簡(jiǎn)介PDF.js Demo是一套基于Mozilla開源PDF.js庫的純JavaScript示例工程面向前端開發(fā)者和需要為網(wǎng)站嵌入文檔預(yù)覽功能的技術(shù)人員解決瀏覽器中無需插件即可實(shí)現(xiàn)PDF在線預(yù)覽、頁面縮放、本地文件加載與打印調(diào)用等核心問題適合OA系統(tǒng)、電子合同預(yù)覽、在線課堂資料展示等場(chǎng)景。資源壓縮包約2.49MB共376個(gè)文件核心包括字形映射、屬性配置、圖片圖標(biāo)、腳本文件與HTML示例頁面另附PDF參考文檔和工程配置文件便于對(duì)照查閱與二次開發(fā)。已有9926人學(xué)習(xí)下載。示例除了展現(xiàn)基礎(chǔ)渲染流程外還實(shí)現(xiàn)了動(dòng)態(tài)縮放、通過File API讀取本地PDF以及與瀏覽器打印接口結(jié)合的實(shí)用邏輯同時(shí)涵蓋緩存頁面、分頁加載、使用Web Worker后臺(tái)解析等性能優(yōu)化要點(diǎn)并配有目錄結(jié)構(gòu)說明和代碼注釋適合作為在線文檔方案的技術(shù)藍(lán)本。1. 純JS PDF在線預(yù)覽指北為何選擇pdf.js以及它到底能解決什么如果你接手過“要在網(wǎng)頁里打開PDF但不想加載插件、不想裝控件”的需求大概率會(huì)繞到pdf.js這條路上來。它是純前端解析PDF并渲染到canvas的開源方案只要瀏覽器支持ES5以上和canvas就能把PDF文件變成可交互的頁面同時(shí)支持打印、文本選中、搜索這些原生體驗(yàn)。最關(guān)鍵的是它不依賴后端轉(zhuǎn)換直接喂它文件路徑或二進(jìn)制流就能工作。如果你是做內(nèi)部系統(tǒng)、文件管理平臺(tái)或者教育類工具的開發(fā)這套方案能省掉一整套在線預(yù)覽服務(wù)配合打印接口還能把“預(yù)覽”和“打印”統(tǒng)一交給前端處理。下面我以一份可運(yùn)行的demo為基準(zhǔn)從零拆解它怎么跑起來以及在真實(shí)項(xiàng)目中哪些參數(shù)值得調(diào)、哪些坑必須繞開。2. 快速搭一個(gè)預(yù)覽Demo引入、初始化和第一屏渲染2.1 引入方式從CDN拉全量版還是自托管文件pdf.js的官方分發(fā)包含三個(gè)入口pdf.js主文件、pdf.worker.js工作線程文件以及可選的cmaps字符映射目錄。在demo里最省事的方式是直接引用CDN上的固定版本比如在html里這樣寫script srchttps://unpkg.com/pdfjs-dist2.16.105/build/pdf.min.js/script但需要注意pdf.js內(nèi)部會(huì)嘗試從與主文件相同的目錄加載worker文件。如果你只引入主文件它會(huì)在運(yùn)行時(shí)發(fā)一個(gè)動(dòng)態(tài)請(qǐng)求去拉pdf.worker.js。我在實(shí)際項(xiàng)目里習(xí)慣把兩個(gè)文件都下載到本地靜態(tài)目錄然后手動(dòng)指定worker路徑這樣可以避免CDN版本更新導(dǎo)致行為變化。指定方式如下pdfjsLib.GlobalWorkerOptions.workerSrc /assets/pdfjs/pdf.worker.min.js;這里的邏輯是pdf.js在解析PDF時(shí)有一部分計(jì)算密集的任務(wù)放在Worker線程里執(zhí)行workerSrc就是告訴主線程“去哪里拿這個(gè)線程的代碼”。如果不設(shè)置它會(huì)默認(rèn)從主文件所在目錄找一旦你把主文件和worker文件放在不同地方初始化就會(huì)失敗。設(shè)置路徑時(shí)建議用絕對(duì)路徑或相對(duì)站點(diǎn)根的路徑避免嵌套路由下路徑解析出錯(cuò)。2.2 初始化PDF文檔getDocument的輸入格式與Promise鏈拿到文件路徑或File對(duì)象之后調(diào)用pdfjsLib.getDocument()創(chuàng)建加載任務(wù)。這個(gè)函數(shù)返回的是PDFDocumentProxy的Promise后續(xù)所有操作都必須掛在它后面const loadingTask pdfjsLib.getDocument({ url: /uploads/sample.pdf, cMapUrl: /assets/pdfjs/cmaps/, cMapPacked: true, }); loadingTask.promise.then(pdf { console.log(頁數(shù):, pdf.numPages); return pdf.getPage(1); }).then(page { // 拿到page對(duì)象后進(jìn)行渲染 }).catch(err { console.error(加載失敗:, err.message); });這里面有兩點(diǎn)要說明第一getDocument返回的是PDFDocumentLoadingTask別直接拿這個(gè)對(duì)象去調(diào)用getPage必須先通過.promise屬性獲取到proxy。第二cMapUrl和cMapPacked是給包含特定字體的PDF用的比如某些CJK中日韓字體。如果你不設(shè)置這兩個(gè)參數(shù)遇到這類文檔時(shí)字形會(huì)顯示成亂碼或者方框。我一般會(huì)在demo里直接帶上cmaps目錄雖然體積多了幾MB但換來的是渲染正確率這筆賬劃算。2.3 渲染第一頁從page到canvas的完整鏈路獲取到PDFPageProxy對(duì)象后渲染的核心是把PDF頁面繪制到canvas上。這一步靠page.render()方法完成它接收一個(gè)RenderParameters對(duì)象。下面是最基礎(chǔ)的第一頁渲染代碼const canvas document.getElementById(pdf-canvas); const ctx canvas.getContext(2d); const viewport page.getViewport({ scale: 1.5 }); canvas.width viewport.width; canvas.height viewport.height; const renderTask page.render({ canvasContext: ctx, viewport: viewport, }); renderTask.promise.then(() { console.log(第一頁渲染完成); });這里的關(guān)鍵在viewport。PDF是一種矢量格式頁面尺寸是用point1/72英寸定義的而canvas需要像素尺寸。getViewport({ scale })的作用就是定義一個(gè)縮放比例把PDF坐標(biāo)換算成canvas像素。scale1.5表示把頁面放大50%顯示。你需要先算好寬高再設(shè)置canvas的width和height否則畫布尺寸和viewport不匹配畫出來的內(nèi)容會(huì)變形或截?cái)?。另外render()返回的renderTask是一個(gè)帶promise的對(duì)象渲染過程中也可以調(diào)用cancel()取消這在翻頁特別快的場(chǎng)景下很有用能避免舊頁面渲染阻塞新頁面。3. 多頁、縮放、旋轉(zhuǎn)與頁碼控制把Demo擴(kuò)展成可用的預(yù)覽器3.1 多頁渲染連續(xù)滾動(dòng)與單頁切換兩種布局demo如果只渲染第一頁那還談不上“預(yù)覽器”。真實(shí)系統(tǒng)里至少要讓用戶能翻頁或者滾動(dòng)瀏覽。這里有兩種常見做法一種是類似閱讀器的單頁模式底部放“上一頁/下一頁”按鈕另一種是類似PDF閱讀軟件的連續(xù)滾動(dòng)模式把所有頁先后渲染到同一個(gè)滾動(dòng)容器里。單頁模式的好處是每次只渲染一頁內(nèi)存開銷小實(shí)現(xiàn)也簡(jiǎn)單let currentPage 1; const totalPages pdf.numPages; function renderPage(pageNum) { return pdf.getPage(pageNum).then(page { const scale 1.2; const viewport page.getViewport({ scale }); canvas.width viewport.width; canvas.height viewport.height; return page.render({ canvasContext: ctx, viewport, }).promise; }); } document.getElementById(next).addEventListener(click, () { if (currentPage totalPages) { currentPage; renderPage(currentPage); } });這段代碼里要注意的是renderPage每次都會(huì)重新設(shè)置canvas尺寸。如果你在getPage和render之間沒有把canvas尺寸重置渲染結(jié)果會(huì)被拉伸。我一般會(huì)在切換頁面時(shí)先清除畫布ctx.clearRect再把新的viewport尺寸賦給canvas防止上一次的殘留影像干擾視覺。連續(xù)滾動(dòng)模式則更復(fù)雜一點(diǎn)。你需要?jiǎng)討B(tài)判斷“哪一頁進(jìn)入視口”然后懶加載渲染。常見做法是監(jiān)聽滾動(dòng)事件計(jì)算當(dāng)前滾動(dòng)偏移量對(duì)應(yīng)的頁數(shù)再調(diào)用getPage去渲染可視區(qū)域周圍的頁面超出視口的頁面移除canvas節(jié)點(diǎn)釋放內(nèi)存。這個(gè)方案對(duì)長(zhǎng)文檔友好但增量渲染和DOM回收邏輯需要仔細(xì)寫否則滾動(dòng)快時(shí)頁面會(huì)閃白。3.2 縮放與旋轉(zhuǎn)viewport參數(shù)附近的細(xì)節(jié)viewport不只是scale一個(gè)屬性它還包含旋轉(zhuǎn)角度。PDF內(nèi)部可以通過page.rotate屬性指定頁面本身的旋轉(zhuǎn)角度getViewport默認(rèn)會(huì)尊重這個(gè)角度。如果你想讓用戶手動(dòng)旋轉(zhuǎn)需要傳第二個(gè)參數(shù)rotationconst viewport page.getViewport({ scale: currentScale, rotation: currentRotation, // 90的整數(shù)倍 });注意到一個(gè)容易出錯(cuò)的地方rotation是在原始旋轉(zhuǎn)基礎(chǔ)上的增量不是“重置”。如果PDF本身已經(jīng)是90度方向你傳rotation90會(huì)變成180度。所以做旋轉(zhuǎn)功能時(shí)要先把page.rotate讀到并保存然后在此基礎(chǔ)上累加。另外縮放時(shí)不要只改scale然后就重新渲染必須同時(shí)更新canvas的寬高否則畫布內(nèi)部用了ctx.scale的話會(huì)出現(xiàn)“畫布CSS尺寸不變但內(nèi)部像素變化”的模糊現(xiàn)象。我現(xiàn)在實(shí)踐中的做法是維護(hù)一份當(dāng)前狀態(tài)對(duì)象const state { scale: 1.0, rotation: 0, pageNum: 1, }; function applyViewport(page) { const baseRotation page.rotate || 0; const viewport page.getViewport({ scale: state.scale, rotation: (baseRotation state.rotation) % 360, }); canvas.width viewport.width; canvas.height viewport.height; return viewport; }這么做的好處是每次渲染時(shí)都從原始頁面狀態(tài)計(jì)算避免上一次操作污染下一次結(jié)果。3.3 文本層讓預(yù)覽支持復(fù)制、搜索與無障礙閱讀純canvas渲染出的PDF只是一張圖片用戶無法選中文字瀏覽器搜索自然也找不到內(nèi)容。這在文檔管理系統(tǒng)里幾乎是不可接受的缺點(diǎn)。解決方案是加一層“文本層”text layer。pdf.js的API暴露了page.getTextContent()方法可以把頁面里的文字塊抽出來再通過TextLayerBuilder這個(gè)工具類把它們渲染成一個(gè)覆蓋在canvas上的透明層。import { TextLayerBuilder } from pdfjs-dist/lib/web/text_layer_builder; const textLayerDiv document.getElementById(text-layer); const textContent await page.getTextContent(); const textLayer new TextLayerBuilder({ textLayerDiv, pageIndex: page.pageNumber - 1, viewport: viewport, }); textLayer.setTextContent(textContent); textLayer.setViewport(viewport); textLayer.render();注意text layer構(gòu)建器的pageIndex從0開始而page.pageNumber從1開始不減去1的話會(huì)導(dǎo)致文本層錯(cuò)位。這個(gè)mapper類在官方示例里有但很多人下載的demo里沒有包含它復(fù)制代碼時(shí)容易漏。裝了文本層后你要保證它的z-index高于canvas但低于頁面上的其他按鈕。另外縮放時(shí)文本層要重新計(jì)算所有文字的位置例如我一般會(huì)在縮放結(jié)束后調(diào)用textLayer.setViewport(viewport)再做一次渲染。4. 打印實(shí)現(xiàn)用pdf.js的print模塊還是自己拼iframe4.1 內(nèi)置print方法的邊界它其實(shí)是在“另起爐灶”pdf.js在官方web/viewer.html里自帶打印功能如果你直接把整個(gè)viewer嵌入站點(diǎn)可以參考它的實(shí)現(xiàn)。它內(nèi)部的邏輯大致是重新創(chuàng)建所有頁的canvas計(jì)算一套適合打印的viewport然后調(diào)用document.execCommand(print)或者h(yuǎn)ostContainer.print()。但在你自己的demo里如果只引入核心庫是沒有這個(gè)能力的。你需要自己寫打印入口。我見過不少開發(fā)者試圖從pdfjsLib里找出.print()方法但在核心包里確實(shí)沒有。核心庫提供的只是解析、渲染和文本提取打印是viewer那層的事。所以如果你在自定義預(yù)覽界面做打印需要走下面的路線。4.2 自建iframe打印從canvas到打印文檔的轉(zhuǎn)換流程最穩(wěn)妥的做法是構(gòu)造一個(gè)隱藏的iframe把要打印的PDF頁面依次渲染成canvas然后把canvas轉(zhuǎn)成圖片塞進(jìn)iframe的document.body里最后調(diào)用iframe的contentWindow.print()。下面是精簡(jiǎn)版代碼async function printPdf(pdf) { // 1. 創(chuàng)建隱藏iframe const iframe document.createElement(iframe); iframe.style.display none; document.body.appendChild(iframe); const win iframe.contentWindow; const doc win.document; doc.write(htmlheadtitleprint/title/headbody/body/html); doc.close(); // 2. 逐頁渲染為canvas轉(zhuǎn)圖片 for (let i 1; i pdf.numPages; i) { const page await pdf.getPage(i); // 打印用的scale建議用1或1.5太高會(huì)導(dǎo)致圖片體積巨大 const viewport page.getViewport({ scale: 1.5 }); const canvas document.createElement(canvas); canvas.width viewport.width; canvas.height viewport.height; const ctx canvas.getContext(2d); await page.render({ canvasContext: ctx, viewport }).promise; const img doc.createElement(img); img.src canvas.toDataURL(image/jpeg, 0.9); doc.body.appendChild(img); } // 3. 延遲打印等待圖片加載完成 setTimeout(() { win.print(); document.body.removeChild(iframe); }, 500); }這段代碼有三個(gè)實(shí)際問題第一canvas.toDataURL()對(duì)大頁面會(huì)產(chǎn)生很長(zhǎng)的base64字符串內(nèi)存壓力大時(shí)可能卡頓。建議改成canvas.toBlob()然后用URL.createObjectURL()賦給img.src。第二打印時(shí)iframe內(nèi)的樣式要額外寫一點(diǎn)比如page { margin: 0 }能去掉默認(rèn)邊距img { width: 100%; page-break-after: always; }能保證每張圖片獨(dú)占一頁。第三不要立刻調(diào)用print()要給瀏覽器一點(diǎn)時(shí)間加載圖片否則可能出現(xiàn)空白頁。延遲500ms是經(jīng)驗(yàn)值圖片多時(shí)我會(huì)用img.onload計(jì)數(shù)來替代固定延時(shí)。4.3 打印參數(shù)控制窗口、頁面方向和縮放規(guī)則到了打印對(duì)話框這一步頁面方向、頁邊距這些其實(shí)是用戶自己控制的。你可以通過CSSpage規(guī)則做少量干預(yù)例如強(qiáng)制A4縱向page { size: A4 portrait; margin: 10mm; }但要注意page的size在Chrome和Firefox的渲染支持不一致。Firefox對(duì)size: A4有明顯支持Chrome在打印預(yù)覽里也會(huì)讀取這個(gè)值。如果你的用戶群體里裝了老版本瀏覽器這些規(guī)則可能被忽略所以不要完全依賴CSS最好在iframe的圖片里直接用width: 100%做自適應(yīng)。另外一個(gè)細(xì)節(jié)是打印范圍全部頁還是當(dāng)前頁需要通過win.print()的前置邏輯控制比如只把要打印的頁面渲染到iframe而不是打印全部。我一般會(huì)在函數(shù)參數(shù)里加一個(gè)range數(shù)組比如[1,3,5]代表只打印這幾頁這樣既控制范圍也避免打印太多頁面導(dǎo)致內(nèi)存溢出。5. 常見問題與避坑指南我從三個(gè)項(xiàng)目里挖出來的坑5.1 跨域Worker加載失敗不是所有報(bào)錯(cuò)都叫CORS現(xiàn)象控制臺(tái)報(bào)錯(cuò)信息類似Failed to fetch dynamically imported module或者worker file not found頁面一直在加載中canvas始終空白。原因pdf.js在加載worker時(shí)采用動(dòng)態(tài)import機(jī)制如果你的站點(diǎn)是http://a.com而worker路徑配置成了http://b.com/assets/pdf.worker.min.js瀏覽器出于跨域限制拒絕拉取。還有一種情況是本地開發(fā)用file://協(xié)議打開頁面動(dòng)態(tài)import受CORS策略限制同樣失敗。解決把GlobalWorkerOptions.workerSrc改成和頁面同域的相對(duì)路徑例如從/assets/開始。同時(shí)確認(rèn)你的服務(wù)器對(duì).js文件返回的Content-Type是application/javascript不是text/plain。排查時(shí)先打開Network面板看worker請(qǐng)求是不是401或CORS error。另外如果你把pdf.js構(gòu)建成分離的獨(dú)立包也要檢查打包后worker路徑是否被混淆器改動(dòng)了。5.2 渲染大文件時(shí)內(nèi)存一直漲canvas和Promise順序都沒管好現(xiàn)象打開一份幾十MB的PDF翻頁二三十次后頁面開始卡頓甚至瀏覽器標(biāo)簽頁崩潰。原因每一頁渲染都會(huì)創(chuàng)建一個(gè)canvas元素如果你切換頁時(shí)只把舊的canvas隱藏掉而不移除它的像素?cái)?shù)據(jù)仍然占用內(nèi)存。而且fetch和getPage返回的Promise如果沒有及時(shí)處理會(huì)保持文檔對(duì)象不釋放。核心庫本身會(huì)緩存頁面數(shù)據(jù)但你調(diào)用pdf.destroy()之前這些緩存一直存在。解決每次渲染完成后把不再可見的canvas的width和height置為0或者直接從DOM上移除。對(duì)于連續(xù)滾動(dòng)模式要在滾動(dòng)過程中動(dòng)態(tài)回收離屏頁面。另外在單頁應(yīng)用里路由離開預(yù)覽頁面時(shí)務(wù)必調(diào)用pdf.destroy()和loadingTask.destroy()把文檔引用清掉。如果你同時(shí)監(jiān)聽了progress事件記得移除監(jiān)聽器不然也會(huì)形成閉包引用。5.3 文本層錯(cuò)位特別是混合字體和跨頁文字現(xiàn)象安裝了文本層后復(fù)制文字時(shí)看到的文字位置和canvas里對(duì)應(yīng)位置對(duì)不上或者選中某段文字時(shí)高亮區(qū)域偏移了幾個(gè)像素。原因多數(shù)情況下是因?yàn)関iewport不一致。渲染canvas時(shí)用了一套scale而文本層渲染時(shí)用了另一套scale或者你在window.resize后沒有重置兩個(gè)viewport。另外某些字體本身帶glyph偏移pdf.js的文本層對(duì)這部分字體的還原偏差比較大。解決把canvas和文本層放進(jìn)同一個(gè)父容器用兩套完全相同的viewport參數(shù)分別調(diào)用setViewport。關(guān)鍵點(diǎn)是文本層的定位基于viewport的width/height和transform你可以在渲染文本層前先textLayerDiv.style.width viewport.width px、height同理。我在demo里會(huì)在縮放按鈕的回調(diào)里同時(shí)更新canvas和文本層并強(qiáng)制加一行textLayer.reset()再重建避免編輯器復(fù)用舊狀態(tài)。5.4 打印出來的圖片發(fā)虛或者被拉伸現(xiàn)象iframe里看到的圖片是清晰的但打印出來模糊或者一張圖被切成了兩頁。原因打印分辨率取決于canvas的像素大小。如果你用scale1即72dpi渲染打印到紙上會(huì)明顯偏虛因?yàn)槠聊环直媛屎痛蛴C(jī)分辨率不對(duì)等。另一方面如果img的CSS設(shè)了width:100%而原圖本身寬度就不足打印機(jī)會(huì)以物理尺寸輸出就會(huì)發(fā)虛。解決打印渲染的canvas建議用scale1.5或2對(duì)應(yīng)150dpi到300dpi。另外在iframe的CSS里設(shè)置page { size: auto; }同時(shí)給img加image-rendering: pixelated的逆操作——實(shí)際上應(yīng)該去掉這個(gè)屬性保持默認(rèn)的平滑縮放。每次打印前我用一張白底測(cè)試頁先試打確認(rèn)邊距和縮放正常后再進(jìn)入批量打印邏輯。6. 進(jìn)階性能優(yōu)化與移動(dòng)端適配的幾個(gè)實(shí)用技巧如果你準(zhǔn)備把demo擴(kuò)展到生產(chǎn)環(huán)境有幾件小事值得在代碼里提前布局。第一件是虛擬滾動(dòng)。連續(xù)滾動(dòng)模式下渲染全部頁面是災(zāi)難比如300頁的文檔。我一般會(huì)在滾動(dòng)容器內(nèi)只保留約3個(gè)canvas節(jié)點(diǎn)當(dāng)前可視頁、前一頁和后一頁其他區(qū)域用占位div撐起高度。核心思想是維護(hù)一個(gè)pages[pageNum]緩存里面存“是否已渲染”標(biāo)志滾動(dòng)時(shí)對(duì)比新頁碼和當(dāng)前渲染集合差的就卸載。占位div的高度計(jì)算公式為viewport.height / scale乘上縮放系數(shù)這樣滾動(dòng)條的位置始終正確。這么做的好處是內(nèi)存占用從“所有頁”降到“3頁”壞處是滾動(dòng)條跳躍感需要微調(diào)比如預(yù)先渲染未來兩頁能緩解白閃。第二件是移動(dòng)端適配。觸摸設(shè)備的縮放習(xí)慣和桌面完全不同雙指縮放事件會(huì)間接觸發(fā)多次resize。我會(huì)在觸摸開始和結(jié)束之間停掉所有渲染任務(wù)用一個(gè)requestAnimationFrame來合并縮放請(qǐng)求。另外移動(dòng)端的canvas不要設(shè)devicePixelRatio之外的額外放大倍數(shù)我在iPhone上用2倍像素渲染會(huì)直接卡死后來限制最高scale為2給用戶一個(gè)“高清模式”開關(guān)默認(rèn)走1.5。第三件是文本搜索和鏈接跳轉(zhuǎn)。pdf.js的getTextContent返回的對(duì)象里有items數(shù)組每個(gè)item帶str和transform矩陣。我利用這些數(shù)據(jù)實(shí)現(xiàn)了簡(jiǎn)單的定位跳轉(zhuǎn)用戶點(diǎn)搜索結(jié)果時(shí)找到那條item的transform[4]和transform[5]x和y坐標(biāo)再用viewport的convertToViewportPoint方法映射到canvas像素位置最后用canvas.scrollIntoView({ block: center })。這個(gè)功能的坑在于搜索結(jié)果可能有重復(fù)位置在縮放后要重新計(jì)算。最后給PDF渲染加一個(gè)進(jìn)度提示其實(shí)很有價(jià)值。getDocument的loadingTask可以通過onProgress拿到加載進(jìn)度但真正耗時(shí)的是渲染我一般用page.render().promise加一個(gè)requestAnimationFrame計(jì)時(shí)超過300ms就顯示“正在解析復(fù)雜頁面”。這個(gè)優(yōu)化沒有高深技術(shù)但能顯著降低用戶等待時(shí)的焦慮感。從第一個(gè)demo到上線我唯一堅(jiān)持的習(xí)慣是每次改動(dòng)渲染相關(guān)代碼后強(qiáng)制自己用一份包含圖表、大字體和掃描文件的PDF做回歸測(cè)試看看canvas尺寸、文本層和打印結(jié)果是否保持穩(wěn)定。這比任何單元測(cè)試都靠譜因?yàn)閜df.js在不同文檔上的行為差異實(shí)在太多。希望這份折騰筆記能幫到你少走幾步我當(dāng)年踩過的彎路。本文還有配套的精品資源點(diǎn)擊獲取