Skip to content
项目

wb04307201/file-view has 326 GitHub stars and 22 forks. GitHot measured -2 stars in 24 hours. Last checked 2026-11-20 05:11 UTC. Last push 2026-10-25.

这些数字如何统计

实测星标增长

24小时
-2
7天
正在收集历史
15天
正在收集历史
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

A lightweight file preview Starter component for Spring Boot that supports online preview of 20+ file formats (docx/xlsx/pptx/PDF/BPMN/images/videos/code/3D models/CAD, etc.) with a simple Maven dependency.

创作与媒体

README.zh-CN.md

原文

File View 文件预览

English | 中文

一个 Spring Boot 的轻量级文件在线预览 Starter 组件,通过简单的 Maven 依赖引入即可为项目提供 docx/xlsx/pptx/PDF/BPMN/图片/视频/代码/3D 模型/CAD 等 20+ 种文件格式的在线预览能力。

Maven Central star star star License JDK SpringBoot


支持的文件类型

  • office文件(docx,xlsx,pptx)
  • 业务流程管理文件(bpmn,dmn,cmmn)
  • 图片文件
  • 视频文件
  • 音频文件
  • 文档文件(pdf,epub,ofd)
  • TIFF图像文件
  • 文本文件/代码文件(c, cpp, cs, css, diff, go, graphql, html, ini, java, js, json, kt, less, lua, m, mk, pl, php, phtml, py, pyrepl, r, rb, rs, scss, sh, sql, swift, ts, vb, wasm, xml, yaml, yml)
  • Markdown文档文件
  • 3D模型文件(3dm,3ds,3mf,amf,bim,brep,dae,fbx,fcstd,gltf,ifc,iges,step,stl,obj,off,ply,wrl)
  • 思维导图文件(xmind)
  • 压缩文件(zip)
  • CAD(dwg,dxf)

引入

添加Maven依赖

1.4.0 及更高版本:基于 JDK 25 + Spring Boot 4.x(当前分支) 1.4.0-sb3:基于 JDK 17 + Spring Boot 3.x

JDK 25 + Spring Boot 4.x(推荐)

<dependency>
    <groupId>io.github.wb04307201</groupId>
    <artifactId>file-view-spring-boot-starter</artifactId>
    <version>1.4.3</version>
</dependency>

JDK 17 + Spring Boot 3.x

<dependency>
    <groupId>io.github.wb04307201</groupId>
    <artifactId>file-view-spring-boot-starter</artifactId>
    <version>1.4.3-sb3</version>
</dependency>

配置文件

file:
  view:
    ## 以下为默认的处理器,默认无需配置
    bpmn:
      enable: true
    dmn:
      enable: true
    cmmn:
      enable: true
    code:
      enable: true
    epub:
      enable: true
    image:
      enable: true
    markdown:
      enable: true
    pdf:
      enable: true
    xmind:
      enable: true
    docx:
      enable: true
    excel:
      enable: true
    pptx:
      enable: true
    o3d:
      enable: true
    zip:
      enable: true
    cad:
      enable: true
    csv:
      enable: true
    tiff:
      enable: true
    ofd:
      enable: true
    ## 以下为默认的文件名和处理器匹配规则,默认无需配置
    strategies:
      - syntaxAndPattern: glob:*.bpmn
        serviceName: bpmn
      - syntaxAndPattern: glob:*.dmn
        serviceName: dmn
      - syntaxAndPattern: glob:*.cmmn
        serviceName: cmmn
      - syntaxAndPattern: glob:*.{c,cpp,cs,css,diff,go,graphql,html,ini,java,js,json,kt,less,lua,m,mk,pl,php,phtml,py,pyrepl,r,rb,rs,scss,sh,sql,swift,ts,vb,wasm,xml,yaml,yml}
        serviceName: code
      - syntaxAndPattern: glob:*.epub
        serviceName: epub
      - syntaxAndPattern: glob:*.{jpg,png,bmp,gif,webp,svg,raw,heic,cr2,nef,orf,sr2}
        serviceName: image
      - syntaxAndPattern: glob:*.md
        serviceName: markdown
      - syntaxAndPattern: glob:*.pdf
        serviceName: pdf
      - syntaxAndPattern: glob:*.xmind
        serviceName: xmind
      - syntaxAndPattern: glob:*.docx
        serviceName: docx
      - syntaxAndPattern: glob:*.{xlsx,xls}
        serviceName: excel
      - syntaxAndPattern: glob:*.pptx
        serviceName: pptx
      - syntaxAndPattern: glob:*.{3dm,3ds,3mf,amf,bim,brep,dae,fbx,fcstd,gltf,ifc,iges,step,stl,obj,off,ply,wrl}
        serviceName: o3d
      - syntaxAndPattern: glob:*.zip
        serviceName: zip
      - syntaxAndPattern: glob:*.csv
        serviceName: csv
      - syntaxAndPattern: glob:*.{tif,tiff}
        serviceName: tiff
      - syntaxAndPattern: glob:*.ofd
        serviceName: ofd
      - syntaxAndPattern: glob:*.{dwg,dxf}
        serviceName: cad

