wb04307201/file-view
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 文件预览
一个 Spring Boot 的轻量级文件在线预览 Starter 组件,通过简单的 Maven 依赖引入即可为项目提供 docx/xlsx/pptx/PDF/BPMN/图片/视频/代码/3D 模型/CAD 等 20+ 种文件格式的在线预览能力。
支持的文件类型
- 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
你也可以直接从文件管理器拖动文件到页面任意位置完成上传。

所有预览页面右上角均内置悬浮下载按钮,鼠标靠近时淡入显示,点击即可下载原始文件。
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为例说明如何扩展预览:
- 使用docker安装OnlyOffice文档开发者版
docker run --name onlyoffice -i -t -d -p 80:80 -e JWT_ENABLED=false -e ALLOW_PRIVATE_IP_ADDRESS=true onlyoffice/documentserver
- 文件预览渲染器扩展
编写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>
- 修改配置,关闭重复的渲染器,重定义文件匹配规则
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
预览效果如下:
文件存储扩展
下面以MinIO为例说明如何扩展文件存储:
- 使用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"
- 添加MinIO依赖:
<dependency>
<groupId>io.minio</groupId>
<artifactId>minio</artifactId>
<version>9.0.3</version>
</dependency>
- 编写接口
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 |