@koi-br/ocr-web-sdk 1.0.9 → 1.0.11

package/README.md

@@ -81,7 +81,19 @@ pnpm add @koi-br/ocr-web-sdk
 ```vue
 <template>
   <div>
-    <FilePreview ref="previewRef" :is-download="true" />
+    <FilePreview 
+      ref="previewRef" 
+      :is-download="true"
+      :pdf-props="{
+        showTocSidebar: true,
+        blocksData: blocksData
+      }"
+      :image-props="{
+        minScale: 0.1,
+        maxScale: 5,
+        clickStep: 0.25
+      }"
+    />
     <button @click="previewFile">预览文件</button>
   </div>
 </template>
@@ -91,6 +103,7 @@ import { ref } from 'vue';
 import { FilePreview } from '@koi-br/ocr-web-sdk';
 
 const previewRef = ref(null);
+const blocksData = ref([]); // PDF 分块数据
 
 // 预览文件 URL
 const previewFile = () => {
@@ -237,7 +250,15 @@ const handleDownload = () => {
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `isDownload` | `boolean` | `false` | 是否显示下载按钮 |
+| `isDownload` | `boolean` | `false` | 是否显示下载按钮（会传递给所有子组件） |
+| `pdfProps` | `object` | `{}` | 传递给 PDF 预览组件的 props（见 [PdfPreview Props](#pdfpreview-组件)） |
+| `imageProps` | `object` | `{}` | 传递给图片预览组件的 props（见 [ImagePreview Props](#imagepreview-组件)） |
+| `tifProps` | `object` | `{}` | 传递给 TIF 预览组件的 props（见 [TifPreview Props](#tifpreview-组件)） |
+| `docxProps` | `object` | `{}` | 传递给 Word 预览组件的 props（见 [DocxPreview Props](#docxpreview-组件)） |
+| `ofdProps` | `object` | `{}` | 传递给 OFD 预览组件的 props（见 [OfdPreview Props](#ofdpreview-组件)） |
+| `xlsxProps` | `object` | `{}` | 传递给 Excel 预览组件的 props（见 [XlsxPreview Props](#xlsxpreview-组件)） |
+
+**注意：** `isDownload` 会单独传递给子组件，不会包含在对应的 `*Props` 对象中。如果需要为不同文件类型设置不同的下载按钮显示状态，可以在对应的 `*Props` 中设置 `isDownload`（优先级更高）。
 
 #### Methods
 
@@ -281,6 +302,64 @@ previewRef.value.preview(url, 'file.pdf', {
 previewRef.value.clearPreview();
 ```
 
+#### 向子组件传递 Props
+
+`FilePreview` 支持通过 `*Props` 属性向对应的子组件传递配置。例如，向 PDF 预览组件传递 `blocksData` 和 `showTocSidebar`：
+
+**示例：**
+```vue
+<template>
+  <FilePreview 
+    ref="previewRef"
+    :is-download="true"
+    :pdf-props="{
+      showTocSidebar: true,
+      blocksData: pdfBlocksData
+    }"
+    :image-props="{
+      minScale: 0.1,
+      maxScale: 5,
+      clickStep: 0.25,
+      wheelStep: 0.1
+    }"
+    :docx-props="{
+      docName: '我的文档',
+      minScale: 0.1,
+      maxScale: 3
+    }"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { FilePreview } from '@koi-br/ocr-web-sdk';
+
+const previewRef = ref(null);
+const pdfBlocksData = ref([
+  {
+    blockLabel: '标题',
+    blockContent: '第一章',
+    blockBbox: [100, 100, 200, 150],
+    blockPage: 1
+  }
+]);
+
+// 预览文件
+previewRef.value.preview('https://example.com/file.pdf', 'file.pdf');
+</script>
+```
+
+**各子组件支持的 Props：**
+
+- **PDF (`pdfProps`)**: `showTocSidebar`, `blocksData`（详见 [PdfPreview Props](#pdfpreview-组件)）
+- **图片 (`imageProps`)**: `minScale`, `maxScale`, `clickStep`, `wheelStep`, `originalId`（详见 [ImagePreview Props](#imagepreview-组件)）
+- **TIF (`tifProps`)**: `minScale`, `maxScale`, `clickStep`, `wheelStep`, `originalId`（详见 [TifPreview Props](#tifpreview-组件)）
+- **Word (`docxProps`)**: `docName`, `docData`, `minScale`, `maxScale`, `clickStep`, `wheelStep`（详见 [DocxPreview Props](#docxpreview-组件)）
+- **OFD (`ofdProps`)**: 无额外 props（详见 [OfdPreview Props](#ofdpreview-组件)）
+- **Excel (`xlsxProps`)**: 无额外 props（详见 [XlsxPreview Props](#xlsxpreview-组件)）
+
+**注意：** `isDownload` 会单独传递给所有子组件。如果需要在 `*Props` 中覆盖 `isDownload`，子组件会优先使用 `*Props` 中的值。
+
 ---
 
 ### PdfPreview 组件
@@ -321,8 +400,6 @@ interface BlockInfo {
 |--------|------|--------|------|
 | `goToPage` | `pageNum: number` | - | 跳转到指定页码（从1开始） |
 | `jumpToPosition` | `pageNum: number, bbox: [number, number, number, number], emitEvent?: boolean` | - | 跳转到指定位置并高亮（统一接口，**自动识别类型**，无需传入类型参数） |
-| `jumpToBlockPosition` | `pageNum: number, bbox: [number, number, number, number], emitEvent?: boolean` | - | 跳转到指定文本块位置并高亮（向后兼容的别名，内部调用统一接口） |
-| `jumpToSealPosition` | `pageNum: number, bbox: [number, number, number, number], emitEvent?: boolean` | - | 跳转到指定印章位置并高亮（向后兼容的别名，内部调用统一接口） |
 | `getCurrentPage` | - | `number` | 获取当前页码 |
 | `getTotalPages` | - | `number` | 获取总页数 |
 | `reset` | - | - | 重置预览状态 |
@@ -721,10 +798,6 @@ const handleFileChange = (event) => {
 ```javascript
 // 自动识别类型（推荐）
 pdfRef.value?.jumpToPosition(pageNum, bbox);
-
-// 向后兼容的别名方法
-pdfRef.value?.jumpToBlockPosition(pageNum, bbox);
-pdfRef.value?.jumpToSealPosition(pageNum, bbox);
 ```
 
 ### 6. 资源清理