@work-zhanguo/light-file-preview 0.0.1 → 0.0.3

package/README.md

@@ -1,68 +1,91 @@
 # @work-zhanguo/light-file-preview
 
-轻量级通用文件预览项目，基于 Vue3 实现，兼顾 npm 集成和独立产物嵌入。
-
-## 特性
-
-- 支持通过文件路径直接预览，默认内联展示
-- 支持弹窗模式嵌入，也支持独立 IIFE 产物挂载到任意 HTML 节点
-- 支持统一下载，无法在线预览的格式仍可下载
-- PDF 使用 `pdf.js`，DOCX 使用 `docx-preview`，表格使用 `SheetJS`
-- 文本、代码、JSON、Markdown 采用按需读取与加载过渡，兼顾等待体验
-- 支持中文路径自动编码处理，降低路径拼接集成成本
-
-## 支持情况
-
-| 类型 | 扩展名 | 预览说明 |
-| --- | --- | --- |
-| 图片 | `png/jpg/jpeg/gif/webp/bmp/svg` | 高保真原生预览 |
-| PDF | `pdf` | `pdf.js` 高保真渲染 |
-| 文本 | `txt/json/js/ts/jsx/tsx/html/css/md` | 文本或 Markdown 预览 |
-| Word | `docx` | `docx-preview` 中高保真 |
-| Excel | `xls/xlsx/csv` | `SheetJS` 数据高保真 |
-| 视频 | `mp4/webm` | 原生播放器 |
-| 音频 | `mp3/wav` | 原生播放器 |
-| 其他 | `doc/ppt/pptx` 等 | 默认提示暂不支持预览，但支持下载 |
+Gitee: [https://gitee.com/hou_zhan_guo/light-file-preview](https://gitee.com/hou_zhan_guo/light-file-preview)
+npm：[https://www.npmjs.com/package/@work-zhanguo/light-file-preview](https://www.npmjs.com/package/@work-zhanguo/light-file-preview)
+
+## 项目简介
+
+用于业务系统里的附件预览，支持传入文件路径、远程地址和本地文件，接入方式尽量保持简单。
+
+## 支持文件
+
+支持类型：
+
+- `PNG`
+- `JPG`
+- `JPEG`
+- `GIF`
+- `WEBP`
+- `PDF`
+- `TXT`
+- `JSON`
+- `JS`
+- `HTML`
+- `CSS`
+- `MD`
+- `DOCX`
+- `XLS`
+- `XLSX`
+- `CSV`
+- `MP4`
+- `WEBM`
+- `MP3`
+- `WAV`
+
+补充说明：
+
+- 支持远程 `URL`、本地 `File`、`Blob`
+- 支持新页面预览和弹窗预览
+- 不支持的格式不强行预览，统一保留下载入口
+
+## 项目依赖
+
+- [pdf.js](https://github.com/mozilla/pdf.js)
+- [docx-preview](https://github.com/VolodymyrBaydalka/docxjs)
+- [SheetJS](https://github.com/SheetJS/sheetjs)
+- [marked](https://github.com/markedjs/marked)
+- [DOMPurify](https://github.com/cure53/DOMPurify)
 
 ## 安装
 
+安装组件：
+
 ```bash
 npm install @work-zhanguo/light-file-preview
 ```
 
-## Vue3 使用
+如果是 `Vue3` 项目，注册入口：
 
 ```ts
-import { createApp } from 'vue';
-import App from './App.vue';
 import LightFilePreview from '@work-zhanguo/light-file-preview';
 import '@work-zhanguo/light-file-preview/style.css';
-
-createApp(App).use(LightFilePreview).mount('#app');
 ```
 
-```vue
-<template>
-  <LightFilePreview source="/files/示例.pdf" />
-</template>
+如果是 `Vue2` 项目，注册入口：
+
+```js
+import LightFilePreview from '@work-zhanguo/light-file-preview/vue2';
+import '@work-zhanguo/light-file-preview/style.css';
 ```
 
-## 按需引入
+## 远程地址预览
 
-```vue
-<script setup lang="ts">
-import { FilePreview } from '@work-zhanguo/light-file-preview';
-import '@work-zhanguo/light-file-preview/style.css';
-</script>
+通过 `window.open` 传入网络地址，直接打开新页面预览。建议同时传 `name`，这样扩展名识别更稳定。
 
-<template>
-  <FilePreview source="/assets/report.docx" mode="dialog" v-model:visible="visible" />
-</template>
+```js
+const remoteUrl = 'https://example.com/files/test.docx';
+const previewUrl =
+  '/?preview=1&src=' +
+  encodeURIComponent(remoteUrl) +
+  '&name=' +
+  encodeURIComponent('test.docx');
+
+window.open(previewUrl, '_blank');
 ```
 
-## 独立产物嵌入任意项目
+## 原生项目集成
 
-执行构建后，将 `dist/standalone/light-file-preview.iife.js` 和 `dist/standalone/style.css` 复制到目标项目。
+非 Vue 项目可以直接使用 standalone 产物。
 
 ```html
 <link rel="stylesheet" href="/vendor/light-file-preview/style.css" />
@@ -70,53 +93,114 @@ import '@work-zhanguo/light-file-preview/style.css';
 <script src="/vendor/light-file-preview/light-file-preview.iife.js"></script>
 <script>
   window.LightFilePreview.mount('#preview-root', {
-    source: '/uploads/合同.pdf'
+    source: '/uploads/report.xlsx'
   });
 </script>
 ```
 
-弹窗模式：
+## Odoo 集成
 
-```html
-<script>
-  window.LightFilePreview.openDialog({
-    source: '/uploads/报表.xlsx'
-  });
-</script>
+Odoo 项目推荐走静态资源加 Owl 组件挂载。
+
+```js
+/** @odoo-module **/
+
+import { Component, onMounted, useRef } from '@odoo/owl';
+
+export class FilePreviewBlock extends Component {
+  setup() {
+    this.rootRef = useRef('root');
+
+    onMounted(() => {
+      window.LightFilePreview.mount(this.rootRef.el, {
+        source: this.props.source,
+        fileName: this.props.fileName || 'report.pdf'
+      });
+    });
+  }
+}
+
+FilePreviewBlock.template = 'your_module.FilePreviewBlock';
+```
+
+```xml
+<templates xml:space="preserve">
+  <t t-name="your_module.FilePreviewBlock">
+    <div class="o_file_preview_root" t-ref="root" />
+  </t>
+</templates>
+```
+
+## Vue2 集成
+
+通过单独适配入口接入：
+
+```js
+import Vue from 'vue';
+import LightFilePreview from '@work-zhanguo/light-file-preview/vue2';
+import '@work-zhanguo/light-file-preview/style.css';
+
+Vue.use(LightFilePreview);
 ```
 
-## 组件参数
+```vue
+<template>
+  <light-file-preview :source="fileUrl" />
+</template>
+```
 
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `source` | `string \| File \| Blob` | - | 文件路径或二进制对象 |
-| `fileName` | `string` | - | 自定义文件名 |
-| `mode` | `'inline' \| 'dialog'` | `inline` | 预览模式 |
-| `visible` | `boolean` | `true` | 弹窗是否显示 |
-| `loadingText` | `string` | `文件加载中...` | 加载提示 |
-| `textEncoding` | `string` | `utf-8` | 文本解码编码 |
-| `maxTextBytes` | `number` | `2097152` | 文本最多读取字节数 |
-| `maxSheetRows` | `number` | `200` | 表格最多展示行数 |
-| `maxSheetCols` | `number` | `50` | 表格最多展示列数 |
-| `pdfScale` | `number` | `1.35` | PDF 渲染缩放 |
-| `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
+## Vue3 集成
 
-## 集成说明
+```ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import LightFilePreview from '@work-zhanguo/light-file-preview';
+import '@work-zhanguo/light-file-preview/style.css';
 
-- 文件路径必须是浏览器可访问地址，跨域资源需目标服务端允许 CORS
-- 组件会在 `File/Blob` 场景自动创建并释放 `Object URL`
-- 大文件文本预览默认只截取前 2MB，避免阻塞页面
-- `.html` 默认按文本展示，不直接执行内容，降低安全风险
+createApp(App).use(LightFilePreview).mount('#app');
+```
 
-## 开发
+```vue
+<template>
+  <LightFilePreview source="/files/demo.pdf" />
+</template>
+```
+
+## 部署说明
+
+直接复制打包产物：
 
 ```bash
 npm install
-npm run dev
+npm run build
+
+# 组件库产物
+dist/
+
+# 可复制到任意项目的独立产物
+dist/standalone/
 ```
 
-## 打包
+如果要把首页演示页和文档页一起部署成静态站点，执行：
 
 ```bash
-npm run build
+npm run build:site
 ```
+
+站点部署目录：
+
+```bash
+dist-site/
+```
+
+其中会包含：
+
+- `dist-site/index.html`
+- `dist-site/docs.html`
+
+## 接入说明
+
+- 本地上传文件只在当前浏览器中预览，不会保存到服务器
+- 如果是远程文件预览，需要目标地址允许浏览器访问和跨域读取
+- 弹窗预览会挂到 `body`
+- 不支持的文件格式会保留下载入口

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@work-zhanguo/light-file-preview",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "轻量级通用文件预览组件，支持 Vue3、Vue2 适配与独立产物嵌入。",
   "type": "module",
   "main": "./dist/light-file-preview.umd.cjs",
@@ -28,8 +28,10 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build && vite build --config vite.vue2.config.ts && vite build --config vite.standalone.config.ts && npm run build:types",
+    "build:site": "vite build --config vite.site.config.ts",
     "build:types": "vue-tsc -p tsconfig.json --declaration --emitDeclarationOnly --outDir dist/types",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "preview:site": "vite preview --config vite.site.config.ts --outDir dist-site"
   },
   "keywords": [
     "vue3",