# quil4j

**Repository Path**: feege/quil4j

## Basic Information

- **Project Name**: quil4j
- **Description**: 利用quil编辑器和java的poi,实现json数据->docx-json的转换
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quill 富文本编辑器

一个可直接运行的前后端分离示例。前端使用 Vue 3、Vite 和 Quill 2，后端使用 Spring Boot 3、Apache POI，并通过自定义转换器在 Quill Delta JSON 与 DOCX 之间转换。

目前支持普通文本、1～3 级标题、粗体、斜体、下划线、删除线、字体、字号、文字颜色、文字背景、字符间距、字偶距、脚本字体槽、语言、东亚标点排版、段落对齐、行距、段前/段后间距、首行缩进、分页、有序/无序列表、链接、按原尺寸导入图片和表格，以及 DOCX VML 横线。DOCX 表格会保留列宽、行高规则、固定/自动布局、表格缩进、六边独立边框、底色、单元格内混合文字样式、对齐方式以及横向/纵向合并单元格。导入结果还会通过 Delta 顶层 `documentAttributes` 保存页面尺寸、页边距、页眉页脚距离、栏间距、文档网格和可安全解码的内嵌字体，供浏览器预览及导出时写回。

## 项目结构

```text
frontend/   Vue 3 + Quill 2 编辑器
backend/    Spring Boot API + Apache POI 转换器
```

## 运行环境

- Java 17 或更高版本
- Maven 3.9+
- Node.js 18 或更高版本

## 启动

先启动后端：

```bash
cd backend
mvn spring-boot:run
```

再启动前端：

```bash
cd frontend
npm install
npm run dev
```

浏览器访问 `http://localhost:5173`。Vite 会把 `/api` 请求代理到 `http://localhost:8080`。

## Delta 数据协议

文本和行格式遵循 Quill Delta。标题与列表属性放在换行操作上：

```json
{
  "documentAttributes": {
    "pageWidth": 11906,
    "pageHeight": 16838,
    "marginTop": 1440,
    "marginRight": 1800,
    "marginBottom": 1440,
    "marginLeft": 1800,
    "documentGridType": "lines",
    "documentGridLinePitch": 312
  },
  "ops": [
    { "insert": "文档标题" },
    { "insert": "\n", "attributes": { "header": 1 } },
    { "insert": "粗体", "attributes": { "bold": true } },
    { "insert": " 和普通文本\n" },
    { "insert": "列表项" },
    { "insert": "\n", "attributes": { "list": "bullet" } }
  ]
}
```

图片使用 Quill 标准 image embed，目前前端保存为 Data URL：

```json
{
  "insert": { "image": "data:image/png;base64,..." },
  "attributes": { "width": "590", "height": "255" }
}
```

DOCX 中的 VML 横线使用自定义 `horizontalRule` embed，宽度、颜色、线型和粗细来自原始 shape 属性：

```json
{
  "insert": {
    "horizontalRule": {
      "width": "625px",
      "strokeWidth": "1.5pt",
      "color": "#000000",
      "style": "solid"
    }
  }
}
```

表格使用本项目定义的 table embed。旧版二维字符串数组仍兼容，新版单元格可以携带样式：

```json
{
  "insert": {
      "table": {
        "layout": "fixed",
        "indent": { "type": "dxa", "value": 120, "css": "8px" },
        "border": {
        "color": "#4472C4",
        "width": 1,
        "style": "solid",
        "top": { "color": "#4472C4", "width": 1, "style": "solid" },
        "right": { "color": "#4472C4", "width": 1, "style": "solid" },
        "bottom": { "color": "#4472C4", "width": 1, "style": "solid" },
        "left": { "color": "#4472C4", "width": 1, "style": "solid" },
        "insideH": { "color": "#4472C4", "width": 1, "style": "solid" },
        "insideV": { "color": "#4472C4", "width": 1, "style": "solid" }
      },
      "columnWidths": [40, 60],
      "cellPadding": { "top": "6px", "right": "8px", "bottom": "6px", "left": "8px" },
      "rows": [{
        "height": 540,
        "cells": [
          {
            "text": "姓名",
            "cellBackground": "#D9EAF7",
            "bold": true,
            "align": "center",
            "lineHeight": "18pt",
            "letterSpacing": "0.2pt"
          },
          { "text": "部门", "colSpan": 2 }
        ]
      }]
    }
  }
}
```

## API

| 方法 | 地址 | 用途 |
| --- | --- | --- |
| `POST` | `/api/documents` | 新建并保存 Delta 文档 |
| `GET` | `/api/documents/{id}` | 读取文档 |
| `PUT` | `/api/documents/{id}` | 更新文档 |
| `POST` | `/api/documents/import` | 上传 `.docx` 并转换为 Delta |
| `POST` | `/api/documents/export` | 提交 Delta 并下载 `.docx` |

保存接口的请求体格式：

```json
{
  "title": "示例文档",
  "content": { "ops": [{ "insert": "正文\n" }] }
}
```

当前 `DocumentService` 使用内存存储，适合演示和二次开发。生产环境可将它替换为 JPA/MyBatis 持久层，Delta 本身可作为 JSON/JSONB 字段保存；图片也建议改为对象存储 URL，避免数据库中保存大段 Base64。

DOCX 导入按原始段落、run、表格、表格样式和绘图 XML 解析，不依赖标题文字或固定上下文。Word 中没有对应 Quill Delta 字段的高级版式会通过自定义属性/embed 尽量保留，仍无法保证所有 Word 特性在编辑器中逐字节等价。

## 验证

```bash
cd frontend && npm run build
cd backend && mvn test
```

后端测试覆盖了文本、标题、列表、图片、VML 横线、原始表格边框和表格的 DOCX 往返转换。