syntaxAndPattern通过指定语法(如 glob 或 regex)对文件名进行匹配:

  • glob:*.txt
  • regex:(.*)\.txt

使用

静态资源库

部分文件类型使用内置渲染器,如:pdf、epub、xmind、zip、image、code、markdown、cmmn、dmn、bpmn等 使用的js库资源从jsDelivr加载,如无法从jsDelivr获取资源,可以添加file-view-static将js库本地化

<dependency>
    <groupId>io.github.wb04307201</groupId>
    <artifactId>file-view-static</artifactId>
    <version>1.0.0</version>
</dependency>

访问内置界面进行文件上传和预览

访问 http://localhost:8080/file/view
你也可以直接从文件管理器拖动文件到页面任意位置完成上传。
img.png
gif.gif

所有预览页面右上角均内置悬浮下载按钮,鼠标靠近时淡入显示,点击即可下载原始文件。

REST API

方法 路径 说明
POST /file/view/upload 上传文件(支持多文件上传,返回 List<FileStorageInfo> 数组)
GET /file/view/list 获取已上传的文件列表
GET /file/view/{id} 预览指定 ID 的文件
POST /file/view/deleteById 删除指定 ID 的文件(请求体 JSON:{"id": "文件ID"})
GET /wopi/files/{id} WOPI 接口:获取文件元信息
GET /wopi/files/{id}/contents WOPI 接口:获取文件内容

预览扩展

下面以OnlyOffice为例说明如何扩展预览:

  1. 使用docker安装OnlyOffice文档开发者版
docker run --name onlyoffice -i -t -d -p 80:80 -e JWT_ENABLED=false -e ALLOW_PRIVATE_IP_ADDRESS=true onlyoffice/documentserver
  1. 文件预览渲染器扩展
    编写IView.java接口的实现OnlyOfficeView.java:
package cn.wubo.file.view.test;

import cn.wubo.file.view.preview.IView;
import org.springframework.stereotype.Service;
import org.springframework.web.servlet.function.ServerRequest;
import org.springframework.web.servlet.function.ServerResponse;

import java.net.URI;

@Service
public class OnlyOfficeView implements IView {
    @Override
    public String getServiceName() {
        return "onlyoffice";
    }

    @Override
    public ServerResponse handle(ServerRequest request) {
        String id = request.pathVariable("id");
        return ServerResponse.temporaryRedirect(URI.create(String.format("/onlyoffice.html?id=%s",id))).build();
    }
}

编写页面onlyoffice.html:

<!DOCTYPE html>
<html lang="zh-cmn-Hans">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script src="/static/common.js"></script>
    <script type="text/javascript" src="http://localhost/web-apps/apps/api/documents/api.js"></script>
    <title>onlyoffice</title>
    <style>
        html, body {
            height: 100%;
            padding: 0;
            margin: 0;
        }
    </style>
