@work-zhanguo/light-file-preview

v0.0.16

Published

4 days ago

Lightweight file preview component for Vue 3, Vue 2, and standalone usage / 轻量级文件预览组件，支持 Vue3、Vue2 与独立产物嵌入。

0High
0Medium
0Low

work-zhanguo

vue3 vue2 file-preview pdf docx xlsx

项目简介

当前版本：0.0.16
适用场景：业务系统附件预览、在线查看、弹窗预览、新页面预览
支持 Vue 3、Vue 2 适配入口，以及非 Vue 项目的 standalone 产物

效果预览

仓库里的原始截图在 public/screenshots/ 目录。

下面的示例图使用 npm CDN 地址。当前仓库修改不会立即影响已发布版本；发布包含截图的新版本后，npm 页面会直接显示这些图片。

DOCX

DOCX 预览效果

XLSX

XLSX 预览效果

PDF

PDF 预览效果

PPTX 降级展示

当前 PPT / PPTX 不做在线解析，组件会保留下载入口，不会伪装成已支持的在线预览。

PPTX 降级效果

支持文件

在线预览支持：

PNG
JPG
JPEG
GIF
WEBP
BMP
SVG
PDF
TXT
JSON
JS
TS
JSX
TSX
HTML
CSS
MD
DOCX
XLS
XLSX
CSV
MP4
WEBM
MP3
WAV

降级为下载入口：

DOC
PPT
PPTX
其他未识别格式

补充说明：

支持远程 URL、本地 File、Blob
支持直接嵌入和弹窗预览
不支持的格式不强行预览，统一保留下载入口

项目依赖

安装

npm install @work-zhanguo/light-file-preview

组件属性

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | source | string \| File \| Blob | - | 必填。支持远程 URL、本地 File、Blob。 | | fileName | string | - | 自定义文件名，远程地址没有扩展名时建议传。 | | mode | 'inline' \| 'dialog' | 'inline' | 直接预览或弹窗预览。 | | visible | boolean | true | 弹窗模式下控制显示状态，可配合 v-model:visible。 | | loadingText | string | '文件加载中...' | 加载提示文案。 | | textEncoding | string | 'utf-8' | 文本类文件读取编码。 | | maxTextBytes | number | 2097152 | 文本预览最大读取字节数，默认 2MB。 | | maxSheetRows | number | 200 | 表格预览最大展示行数。 | | maxSheetCols | number | 50 | 表格预览最大展示列数。 | | pdfScale | number | 1.35 | PDF 渲染缩放比例。 | | showToolbar | boolean | true | 是否显示顶部工具栏。 | | dialogTitle | string | '文件预览' | 预览标题兜底文案。 |

组件事件：

update:visible：弹窗关闭时回传状态
error：解析失败时返回错误对象

Vue 3 集成

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');

<template>
  <LightFilePreview source="/files/demo.pdf" />
</template>

Vue 2 集成

import Vue from 'vue';
import LightFilePreview from '@work-zhanguo/light-file-preview/vue2';
import '@work-zhanguo/light-file-preview/style.css';

Vue.use(LightFilePreview);

<template>
  <light-file-preview :source="fileUrl" />
</template>

弹窗预览

<template>
  <button @click="show = true">打开弹窗预览</button>

  <LightFilePreview
    v-model:visible="show"
    source="https://501351981.github.io/vue-office/examples/dist/static/test-files/test.docx"
    mode="dialog"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const show = ref(false);
</script>

新页面预览

建议同时传 name，这样扩展名识别更稳定。

const remoteUrl = 'https://example.com/files/test.docx';
const previewUrl =
  '/?preview=1&src=' +
  encodeURIComponent(remoteUrl) +
  '&name=' +
  encodeURIComponent('test.docx');

window.open(previewUrl, '_blank');

原生项目集成

非 Vue 项目可以直接使用 standalone 产物。

如果你是从 npm 包里复制静态文件，建议复制下面两个文件：

dist/standalone/light-file-preview.iife.js
dist/standalone/style.css

<link rel="stylesheet" href="/vendor/light-file-preview/style.css" />
<div id="preview-root"></div>
<script src="/vendor/light-file-preview/light-file-preview.iife.js"></script>
<script>
  window.LightFilePreview.mount('#preview-root', {
    source: '/uploads/report.xlsx'
  });
</script>

Odoo 集成

Odoo 项目推荐走静态资源加 Owl 组件挂载。

