Skip to content

Commit 1f40835

Browse files
wh131462wh131462
committed
docs: 完善 PDF.js 资源配置文档
1 parent 04a1025 commit 1f40835

9 files changed

Lines changed: 176 additions & 48 deletions

File tree

‎packages/angular-file-preview/README.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,29 @@ By default, the component automatically uses unpkg CDN to load PDF.js, no additi
5353
1. Copy PDF.js files to your public directory:
5454

5555
```bash
56-
cp -r node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdfjs/
56+
cp -r node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/
5757
cp -r node_modules/pdfjs-dist/cmaps public/pdfjs/
58+
cp -r node_modules/pdfjs-dist/standard_fonts public/pdfjs/
59+
cp -r node_modules/pdfjs-dist/wasm public/pdfjs/
5860
```
5961

6062
2. Configure PDF.js in your app entry:
6163

6264
```ts
63-
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs';
65+
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
6466
import { configurePdfWorker } from '@eternalheart/angular-file-preview';
6567

6668
configurePdfWorker(pdfjsLib, {
6769
workerSrc: '/pdfjs/pdf.worker.min.mjs',
6870
cMapUrl: '/pdfjs/cmaps/',
6971
cMapPacked: true,
72+
standardFontDataUrl: '/pdfjs/standard_fonts/',
73+
wasmUrl: '/pdfjs/wasm/',
7074
});
7175
```
7276

77+
Call this during client application initialization, before the first PDF render. The worker must use the legacy build matching the installed `pdfjs-dist` version.
78+
7379
#### Auto-copy with Vite (Recommended)
7480