</head>
<body>
<div id="placeholder"></div>
<script>
    document.addEventListener('DOMContentLoaded', function () {
        const id = getUrlParam('id');

        fetch(`/wopi/files/${id}`)
            .then(response => response.json())
            .then(data => {
                const fileName = data.BaseFileName;
                const fileType = data.BaseFileName.substring(data.BaseFileName.lastIndexOf('.') + 1);
                let documentType;
                if (fileType === 'docx' || fileType === 'doc') documentType = 'word';
                if (fileType === 'xlsx' || fileType === 'xls') documentType = 'cell';
                if (fileType === 'pptx' || fileType === 'ppt') documentType = 'slide';

                const config = {
                    "type": "desktop",
                    "width": "100%",
                    "height": "100%",
                    "documentType": `${documentType}`,
                    "document": {
                        "fileType": `${fileType}`,
                        "key": `${data.id}`,
                        "title": `${fileName}`,
                        "url": `${window.location.origin}/wopi/files/${data.id}/contents`,
                    },
                    "editorConfig": {
                        "mode": "view",
                        "lang": "zh"
                    },
                };

                console.log('config',config)

                const docEditor = new DocsAPI.DocEditor("placeholder", config);
            });
    });
</script>
</body>
</html>
  1. 修改配置,关闭重复的渲染器,重定义文件匹配规则application.yml:
file:
  view:
    docx:
      enable: false
    excel:
      enable: false
    pptx:
      enable: false
    strategies:
      - ...
    #      - syntaxAndPattern: glob:*.docx
    #        serviceName: docx
    #      - syntaxAndPattern: glob:*.xlsx
    #        serviceName: excel
    #      - syntaxAndPattern: glob:*.pptx
    #        serviceName: pptx
      - syntaxAndPattern: glob:*.{docx,doc,xlsx,xls,pptx,ppt}
        serviceName: onlyoffice

预览效果如下:
gif_1.gif

文件存储扩展

下面以MinIO为例说明如何扩展文件存储:

  1. 使用docker安装MinIO:
docker run -p 9000:9000 -p 9001:9001 --name minio -e "MINIO_ROOT_USER=ROOTUSER" -e "MINIO_ROOT_PASSWORD=CHANGEME123" quay.io/minio/minio server /data --console-address ":9001"
  1. 添加MinIO依赖:
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>9.0.3</version>
</dependency>
  1. 编写接口IFileStorage.java的实现MinioFileStorageImpl.java:
package cn.wubo.file.view.test;

import cn.wubo.file.view.exception.LocalFileStorageException;
import cn.wubo.file.view.storage.IFileStorage;
import cn.wubo.file.view.storage.dto.FileStorageInfo;
import cn.wubo.file.view.utils.VersionUtls;
import io.minio.GetObjectArgs;
import io.minio.MinioClient;
import io.minio.PutObjectArgs;
import io.minio.RemoveObjectArgs;
import org.springframework.stereotype.Service;

import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

@Service
public class MinioFileStorageImpl implements IFileStorage {

    private final MinioClient minioClient;

    private static final String BUCKET_NAME = "temp";

    private static List<FileStorageInfo> fileStorageInfos = new ArrayList<>();

    public MinioFileStorageImpl() {
        this.minioClient = new MinioClient.Builder()
                .endpoint("http://127.0.0.1:9000")
                .credentials("ROOTUSER", "CHANGEME123")
                .build();
    }

    @Override
    public FileStorageInfo upload(String fileName, byte[] content, String mimeType) {
        try {
            String id = UUID.randomUUID().toString();
            String version = VersionUtls.generateContentVersion(content, id);
            Path filePath = Paths.get(version, fileName);

            minioClient.putObject(
                    PutObjectArgs.builder()
                            .bucket(BUCKET_NAME)
                            .object(filePath.toString())
                            .stream(new ByteArrayInputStream(content), (long) content.length, -1L)
                            .contentType(mimeType)
                            .build()
            );

            FileStorageInfo fpi = new FileStorageInfo(id, fileName, content.length, mimeType, filePath.toString(), version);
            fileStorageInfos.add(fpi);
            return fpi;
        } catch (NoSuchAlgorithmException | MinioException e) {
            throw new LocalFileStorageException(e.getMessage(), e);
        }
    }

