@koi-br/ocr-web-sdk 1.0.10 → 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,67 +302,32 @@ previewRef.value.preview(url, 'file.pdf', {
 previewRef.value.clearPreview();
 ```
 
-#### 访问子组件方法
-
-`FilePreview` 提供了多种方式访问子组件的方法：
-
-##### 方式一：使用代理方法（推荐）
-
-`FilePreview` 提供了常用方法的代理，可以直接调用：
-
-```javascript
-// PDF 预览相关方法
-previewRef.value.goToPage(5); // 跳转到第5页
-previewRef.value.jumpToPosition(1, [100, 100, 200, 200]); // 跳转到指定位置
-const currentPage = previewRef.value.getCurrentPage(); // 获取当前页码
-const totalPages = previewRef.value.getTotalPages(); // 获取总页数
-
-// 图片预览相关方法
-previewRef.value.resetImage(); // 重置图片预览
-previewRef.value.resetTif(); // 重置 TIF 预览
-```
-
-##### 方式二：获取子组件引用
-
-如果需要访问子组件的所有方法，可以获取子组件的引用：
+#### 向子组件传递 Props
 
-```javascript
-// 获取 PDF 预览组件引用
-const pdfPreview = previewRef.value.getPdfPreview();
-if (pdfPreview) {
-  pdfPreview.jumpToPosition(1, [100, 100, 200, 200]);
-  pdfPreview.goToPage(5);
-}
-
-// 获取图片预览组件引用
-const imagePreview = previewRef.value.getImagePreview();
-if (imagePreview) {
-  imagePreview.reset();
-}
-
-// 获取当前活动的预览组件（根据文件类型自动返回）
-const currentPreview = previewRef.value.getCurrentPreview();
-if (currentPreview) {
-  // 如果是 PDF 预览，可以调用 PDF 相关方法
-  if (currentPreview.jumpToPosition) {
-    currentPreview.jumpToPosition(1, [100, 100, 200, 200]);
-  }
-  // 如果是图片预览，可以调用图片相关方法
-  if (currentPreview.reset) {
-    currentPreview.reset();
-  }
-}
-```
+`FilePreview` 支持通过 `*Props` 属性向对应的子组件传递配置。例如，向 PDF 预览组件传递 `blocksData` 和 `showTocSidebar`：
 
-**完整使用示例：**
+**示例：**
 ```vue
 <template>
-  <div>
-    <FilePreview ref="previewRef" :is-download="true" />
-    <button @click="handlePreview">预览文件</button>
-    <button @click="handleJumpToPage">跳转到第5页</button>
-    <button @click="handleJumpToPosition">跳转到指定位置</button>
-  </div>
+  <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>
@@ -349,38 +335,31 @@ import { ref } from 'vue';
 import { FilePreview } from '@koi-br/ocr-web-sdk';
 
 const previewRef = ref(null);
-
-const handlePreview = () => {
-  previewRef.value.preview('https://example.com/file.pdf', 'file.pdf');
-};
-
-const handleJumpToPage = () => {
-  // 方式一：使用代理方法（推荐）
-  previewRef.value.goToPage(5);
-  
-  // 方式二：获取 PDF 预览组件引用
-  const pdfPreview = previewRef.value.getPdfPreview();
-  if (pdfPreview) {
-    pdfPreview.goToPage(5);
+const pdfBlocksData = ref([
+  {
+    blockLabel: '标题',
+    blockContent: '第一章',
+    blockBbox: [100, 100, 200, 150],
+    blockPage: 1
   }
-};
+]);
 
-const handleJumpToPosition = () => {
-  // 跳转到第1页的指定位置 [x1, y1, x2, y2]
-  const bbox = [100, 100, 200, 200];
-  
-  // 方式一：使用代理方法（推荐）
-  previewRef.value.jumpToPosition(1, bbox);
-  
-  // 方式二：获取 PDF 预览组件引用
-  const pdfPreview = previewRef.value.getPdfPreview();
-  if (pdfPreview) {
-    pdfPreview.jumpToPosition(1, bbox);
-  }
-};
+// 预览文件
+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 组件