@7niao/doc-previewer 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 7niao
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# @7niao/doc-previewer(Trae CN + DeepSeek-v4.1-Flash)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 Vue 3 + TypeScript 的通用文件预览组件。按文件类型自动选择渲染器并按需懒加载，内置缩放、旋转、下载、打印、全屏与画布拖拽平移，可作为一个独立组件接入任意 Vue 3 项目。
+
+## 特性
+
+- 覆盖常见办公与工程格式：图片、音视频、PDF、Word（docx）、Excel（xlsx）、PPT（pptx）、OFD、CAD（dwg/dxf）、3D 模型（glb/gltf）、GIS（kml/kmz/shp/geojson）、压缩包（zip/rar/7z/tar）。
+- 统一输入：`File`、`Blob` 或可访问的远程 URL。
+- 工具栏：缩小 / 放大 / 复位、左旋 / 右旋、下载、打印、全屏；按格式自动禁用无意义的操作。
+- 画布拖拽：内容超出视口时按住鼠标左键即可平移，光标自动切换为“抓手”。
+- 按格式懒加载渲染器，未用到的重型依赖不会进入首屏。
+- 压缩包支持条目浏览、密码输入，并可对单个条目嵌套预览。
+- 完整 TypeScript 类型声明，同时提供演示站点与示例文件。
+
+## 安装
+
+```bash
+pnpm add @7niao/doc-previewer
+# 或
+npm install @7niao/doc-previewer
+yarn add @7niao/doc-previewer
+```
+
+`vue` 为 peer 依赖，需要宿主项目已安装 `vue@^3.4`。发布产物为 ESM，适用于 Vite、Webpack 5、Rollup 等现代打包器。
+
+## 快速开始
+
+### 引入样式
+
+组件库的样式（含 Leaflet 地图样式）统一抽取到 `style.css`，只需引入一次：
+
+```ts
+// main.ts
+import '@7niao/doc-previewer/style.css'
+```
+
+### 局部使用
+
+```vue
+<script setup lang="ts">
+import { FileViewer } from '@7niao/doc-previewer'
+import { ref } from 'vue'
+
+const file = ref<File | string>('https://example.com/report.pdf')
+
+const options = {
+  height: '640px',
+  showFileInfo: true,
+  zoom: { min: 0.1, max: 8, step: 0.2 },
+}
+</script>
+
+<template>
+  <FileViewer
+    :src="file"
+    file-name="report.pdf"
+    :options="options"
+    @ready="kind => console.log('渲染完成', kind)"
+    @error="message => console.error(message)"
+  />
+</template>
+```
+
+### 通过 ref 调用
+
+```vue
+<script setup lang="ts">
+import { FileViewer } from '@7niao/doc-previewer'
+import { ref } from 'vue'
+
+const file = ref<File | string>('https://example.com/report.pdf')
+const viewer = ref<InstanceType<typeof FileViewer> | null>(null)
+</script>
+
+<template>
+  <FileViewer ref="viewer" :src="file" />
+</template>
+```
+
+`ref` 上可调用：`zoomIn()`、`zoomOut()`、`resetZoom()`、`rotateLeft()`、`rotateRight()`、`download()`、`print()`、`toggleFullscreen()`、`getKind()`、`getSource()`。
+
+### 工具函数与类型
+
+```ts
+import { detectKind, getExtension, formatBytes, KIND_LABELS } from '@7niao/doc-previewer'
+import type { PreviewKind, FileViewerOptions, PreviewSource } from '@7niao/doc-previewer'
+```
+
+## 静态资源：压缩包 Worker
+
+压缩包预览依赖 `libarchive.js` 的 Worker 与 WASM 文件，组件默认从站点根目录的 `libarchive/` 读取。发布包中已附带这些文件，部署时复制到宿主项目的 public 目录即可：
+
+```bash
+cp -R node_modules/@7niao/doc-previewer/dist/libarchive public/libarchive
+```
+
+访问路径为 `${BASE_URL}libarchive/worker-bundle.js`。若应用部署在子路径下，请确认 `BASE_URL` 与复制位置一致；未复制时压缩包预览会提示加载失败，其余格式不受影响。
+
+## Props
+
+| 属性 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `src` | `File \| Blob \| string` | 是 | 文件对象、Blob 或可访问的 URL |
+| `fileName` | `string` | 否 | 覆盖自动识别的文件名 |
+| `mimeType` | `string` | 否 | 覆盖自动识别的 MIME |
+| `kind` | `PreviewKind` | 否 | 强制指定渲染类型，跳过扩展名推断 |
+| `options` | `FileViewerOptions` | 否 | 预览器配置，见下表 |
+
+## Events
+
+| 事件 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `kind: PreviewKind` | 渲染完成 |
+| `error` | `message: string` | 渲染失败，附带错误原因 |
+| `zoom-change` | `percent: number` | 缩放比例变化 |
+| `download` | `name: string` | 用户点击下载 |
+| `print` | - | 用户点击打印 |
+| `fullscreen-change` | `active: boolean` | 进入 / 退出全屏 |
+
+## options
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `height` | `string` | `'640px'` | 组件高度 |
+| `toolbar` | `boolean` | `true` | 是否显示顶部工具栏 |
+| `showFileInfo` | `boolean` | `true` | 是否显示文件名与格式信息 |
+| `zoom` | `{ min?: number; max?: number; step?: number }` | `{ min: 0.1, max: 10, step: 0.2 }` | 缩放范围与每步倍率 |
+| `mapTiles` | `string \| false` | 不加载在线底图 | GIS 底图瓦片地址模板，如 `https://tile.openstreetmap.org/{z}/{x}/{y}.png` |
+| `cadLineColor` | `string` | `'#1f2937'` | CAD 线条颜色 |
+| `textMaxLength` | `number` | `2000000` | 文本预览最大字符数，超出截断 |
+
+`PreviewKind` 取值：`image`、`video`、`audio`、`pdf`、`word`、`excel`、`ppt`、`ofd`、`archive`、`cad`、`model3d`、`gis`、`text`、`unsupported`。
+
+## 支持格式
+
+| 类别 | 扩展名 | 渲染实现 | 说明 |
+| --- | --- | --- | --- |
+| 图片 | jpg/jpeg/png/gif/webp/avif/bmp/ico/svg/tif | 原生 `<img>` | 自适应适口，支持缩放、旋转、拖拽 |
+| 音视频 | mp4/webm/ogv/mov/m4v/mkv、mp3/wav/ogg/aac/flac/m4a | 原生 `<video>` / `<audio>` | 使用浏览器原生控制条，不提供缩放 |
+| PDF | pdf | `pdfjs-dist` | Canvas 单页渲染，支持上一页 / 下一页翻页并显示页码，打印走隐藏 iframe |
+| Word | docx/doc | `docx-preview` | 保留分页与样式；复杂域、嵌入对象可能降级 |
+| Excel | xlsx/xlsm/xls/csv/ods | `xlsx`(SheetJS) | 转 HTML 展示，支持多 Sheet 切换 |
+| PPT | pptx/ppt | `pptx-preview` | 列表模式近似还原版式，动画与部分特效不渲染 |
+| OFD | ofd | `ofd-tools` | SVG 渲染、多页展示；未启用电子签章验签 |
+| CAD | dxf/dwg | `dwg2dxf` + `dxf-parser` + `three.js` | DWG 先经 WASM 转为 DXF 再绘制，支持下钻缩放与旋转 |
+| 3D 模型 | glb/gltf | `three.js` GLTFLoader + OrbitControls | 不支持 Draco 压缩模型 |
+| GIS | kml/kmz/shp/geojson | `leaflet` + `@tmcw/togeojson` + `shpjs` | SHP 需配套 `.prj` 才有正确投影；未配置 `mapTiles` 时显示网格底图 |
+| 压缩包 | zip/rar/7z/tar/gz/bz2/xz | `libarchive.js` | 条目列表、密码解锁、单条目嵌套预览，最多展示 500 条 |
+| 文本 | txt/text/md/json/log/xml/yaml/ini/js/ts/py/go 等 | 内置文本渲染器 | UTF-8 解码，`.json` 自动格式化，超长截断 |
+
+未识别的格式会显示提示并提供下载入口。
+
+## 依赖说明
+
+所有渲染引擎均已在发布产物的按需分包中内联，使用方只需安装 `vue`。以下依赖仅在本仓库开发与构建时需要（列于 `devDependencies`）：
+
+| 依赖 | 用途 |
+| --- | --- |
+| `pdfjs-dist` | PDF 解析与 Canvas 渲染，包含独立 worker |
+| `docx-preview` | docx 分页渲染 |
+| `xlsx` | Excel / CSV 解析与表格 HTML 输出 |
+| `pptx-preview` | pptx 版式渲染 |
+| `ofd-tools` | OFD 文档解析与 SVG 渲染 |
+| `libarchive.js` | zip/rar/7z 等压缩包解压（Worker + WASM） |
+| `dwg2dxf` | DWG 转 DXF 的 WASM 转换器 |
+| `dxf-parser` | DXF 实体解析 |
+| `three` | CAD 与 3D 模型绘制、轨道控制器 |
+| `leaflet`、`shpjs`、`@tmcw/togeojson`、`fflate` | GIS 地图、Shapefile 与 KML/KMZ 解析 |
+| `@lucide/vue` | 工具栏与状态图标 |
+
+注：`ofd-tools` 内部依赖的 `@lapo/asn1js` 仅用于电子签章验签，构建时被替换为最小实现，因此不支持 OFD 签章校验。
+
+## 技术栈
+
+- Vue 3.5（`<script setup>` + Composition API）
+- TypeScript 6 + `vue-tsc` 生成类型声明
+- Vite 8（Rolldown）+ `build.lib` 模式产出 ESM 组件库
+- 渲染层：PDF.js、docx-preview、SheetJS、pptx-preview、ofd-tools、libarchive.js、three.js、Leaflet
+- 样式：组件内 scoped CSS，统一抽取为 `dist/style.css`，支持 `prefers-color-scheme` 深色模式
+
+## 本地开发与发布
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动演示站点（含 20 个示例文件）
+pnpm dev
+
+# 类型检查
+pnpm typecheck
+
+# 构建组件库 -> dist/
+pnpm build
+
+# 构建演示站点 -> dist-demo/
+pnpm build:demo
+
+# 查看发布内容
+pnpm pack --dry-run
+
+# 发布到 npm（需先 npm login，且包名带作用域需 --access public）
+pnpm publish:lib
+```
+
+发布流程：修改 `version` → `pnpm publish:lib`。`prepublishOnly` 会自动执行组件库构建，确保 `dist/` 为最新产物；发布内容包括 `dist/`（JS 分包、`style.css`、`types/`、`libarchive/` 资源）。
+
+## 注意事项
+
+- 远程 URL 预览需要目标服务允许跨域（CORS）。
+- PDF 字体、Office 文档字体依赖运行环境，缺失字体会自动回退。
+- 扫描版 PDF 无文本层，不提供 OCR。
+- 压缩包条目在内存中解压，建议控制单个文件体积。
+- 预览组件按浏览器能力降级：不支持的原生音视频编码会给出错误提示并保留下载入口。
+
+## License
+
+[ISC](./LICENSE)