    @Override
    public FileStorageInfo findById(String id) {
        return fileStorageInfos.stream()
                .filter(fpi -> fpi.getId().equals(id))
                .findAny()
                .orElseThrow(() -> new LocalFileStorageException("File info not found for id: " + id));
    }

    @Override
    public List<FileStorageInfo> list() {
        return fileStorageInfos;
    }

    @Override
    public byte[] getContentByLocation(String location) {
        try {
            InputStream is = minioClient.getObject(
                    GetObjectArgs.builder()
                            .bucket(BUCKET_NAME)
                            .object(location)
                            .build()
            );
            return is.readAllBytes();
        } catch (IOException | MinioException e) {
            throw new LocalFileStorageException(e.getMessage(), e);
        }
    }

    @Override
    public Boolean deleteById(String id) {
        FileStorageInfo fsi = findById(id);
        if (fsi != null) {
            try {
                minioClient.removeObject(
                        RemoveObjectArgs.builder()
                                .bucket(BUCKET_NAME)
                                .object(fsi.getLocation())
                                .build()
                );
                fileStorageInfos.remove(fsi);
            } catch (MinioException e) {
                throw new LocalFileStorageException(e.getMessage(), e);
            }
        }
        return true;
    }
}

请求鉴权

默认情况下,/file/view/* 和 /wopi/* 端点允许未鉴权的访问。如需添加鉴权,只需实现 IAuth 接口并注册为 Spring Bean,默认的放行实现将被自动替换。

API 鉴权模式(返回 403)

@Service
public class TokenAuth implements IAuth {
    @Override
    public AuthResult check(HttpServletRequest request, String path) {
        String token = request.getHeader("X-Api-Token");
        if (!"your-secret-token".equals(token)) {
            return AuthResult.deny("无效的 Token");
        }
        return AuthResult.allow();
    }
}

BFF 鉴权模式(302 重定向到登录页)

@Service
public class BffAuth implements IAuth {
    @Override
    public AuthResult check(HttpServletRequest request, String path) {
        HttpSession session = request.getSession(false);
        if (session == null || session.getAttribute("user") == null) {
            // 浏览器未登录,重定向到登录页
            return AuthResult.redirect("/login?from=" + path);
        }
        return AuthResult.allow();
    }
}

AuthResult 的三种返回结果

返回 HTTP 行为 适用场景
AuthResult.allow() 放行请求 已登录 / 无需鉴权
AuthResult.deny("原因") 403 + JSON {"error":"原因"} API 客户端(前端 fetch、OnlyOffice 回调等)
AuthResult.redirect("/login") 302 浏览器重定向 BFF 模式 — 未登录时跳转到登录页

需要鉴权的路径

默认仅对以 /file/view 和 /wopi 开头的路径进行鉴权。你可以通过 application.yml 自定义需要鉴权的路径:

file:
  view:
    auth:
      path-patterns:
        - /file/view/**    # 所有子路径
        - /wopi/**
        - /api/**           # 也保护自定义接口
        # - /**             # 拦截所有请求

支持的路径匹配模式:

模式 含义
/file/view 精确匹配
/file/* 直接子路径(一级)
/file/** 所有递归子路径

注意: 如果配置了 /**,请确保在 IAuth 实现中对登录接口放行,避免重定向死循环。

使用的第三方库

文件类型 第三方库
DOCX 文件 docx-preview + JSZip
XLSX 文件 SheetJS
PPTX 文件 pptxviewjs + Chart.js
业务流程管理文件 bpmn-js / cmmn-js / dmn-js
图片文件 Viewer.js
文档文件(PDF) PDFObject
文档文件(EPUB) epub.js + JSZip
文本文件/代码文件 highlight.js
Markdown文档文件 Vditor
CSV 文件 Papa Parse
3D 模型文件 Online 3D Viewer + Three.js
思维导图文件 xmind-embed-viewer
压缩文件 JSZip
CAD 文件(DWG/DXF) @mlightcad/cad-simple-viewer + Three.js
TIFF 图像文件 UTIF.js + pako
OFD 文件 xq-doc-viewer