/** @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';

<templates xml:space="preserve">
  <t t-name="your_module.FilePreviewBlock">
    <div class="o_file_preview_root" t-ref="root" />
  </t>
</templates>

部署说明

组件库打包：

npm install
npm run build

产物目录：

dist/
dist/standalone/

如果要把首页演示页和文档页一起部署成静态站点，执行：

npm run build:site

站点部署目录：

dist-site/

Overview

Current version: 0.0.16
Use cases: attachment preview in business systems, inline viewing, dialog preview, and standalone preview pages
Supports Vue 3, a Vue 2 adapter entry, and standalone assets for non-Vue projects

Recent updates:

0.0.16: fixed global style leakage caused by importing style.css, and scoped published component styles to .lfp-* rules only
0.0.15: rewrote README.md for npm with collapsible Chinese and English sections, and synchronized package description and documentation version info
0.0.14: optimized blank area handling in xlsx, removed undeclared frozen header/column behavior, and added paged/all display switching for PDF and DOCX
0.0.13: fixed retry behavior after preview failures in dialog mode, refreshed README examples, and clarified packaging details
0.0.12: fixed missing background, text, and border colors for some xlsx cells, and added theme / tint / indexed color parsing

For the full release history, see CHANGELOG.md.

Preview Screenshots

Original screenshots are stored in public/screenshots/.

The images below use the npm CDN URL. Local repository changes do not affect the already published package immediately; after publishing a new version, npm will show the latest screenshots directly.

DOCX

DOCX preview

XLSX

XLSX preview

PDF

PDF preview

PPTX fallback

PPT / PPTX files are intentionally not parsed as online previews for now. The component keeps a download entry instead of pretending the format is fully supported.

PPTX fallback

Supported Files

Supported for online preview:

PNG
JPG
JPEG
GIF
WEBP
BMP
SVG
PDF
TXT
JSON
JS
TS
JSX
TSX
HTML
CSS
MD
DOCX
XLS
XLSX
CSV
MP4
WEBM
MP3
WAV

Fallback to download entry:

DOC
PPT
PPTX
any unrecognized format

Notes:

Supports remote URL, local File, and Blob
Supports both inline embedding and dialog preview
Unsupported formats are not force-rendered and always keep a download entry

Dependencies

Installation

npm install @work-zhanguo/light-file-preview

Component Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | source | string \| File \| Blob | - | Required. Supports remote URLs, local File, and Blob. | | fileName | string | - | Optional file name. Recommended when a remote URL has no extension. | | mode | 'inline' \| 'dialog' | 'inline' | Inline preview or dialog preview. | | visible | boolean | true | Controls dialog visibility and works with v-model:visible. | | loadingText | string | '文件加载中...' | Loading text displayed during parsing. | | textEncoding | string | 'utf-8' | Encoding used for text-like files. | | maxTextBytes | number | 2097152 | Max size for text preview, default is 2 MB. | | maxSheetRows | number | 200 | Maximum number of rows rendered in sheet preview. | | maxSheetCols | number | 50 | Maximum number of columns rendered in sheet preview. | | pdfScale | number | 1.35 | Render scale used for PDF pages. | | showToolbar | boolean | true | Whether to show the top toolbar. | | dialogTitle | string | '文件预览' | Fallback title used in dialog mode. |

Events:

update:visible: emitted when the dialog closes
error: emitted with the parsing error object

Vue 3 Integration

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');

<template>
  <LightFilePreview source="/files/demo.pdf" />
</template>

Vue 2 Integration

import Vue from 'vue';
import LightFilePreview from '@work-zhanguo/light-file-preview/vue2';
import '@work-zhanguo/light-file-preview/style.css';

Vue.use(LightFilePreview);

<template>
  <light-file-preview :source="fileUrl" />
</template>

Dialog Preview

<template>
  <button @click="show = true">Open dialog preview</button>

  <LightFilePreview
    v-model:visible="show"
    source="https://501351981.github.io/vue-office/examples/dist/static/test-files/test.docx"
    mode="dialog"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const show = ref(false);
</script>

Standalone Preview Page

It is recommended to pass name as well so extension detection stays stable.

const remoteUrl = 'https://example.com/files/test.docx';
const previewUrl =
  '/?preview=1&src=' +
  encodeURIComponent(remoteUrl) +
  '&name=' +
  encodeURIComponent('test.docx');

window.open(previewUrl, '_blank');

Native Project Integration

Non-Vue projects can directly use the standalone bundle.

If you copy static assets from the npm package, the recommended files are:

dist/standalone/light-file-preview.iife.js
dist/standalone/style.css

<link rel="stylesheet" href="/vendor/light-file-preview/style.css" />
<div id="preview-root"></div>
<script src="/vendor/light-file-preview/light-file-preview.iife.js"></script>
<script>
  window.LightFilePreview.mount('#preview-root', {
    source: '/uploads/report.xlsx'
  });
</script>

Odoo Integration

For Odoo projects, the recommended approach is to mount the standalone bundle through static assets and an Owl component.

/** @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';

<templates xml:space="preserve">
  <t t-name="your_module.FilePreviewBlock">
    <div class="o_file_preview_root" t-ref="root" />
  </t>
</templates>

Deployment

Build the component library:

npm install
npm run build

Output directories:

dist/
dist/standalone/

If you want to deploy both the demo home page and the docs page as a static site:

npm run build:site

Static site output:

dist-site/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

项目简介

效果预览

DOCX

XLSX

PDF

PPTX 降级展示

支持文件

项目依赖

安装

组件属性

Vue 3 集成

Vue 2 集成

弹窗预览

新页面预览

原生项目集成

Odoo 集成

部署说明

Overview

Preview Screenshots

DOCX

XLSX

PDF

PPTX fallback

Supported Files

Dependencies

Installation

Component Props

Vue 3 Integration

Vue 2 Integration

Dialog Preview

Standalone Preview Page

Native Project Integration

Odoo Integration

Deployment