7581
Configure auto-copy in `vite.config.ts`:
@@ -83,12 +89,20 @@ export default defineConfig({
8389
viteStaticCopy({
8490
targets: [
8591
{
86-
src: 'node_modules/pdfjs-dist/build/pdf.worker.min.mjs',
92+
src: 'node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs',
8793
dest: 'pdfjs'
8894
},
8995
{
9096
src: 'node_modules/pdfjs-dist/cmaps',
9197
dest: 'pdfjs'
98+
},
99+
{
100+
src: 'node_modules/pdfjs-dist/standard_fonts',
101+
dest: 'pdfjs'
102+
},
103+
{
104+
src: 'node_modules/pdfjs-dist/wasm',
105+
dest: 'pdfjs'
92106
}
93107
]
94108
})

‎packages/angular-file-preview/README.zh-CN.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,29 @@ import '@eternalheart/angular-file-preview/style.css';
5353
1. 将 PDF.js 文件复制到你的 public 目录：
5454

5555
```bash
56-
cp -r node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdfjs/
56+
cp -r node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/
5757
cp -r node_modules/pdfjs-dist/cmaps public/pdfjs/
58+
cp -r node_modules/pdfjs-dist/standard_fonts public/pdfjs/
59+
cp -r node_modules/pdfjs-dist/wasm public/pdfjs/
5860
```
5961

6062
2. 在应用入口配置 PDF.js：
6163

6264
```ts
63-
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs';
65+
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
6466
import { configurePdfWorker } from '@eternalheart/angular-file-preview';
6567

6668
configurePdfWorker(pdfjsLib, {
6769
workerSrc: '/pdfjs/pdf.worker.min.mjs',
6870
cMapUrl: '/pdfjs/cmaps/',
6971
cMapPacked: true,
72+
standardFontDataUrl: '/pdfjs/standard_fonts/',
73+
wasmUrl: '/pdfjs/wasm/',
7074
});
7175
```
7276

77+
请在客户端应用初始化阶段、首次渲染 PDF 前调用。Worker 必须使用与当前 `pdfjs-dist` 版本匹配的 legacy 构建。
78+
7379
#### 使用 Vite 自动复制（推荐）
7480

7581
在 `vite.config.ts` 中配置自动复制：
@@ -83,12 +89,20 @@ export default defineConfig({
8389
viteStaticCopy({
8490
targets: [
8591
{
86-
src: 'node_modules/pdfjs-dist/build/pdf.worker.min.mjs',
92+
src: 'node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs',
8793
dest: 'pdfjs'
8894
},
8995
{
9096
src: 'node_modules/pdfjs-dist/cmaps',
9197
dest: 'pdfjs'
98+
},
99+
{
100+
src: 'node_modules/pdfjs-dist/standard_fonts',
101+
dest: 'pdfjs'
102+
},
103+
{
104+
src: 'node_modules/pdfjs-dist/wasm',
105+
dest: 'pdfjs'
92106
}
93107
]
94108
})

‎packages/docs/api/types.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -309,29 +309,39 @@ PDF.js 配置选项接口：
309309
310310
```typescript
311311
interface PdfConfigOptions {
312-
workerSrc?: string // PDF.js Worker 文件路径
313-
cMapUrl?: string // CMap 文件路径（多字节字符支持）
314-
cMapPacked?: boolean // 是否使用压缩的 CMap
312+
workerSrc?: string // PDF.js legacy Worker 文件路径
313+
cMapUrl?: string // CMap 文件目录路径（多字节字符支持）
314+
cMapPacked?: boolean // 是否使用压缩的 CMap，默认 true
315+
standardFontDataUrl?: string // PDF.js 标准字体文件目录路径
316+
wasmUrl?: string // PDF.js WASM 文件目录路径
315317
}
316318
```
317319

318320
### 属性说明
319321

320-
- `workerSrc`: 自定义 PDF.js Worker 文件路径，默认从 unpkg CDN 加载
321-
- `cMapUrl`: CMap 文件路径，用于支持 CJK 等多字节字符
322-
- `cMapPacked`: 是否使用压缩格式的 CMap 文件
322+
- `workerSrc`: 自定义 PDF.js legacy Worker 文件路径，默认从 unpkg CDN 加载
323+
- `cMapUrl`: CMap 文件目录路径，用于支持 CJK 等多字节字符，默认从 unpkg CDN 加载
324+
- `cMapPacked`: 是否使用压缩格式的 CMap 文件，默认为 `true`
325+
- `standardFontDataUrl`: PDF.js 标准字体文件目录路径，默认从 unpkg CDN 加载
326+
- `wasmUrl`: PDF.js WASM 文件目录路径，用于 JBIG2、JPEG 2000 等图像解码，默认从 unpkg CDN 加载
323327

324328
### 示例
325329

326330
```typescript
327331
import { configurePdfjs } from '@eternalheart/react-file-preview'
328332

329-
// 使用本地 worker
333+
// 在客户端应用初始化阶段、首次渲染 PDF 前调用
330334
configurePdfjs({
331-
workerSrc: '/pdf.worker.min.mjs'
335+
workerSrc: '/pdfjs/pdf.worker.min.mjs',
336+
cMapUrl: '/pdfjs/cmaps/',
337+
cMapPacked: true,
338+
standardFontDataUrl: '/pdfjs/standard_fonts/',
339+
wasmUrl: '/pdfjs/wasm/',
332340
})
333341
```
334342

343+
`workerSrc` 必须使用与当前 `pdfjs-dist` 版本匹配的 `legacy/build/pdf.worker.min.mjs`。生产、离线或受内容安全策略限制的环境建议将上述资源部署到本地。
344+
335345
## 完整类型定义示例
336346

337347
```typescript

‎packages/docs/api/utils.md‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,7 @@ function processFile(input: PreviewFileInput, index: number) {
255255

256256
## configurePdfjs
257257

258-
配置 PDF.js 的 Worker 和 CMap 设置。
258+
配置 PDF.js 的 Worker、CMap、标准字体和 WASM 资源。该函数仅由 React 包直接导出。
259259

260260
### 签名
261261

@@ -266,31 +266,52 @@ function configurePdfjs(options?: PdfConfigOptions): void
266266
### 参数
267267

268268
- `options` - 可选配置对象：
269-
- `workerSrc`: PDF.js Worker 文件路径
270-
- `cMapUrl`: CMap 文件路径
271-
- `cMapPacked`: 是否使用压缩的 CMap
269+
- `workerSrc`: PDF.js legacy Worker 文件路径
270+
- `cMapUrl`: CMap 文件目录路径
271+
- `cMapPacked`: 是否使用压缩的 CMap，默认为 `true`
272+
- `standardFontDataUrl`: PDF.js 标准字体文件目录路径
273+
- `wasmUrl`: PDF.js WASM 文件目录路径，用于 JBIG2、JPEG 2000 等图像解码
272274

273275
### 示例
274276

275277
```typescript
276278
import { configurePdfjs } from '@eternalheart/react-file-preview'
277279
278-
// 使用本地 Worker 文件
280+
// 在首次渲染 PDF 前配置本地静态资源
279281
configurePdfjs({
280-
workerSrc: '/pdf.worker.min.mjs'
281-
})
282-
283-
// 自定义 CMap 配置
284-
configurePdfjs({
285-
cMapUrl: '/cmaps/',
286-
cMapPacked: true
282+
workerSrc: '/pdfjs/pdf.worker.min.mjs',
283+
cMapUrl: '/pdfjs/cmaps/',
284+
cMapPacked: true,
285+
standardFontDataUrl: '/pdfjs/standard_fonts/',
286+
wasmUrl: '/pdfjs/wasm/',
287287
})
288288
```
289289

290290
::: tip
291-
默认情况下，组件会自动从 unpkg CDN 加载 PDF.js Worker，无需手动配置。仅在需要离线使用或自定义部署时才需要调用此函数。
291+
不传参数时，Worker、CMap、标准字体和 WASM 资源均从 unpkg CDN 加载。生产环境、离线环境或受内容安全策略限制的环境建议部署本地资源。
292292
:::
293293

294+
::: warning
295+
请在客户端应用初始化阶段、首次渲染 PDF 前调用。`workerSrc` 必须指向 `pdfjs-dist/legacy/build/pdf.worker.min.mjs`，并与项目安装的 `pdfjs-dist` 版本保持一致；服务端渲染阶段调用不会生效。
296+
:::
297+
298+
### Vue 与 Angular
299+
300+
Vue 和 Angular 包当前导出框架无关的 `configurePdfWorker`，需要显式传入 PDF.js legacy 模块：
301+
302+
```typescript
303+
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs'
304+
import { configurePdfWorker } from '@eternalheart/vue-file-preview' // Angular 使用对应包名
305+
306+
configurePdfWorker(pdfjsLib, {
307+
workerSrc: '/pdfjs/pdf.worker.min.mjs',
308+
cMapUrl: '/pdfjs/cmaps/',
309+
cMapPacked: true,
310+
standardFontDataUrl: '/pdfjs/standard_fonts/',
311+
wasmUrl: '/pdfjs/wasm/',
312+
})
313+
```
314+
294315
## pdfjs
295316

296317
PDF.js 库的重新导出，可用于高级配置场景。
@@ -412,4 +433,3 @@ const text = await fetchTextUtf8('/api/file/log.txt', { fetcher })
412433

413434
- [组件 API](./components) - 查看组件的完整 API
414435
- [类型定义](./types) - 了解所有类型定义
415-

‎packages/docs/guide/installation.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -85,19 +85,19 @@ import '@eternalheart/angular-file-preview/style.css'
8585

8686
## PDF 支持
8787

88-
组件已内置 PDF.js worker 配置，**无需任何额外配置**。
88+
组件已内置 PDF.js Worker 和文档资源配置，**无需任何额外配置**。
8989

90-
Worker 文件会自动从 CDN 加载，确保：
90+
Worker、CMap、标准字体和 WASM 文件会自动从 CDN 加载，确保：
9191
- <img src="/assets/icons/check.svg" width="18" height="18" style="display:inline;vertical-align:middle" /> 零配置，开箱即用
9292
- <img src="/assets/icons/check.svg" width="18" height="18" style="display:inline;vertical-align:middle" /> 自动匹配 pdfjs-dist 版本
9393
- <img src="/assets/icons/check.svg" width="18" height="18" style="display:inline;vertical-align:middle" /> 稳定可靠的加载方式
9494
- <img src="/assets/icons/check.svg" width="18" height="18" style="display:inline;vertical-align:middle" /> 无需手动复制任何文件
9595

9696
::: tip
97-
组件会自动使用 unpkg CDN 加载 PDF.js worker 文件，无需任何手动配置。
97+
组件会自动使用 unpkg CDN 加载 PDF.js 资源，无需任何手动配置。生产、离线或受内容安全策略限制的环境建议部署本地资源。
9898
:::
9999

100-
如需自定义 worker 路径（例如生产环境用本地静态文件），可在应用入口调用配置函数：
100+
如需使用本地静态资源，请在客户端应用初始化阶段、首次渲染 PDF 前调用配置函数：
101101

102102
::: code-group
103103

@@ -108,33 +108,43 @@ configurePdfjs({
108108
workerSrc: '/pdfjs/pdf.worker.min.mjs',
109109
cMapUrl: '/pdfjs/cmaps/',
110110
cMapPacked: true,
111+
standardFontDataUrl: '/pdfjs/standard_fonts/',
112+
wasmUrl: '/pdfjs/wasm/',
111113
})
112114
```
113115

114116
```ts [Vue 3]
115117
import { configurePdfWorker } from '@eternalheart/vue-file-preview'
116-
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'
118+
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs'
117119

118120
configurePdfWorker(pdfjsLib, {
119121
workerSrc: '/pdfjs/pdf.worker.min.mjs',
120122
cMapUrl: '/pdfjs/cmaps/',
121123
cMapPacked: true,
124+
standardFontDataUrl: '/pdfjs/standard_fonts/',
125+
wasmUrl: '/pdfjs/wasm/',
122126
})
123127
```
124128

125129
```ts [Angular]
126130
import { configurePdfWorker } from '@eternalheart/angular-file-preview'
127-
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'
131+
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs'
128132

129133
configurePdfWorker(pdfjsLib, {
130134
workerSrc: '/pdfjs/pdf.worker.min.mjs',
131135
cMapUrl: '/pdfjs/cmaps/',
132136
cMapPacked: true,
137+
standardFontDataUrl: '/pdfjs/standard_fonts/',
138+
wasmUrl: '/pdfjs/wasm/',
133139
})
134140
```
135141

136142
:::
137143

144+
::: warning
145+
`workerSrc` 必须指向与当前 `pdfjs-dist` 版本匹配的 `legacy/build/pdf.worker.min.mjs`。服务端渲染阶段调用配置函数不会生效。
146+
:::
147+
138148
## 验证安装
139149

140150
::: code-group

‎packages/react-file-preview/README.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,10 @@ By default, the component automatically uses unpkg CDN to load PDF.js, no additi
5757

5858
```bash
5959
# Copy PDF.js files from node_modules to public directory
60-
cp -r node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdfjs/
60+
cp -r node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/
6161
cp -r node_modules/pdfjs-dist/cmaps public/pdfjs/
62+
cp -r node_modules/pdfjs-dist/standard_fonts public/pdfjs/
63+
cp -r node_modules/pdfjs-dist/wasm public/pdfjs/
6264
```
6365

6466
2. Configure PDF.js in your app entry:
@@ -70,7 +72,9 @@ import { configurePdfjs } from '@eternalheart/react-file-preview';
7072
configurePdfjs({
7173
workerSrc: '/pdfjs/pdf.worker.min.mjs',
7274
cMapUrl: '/pdfjs/cmaps/',
73-
cMapPacked: true
75+
cMapPacked: true,
76+
standardFontDataUrl: '/pdfjs/standard_fonts/',
77+
wasmUrl: '/pdfjs/wasm/'
7478
});
7579
```
7680

@@ -87,12 +91,20 @@ export default defineConfig({
8791
viteStaticCopy({
8892
targets: [
8993
{
90-
src: 'node_modules/pdfjs-dist/build/pdf.worker.min.mjs',
94+
src: 'node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs',
9195
dest: 'pdfjs'
9296
},
9397
{
9498
src: 'node_modules/pdfjs-dist/cmaps',
9599
dest: 'pdfjs'
100+
},
101+
{
102+
src: 'node_modules/pdfjs-dist/standard_fonts',
103+
dest: 'pdfjs'
104+
},
105+
{
106+
src: 'node_modules/pdfjs-dist/wasm',
107+
dest: 'pdfjs'
96108
}
97109
]
98110
})
@@ -108,10 +120,14 @@ import { configurePdfjs } from '@eternalheart/react-file-preview';
108120
configurePdfjs({
109121
workerSrc: '/pdfjs/pdf.worker.min.mjs',
110122
cMapUrl: '/pdfjs/cmaps/',
111-
cMapPacked: true
123+
cMapPacked: true,
124+
standardFontDataUrl: '/pdfjs/standard_fonts/',
125+
wasmUrl: '/pdfjs/wasm/'
112126
});
113127
```
114128

129+
Call this during client application initialization, before the first PDF render. The worker must use the legacy build matching the installed `pdfjs-dist` version.
130+
115131
### Vite Bundler Note (AVIF Decoder)
116132

117133
If your project bundler is Vite and you happen to have `@jsquash/avif` installed (transitively or directly), the production build may fail with:

0 commit comments

Comments
 (0)