jit-viewer 1.1.1 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +807 -63
  2. package/README.zh-CN.md +460 -0
  3. package/package.json +2 -1
@@ -0,0 +1,460 @@
1
+ # jit-viewer 中文文档
2
+
3
+ 跨框架文档预览 SDK,支持 PDF、DOCX、XLSX/XLS、PPTX/PPT、OFD、TXT、Markdown、HTML、图片等多种格式,并内置文档水印能力。
4
+
5
+ [Back to English](./README.md)
6
+
7
+ ## 特性
8
+
9
+ - 多格式预览:PDF、Office、OFD、Markdown、HTML、图片
10
+ - 跨框架使用:Vue 3、React、原生 HTML/JS
11
+ - 内置工具栏:缩放、旋转、打印、下载、分页
12
+ - 主题与国际化:浅色 / 深色,中文 / 英文
13
+ - 水印能力:文本水印、图片水印、透明度、旋转、平铺间距、顶层/底层显示
14
+ - 支持本地文件、远程 URL、Blob、ArrayBuffer、自定义请求适配器
15
+
16
+ ## 安装
17
+
18
+ ```bash
19
+ # npm
20
+ npm install jit-viewer
21
+
22
+ # yarn
23
+ yarn add jit-viewer
24
+
25
+ # pnpm
26
+ pnpm add jit-viewer
27
+ ```
28
+
29
+ ## 快速开始
30
+
31
+ ### Vue 3
32
+
33
+ ```vue
34
+ <template>
35
+ <div ref="containerRef" class="viewer-container"></div>
36
+ </template>
37
+
38
+ <script setup lang="ts">
39
+ import { onMounted, onUnmounted, ref } from 'vue'
40
+ import { createViewer } from 'jit-viewer'
41
+ import 'jit-viewer/style.css'
42
+
43
+ const containerRef = ref<HTMLElement | null>(null)
44
+ let viewer: ReturnType<typeof createViewer> | null = null
45
+
46
+ onMounted(() => {
47
+ viewer = createViewer({
48
+ target: containerRef.value!,
49
+ file: '/demo/test.pdf',
50
+ toolbar: true,
51
+ theme: 'light',
52
+ locale: 'zh-CN',
53
+ width: '100%',
54
+ height: 640
55
+ })
56
+
57
+ viewer.mount()
58
+ })
59
+
60
+ onUnmounted(() => {
61
+ viewer?.destroy()
62
+ })
63
+ </script>
64
+ ```
65
+
66
+ ### React
67
+
68
+ ```tsx
69
+ import { useEffect, useRef } from 'react'
70
+ import { createViewer, type ViewerInstance } from 'jit-viewer'
71
+ import 'jit-viewer/style.css'
72
+
73
+ export default function App() {
74
+ const containerRef = useRef<HTMLDivElement | null>(null)
75
+ const viewerRef = useRef<ViewerInstance | null>(null)
76
+
77
+ useEffect(() => {
78
+ if (!containerRef.current) return
79
+
80
+ viewerRef.current = createViewer({
81
+ target: containerRef.current,
82
+ file: '/demo/test.pdf',
83
+ toolbar: true,
84
+ height: 640
85
+ })
86
+
87
+ viewerRef.current.mount()
88
+
89
+ return () => viewerRef.current?.destroy()
90
+ }, [])
91
+
92
+ return <div ref={containerRef} style={{ width: '100%', height: 640 }} />
93
+ }
94
+ ```
95
+
96
+ ### 原生 HTML / JS
97
+
98
+ ```html
99
+ <!DOCTYPE html>
100
+ <html lang="zh-CN">
101
+ <head>
102
+ <meta charset="UTF-8" />
103
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
104
+ <title>JitViewer Demo</title>
105
+ <link rel="stylesheet" href="https://unpkg.com/jit-viewer/dist/iife/jit-viewer.min.css" />
106
+ </head>
107
+ <body>
108
+ <div id="viewer" style="width:100%;height:640px;"></div>
109
+
110
+ <script src="https://unpkg.com/jit-viewer/dist/iife/jit-viewer.min.js"></script>
111
+ <script>
112
+ const viewer = JitViewer.createViewer({
113
+ target: '#viewer',
114
+ file: '/demo/test.pdf',
115
+ toolbar: true,
116
+ theme: 'light',
117
+ locale: 'zh-CN',
118
+ width: '100%',
119
+ height: 640
120
+ })
121
+
122
+ viewer.mount()
123
+ </script>
124
+ </body>
125
+ </html>
126
+ ```
127
+
128
+ ## 水印使用
129
+
130
+ 水印通过 `ViewerOptions.watermark` 配置,支持文本水印和图片水印。水印只作用于预览层,不会修改原始文件内容。
131
+
132
+ ### 文本水印
133
+
134
+ ```ts
135
+ import { createViewer } from 'jit-viewer'
136
+ import 'jit-viewer/style.css'
137
+
138
+ const viewer = createViewer({
139
+ target: '#viewer',
140
+ file: '/demo/confidential.pdf',
141
+ toolbar: true,
142
+ watermark: {
143
+ type: 'text',
144
+ content: '内部资料 严禁外传',
145
+ fontSize: 20,
146
+ color: '#bfbfbf',
147
+ opacity: 0.22,
148
+ rotate: -25,
149
+ gapX: 140,
150
+ gapY: 90,
151
+ position: 'top'
152
+ }
153
+ })
154
+
155
+ viewer.mount()
156
+ ```
157
+
158
+ ### 图片水印
159
+
160
+ ```ts
161
+ import { createViewer } from 'jit-viewer'
162
+ import 'jit-viewer/style.css'
163
+
164
+ const viewer = createViewer({
165
+ target: '#viewer',
166
+ file: '/demo/report.pdf',
167
+ watermark: {
168
+ type: 'image',
169
+ image: '/assets/company-logo.png',
170
+ imageWidth: 96,
171
+ imageHeight: 96,
172
+ opacity: 0.16,
173
+ rotate: -20,
174
+ gapX: 180,
175
+ gapY: 120,
176
+ position: 'bottom'
177
+ }
178
+ })
179
+
180
+ viewer.mount()
181
+ ```
182
+
183
+ ### Vue 组件方式
184
+
185
+ ```vue
186
+ <template>
187
+ <Viewer
188
+ :file="file"
189
+ :toolbar="true"
190
+ :theme="'light'"
191
+ :locale="'zh-CN'"
192
+ :watermark="watermark"
193
+ width="100%"
194
+ height="640px"
195
+ />
196
+ </template>
197
+
198
+ <script setup lang="ts">
199
+ import { ref } from 'vue'
200
+ import { Viewer } from 'jit-viewer'
201
+ import 'jit-viewer/style.css'
202
+
203
+ const file = ref('/demo/test.pdf')
204
+
205
+ const watermark = ref({
206
+ type: 'text' as const,
207
+ content: 'JitViewer Demo',
208
+ fontSize: 18,
209
+ color: '#9aa5b1',
210
+ opacity: 0.18,
211
+ rotate: -30,
212
+ gapX: 120,
213
+ gapY: 80,
214
+ position: 'top' as const
215
+ })
216
+ </script>
217
+ ```
218
+
219
+ ### 动态切换不同水印
220
+
221
+ ```ts
222
+ import { createViewer, type ViewerInstance, type ViewerOptions } from 'jit-viewer'
223
+
224
+ let viewer: ViewerInstance | null = null
225
+
226
+ const baseOptions: ViewerOptions = {
227
+ target: '#viewer',
228
+ file: '/demo/test.pdf',
229
+ toolbar: true,
230
+ width: '100%',
231
+ height: 640
232
+ }
233
+
234
+ function renderWithWatermark(watermark: ViewerOptions['watermark']) {
235
+ viewer?.destroy()
236
+
237
+ viewer = createViewer({
238
+ ...baseOptions,
239
+ watermark
240
+ })
241
+
242
+ viewer.mount()
243
+ }
244
+
245
+ renderWithWatermark({
246
+ type: 'text',
247
+ content: '首次预览',
248
+ opacity: 0.2,
249
+ rotate: -20,
250
+ gapX: 140,
251
+ gapY: 90
252
+ })
253
+
254
+ document.querySelector('#switchImage')?.addEventListener('click', () => {
255
+ renderWithWatermark({
256
+ type: 'image',
257
+ image: '/assets/logo.png',
258
+ imageWidth: 88,
259
+ imageHeight: 88,
260
+ opacity: 0.14,
261
+ rotate: -18,
262
+ gapX: 170,
263
+ gapY: 110
264
+ })
265
+ })
266
+
267
+ document.querySelector('#clearWatermark')?.addEventListener('click', () => {
268
+ renderWithWatermark(null)
269
+ })
270
+ ```
271
+
272
+ ## 详细示例
273
+
274
+ ### 示例 1:合同预览 + 顶层保密文本水印
275
+
276
+ ```ts
277
+ createViewer({
278
+ target: '#viewer',
279
+ file: '/contracts/nda.pdf',
280
+ filename: 'nda.pdf',
281
+ toolbar: true,
282
+ pdfRender: 'inset',
283
+ watermark: {
284
+ type: 'text',
285
+ content: 'CONFIDENTIAL',
286
+ fontSize: 24,
287
+ color: '#d4380d',
288
+ opacity: 0.18,
289
+ rotate: -32,
290
+ gapX: 130,
291
+ gapY: 85,
292
+ position: 'top'
293
+ }
294
+ }).mount()
295
+ ```
296
+
297
+ ### 示例 2:员工手册预览 + 底层品牌 Logo 水印
298
+
299
+ ```ts
300
+ createViewer({
301
+ target: '#viewer',
302
+ file: '/manuals/employee-handbook.docx',
303
+ toolbar: true,
304
+ watermark: {
305
+ type: 'image',
306
+ image: '/assets/brand-watermark.svg',
307
+ imageWidth: 72,
308
+ imageHeight: 72,
309
+ opacity: 0.1,
310
+ rotate: -15,
311
+ gapX: 210,
312
+ gapY: 140,
313
+ position: 'bottom'
314
+ }
315
+ }).mount()
316
+ ```
317
+
318
+ ### 示例 3:自定义请求头 + 水印
319
+
320
+ ```ts
321
+ createViewer({
322
+ target: '#viewer',
323
+ file: {
324
+ url: 'https://api.example.com/files/statement.pdf',
325
+ headers: {
326
+ Authorization: 'Bearer your-token'
327
+ }
328
+ },
329
+ requestAdapter: async (url, options) => {
330
+ const response = await fetch(url, {
331
+ method: options?.method || 'GET',
332
+ headers: options?.headers
333
+ })
334
+
335
+ if (!response.ok) {
336
+ throw new Error(`Request failed: ${response.status}`)
337
+ }
338
+
339
+ return response.arrayBuffer()
340
+ },
341
+ watermark: {
342
+ type: 'text',
343
+ content: '审阅版',
344
+ fontSize: 16,
345
+ color: '#7d8b99',
346
+ opacity: 0.16,
347
+ rotate: -28,
348
+ gapX: 150,
349
+ gapY: 100
350
+ }
351
+ }).mount()
352
+ ```
353
+
354
+ ## API
355
+
356
+ ### `createViewer(options)`
357
+
358
+ 创建预览器实例,返回 `ViewerInstance`。
359
+
360
+ ### `ViewerOptions`
361
+
362
+ | 参数 | 类型 | 默认值 | 说明 |
363
+ |------|------|--------|------|
364
+ | `target` | `HTMLElement \| string` | - | 挂载目标元素 |
365
+ | `file` | `FileSource` | - | 文件源,支持 URL、File、Blob、ArrayBuffer、带请求参数对象 |
366
+ | `type` | `FileType` | 自动识别 | 手动指定文件类型 |
367
+ | `filename` | `string` | - | 文件名,用于显示和下载 |
368
+ | `toolbar` | `boolean \| ToolbarConfig` | `true` | 工具栏配置 |
369
+ | `theme` | `'light' \| 'dark' \| ThemeConfig` | `'light'` | 主题配置 |
370
+ | `locale` | `'zh-CN' \| 'en' \| LocaleConfig` | `'zh-CN'` | 语言配置 |
371
+ | `width` | `string \| number` | `'100%'` | 预览器宽度 |
372
+ | `height` | `string \| number` | `'100%'` | 预览器高度 |
373
+ | `className` | `string` | - | 自定义类名 |
374
+ | `style` | `Record<string, string>` | - | 自定义样式 |
375
+ | `pdfRender` | `'native' \| 'inset'` | `'inset'` | PDF 预览方式 |
376
+ | `watermark` | `WatermarkConfig \| null` | `null` | 文档水印配置 |
377
+ | `proxyUrl` | `string` | - | 自定义代理地址 |
378
+ | `requestAdapter` | `RequestAdapter` | - | 自定义请求适配器 |
379
+ | `renderOptions` | `object` | - | 初始缩放、旋转、页码等渲染配置 |
380
+ | `onReady` | `() => void` | - | 预览器就绪回调 |
381
+ | `onLoad` | `() => void` | - | 文件加载完成回调 |
382
+ | `onError` | `(error: Error) => void` | - | 错误回调 |
383
+ | `onDestroy` | `() => void` | - | 销毁回调 |
384
+
385
+ ### `WatermarkConfig`
386
+
387
+ | 参数 | 类型 | 说明 |
388
+ |------|------|------|
389
+ | `type` | `'text' \| 'image'` | 水印类型 |
390
+ | `content` | `string` | 文本水印内容,`type: 'text'` 时使用 |
391
+ | `image` | `string` | 图片地址,`type: 'image'` 时使用 |
392
+ | `fontSize` | `number` | 文字字号,单位 `px` |
393
+ | `color` | `string` | 文字颜色 |
394
+ | `fontFamily` | `string` | 文字字体 |
395
+ | `fontWeight` | `string \| number` | 字重 |
396
+ | `imageWidth` | `number` | 图片水印宽度,单位 `px` |
397
+ | `imageHeight` | `number` | 图片水印高度,单位 `px` |
398
+ | `opacity` | `number` | 透明度,范围建议 `0 ~ 1` |
399
+ | `rotate` | `number` | 旋转角度,单位 `deg` |
400
+ | `gapX` | `number` | 水平平铺间距 |
401
+ | `gapY` | `number` | 垂直平铺间距 |
402
+ | `position` | `'top' \| 'bottom'` | 显示在文档上方或下方 |
403
+ | `width` | `string \| number` | 水印容器宽度 |
404
+ | `height` | `string \| number` | 水印容器高度 |
405
+
406
+ ### `ViewerInstance`
407
+
408
+ | 方法 | 说明 |
409
+ |------|------|
410
+ | `mount(target?)` | 挂载到目标容器 |
411
+ | `destroy()` | 销毁实例 |
412
+ | `setFile(file, filename?)` | 动态切换文件 |
413
+ | `getFile()` | 获取当前文件信息 |
414
+ | `zoom(scale)` | 设置缩放比例 |
415
+ | `rotate(degree)` | 设置旋转角度 |
416
+ | `reset()` | 重置缩放和旋转 |
417
+ | `fullscreen(enable?)` | 切换全屏 |
418
+ | `prevPage()` | 上一页 |
419
+ | `nextPage()` | 下一页 |
420
+ | `gotoPage(page)` | 跳转到指定页 |
421
+ | `getPageInfo()` | 获取页码信息 |
422
+ | `print()` | 打印当前文档 |
423
+ | `download()` | 下载当前文档 |
424
+ | `setTheme(theme)` | 设置主题 |
425
+ | `setLocale(locale)` | 设置语言 |
426
+ | `setToolbar(config)` | 设置工具栏 |
427
+ | `on(event, handler)` | 监听事件 |
428
+ | `off(event, handler)` | 取消监听事件 |
429
+ | `getState()` | 获取当前状态 |
430
+
431
+ ## 支持的文件格式
432
+
433
+ | 格式 | 扩展名 | 说明 |
434
+ |------|--------|------|
435
+ | PDF | `.pdf` | PDF 文档 |
436
+ | Word | `.docx` | Microsoft Word 文档 |
437
+ | Excel | `.xlsx`, `.xls` | Microsoft Excel 表格 |
438
+ | PowerPoint | `.pptx`, `.ppt` | Microsoft PowerPoint 演示文稿 |
439
+ | OFD | `.ofd` | 电子公文格式 |
440
+ | 文本 | `.txt` | 纯文本文件 |
441
+ | Markdown | `.md`, `.markdown` | Markdown 文档 |
442
+ | HTML | `.html`, `.htm` | HTML 文件或网页内容 |
443
+ | 图片 | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.bmp`, `.tiff`, `.tif`, `.ico` | 图片预览 |
444
+
445
+ ## 浏览器支持
446
+
447
+ - Chrome >= 80
448
+ - Firefox >= 75
449
+ - Safari >= 13
450
+ - Edge >= 80
451
+
452
+ ## 许可证
453
+
454
+ [Apache-2.0](./LICENSE)
455
+
456
+ ## 链接
457
+
458
+ - [GitHub](https://github.com/jitOffice/jit-viewer-sdk)
459
+ - [主页](https://jitword.com/jit-viewer.html)
460
+ - [问题反馈](https://github.com/jitOffice/jit-viewer-sdk/issues)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jit-viewer",
3
- "version": "1.1.1",
3
+ "version": "1.1.2",
4
4
  "description": "JitViewer核心SDK - 跨框架文档预览引擎,支持PDF、DOCX、XLSX、PPTX、OFD、TXT、Markdown等格式",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -27,6 +27,7 @@
27
27
  "files": [
28
28
  "dist",
29
29
  "README.md",
30
+ "README.zh-CN.md",
30
31
  "LICENSE"
31
32
  ],
32
33
  "scripts": {