mirror of
https://gitee.com/ulthon/ulthon_information.git
synced 2026-07-01 16:02:48 +08:00
599 lines
25 KiB
Markdown
599 lines
25 KiB
Markdown
# 手机图片排版功能 - 架构文档
|
||
|
||
> 基于源代码实际阅读编写，记录排版引擎的设计原理与数据流。
|
||
|
||
## 1. 渲染管线
|
||
|
||
排版引擎的核心是 `PhoneImageEngine`（IIFE 闭包，`public/static/js/phone-image.js`），纯前端运行，后端不参与渲染计算。
|
||
|
||
### 1.1 管线总览
|
||
|
||
```
|
||
用户触发 doRender() 或编辑器 onChange 自动触发
|
||
|
|
||
v
|
||
PhoneImageEngine.render() -- L82: 管线入口，带并发锁
|
||
|
|
||
+---> editorHtml = window.phoneImageEditor.getHtml() -- L99: 从 wangeditor 读取HTML
|
||
+---> preprocessContent(editorHtml) -- L154: 清洗HTML（去script/style/iframe，规范化img）
|
||
+---> parseHtmlToBlocks(cleanHtml) -- L201: HTML -> 块级元素数组，<hr> 识别为 page-break
|
||
|
|
||
+---> generateCoverPage(sizeConfig) -- L619: 生成封面页HTML
|
||
|
|
||
+---> captureEditorBlocks(editorHtml, blocks, areaHeight, sizeConfig) -- L345: DOM测高核心
|
||
| |
|
||
| +---> 按 page-break(<hr>) 将 blocks 分组 -- L349-365
|
||
| +---> getEditorChildren() -- L323: 穿透 div 包装层获取编辑器DOM子元素
|
||
| +---> 创建 500px 测量容器（fixed, visibility:hidden） -- L376-387
|
||
| +---> 串行测高每组：DOM克隆到测量容器 -> getBoundingClientRect -- L392-433
|
||
| +---> 按比例分配实际高度给组内各 block -- L421-428
|
||
| +---> paginateContent(blocks, contentAreaHeight, sizeConfig) -- L445: 按高度累加分页
|
||
|
|
||
+---> generateSummaryPage(sizeConfig, totalPages) -- L731: 生成尾页HTML
|
||
+---> 页码补全 N/M -- L122-129: 二次遍历替换占位页码
|
||
+---> renderThumbnails(sizeConfig) -- L968: 截图 -> 显示右侧缩略图
|
||
|
|
||
+---> doCapturePages({scale:1}) -- L841: staging隐藏区域渲染 + html2canvas串行截图
|
||
|
|
||
+---> 纯图片页优化: 直接用 Image + Canvas，跳过 html2canvas -- L805-830
|
||
```
|
||
|
||
### 1.2 并发控制
|
||
|
||
`render()` 函数使用 `_locked` 标志防止并发渲染（`phone-image.js:86-91`）。渲染期间如果有新请求，设置 `_pending = true`，当前渲染完成后自动重试（`phone-image.js:134-137`）。
|
||
|
||
### 1.3 DOM 测高机制
|
||
|
||
`captureEditorBlocks`（`phone-image.js:345-437`）是管线中替代旧版 `renderContentFlow` + `measureBlockHeights` 的核心函数。工作流程：
|
||
|
||
1. 按 `page-break` 类型将 blocks 分为若干组
|
||
2. 通过 `getEditorChildren()` 获取 wangeditor 编辑区的真实 DOM 子元素
|
||
3. 创建 500px 宽的隐藏测量容器（fixed 定位，`visibility:hidden`），与内容区宽度（540 - 20*2 padding）一致
|
||
4. 对每组：将对应的 DOM 子元素克隆到测量容器，通过 `requestAnimationFrame` 后读取 `getBoundingClientRect().height` 获取实际高度
|
||
5. 按各 block 估算高度的比例，将测量的实际高度分配给组内各 block
|
||
6. 所有组测高完成后，调用 `paginateContent` 进行分页
|
||
|
||
### 1.4 截图机制
|
||
|
||
截图在 `#render-staging` 隐藏区域进行（`phone-image.html:597`）。关键步骤：
|
||
|
||
1. 将所有页面HTML append到 staging 区域的 `.phone-image-container` 容器中
|
||
2. 临时将 `visibility:hidden` 切为 `visible`（html2canvas 会跳过隐藏元素）
|
||
3. 串行逐页调用 html2canvas 截图（`runCaptureLoop`, L881）
|
||
4. 纯图片页优化：直接用 `Image + Canvas` 绘制，跳过 html2canvas（`phone-image.js:805-830`）
|
||
5. 截图完成后恢复 `visibility:hidden`
|
||
|
||
缩略图用 `scale:1`，保存用 `scale:2`（输出1080px宽度）。
|
||
|
||
### 1.5 getEditorChildren 穿透逻辑
|
||
|
||
`getEditorChildren()`（`phone-image.js:323-334`）处理 wangeditor v5 的 DOM 包装层。wangeditor 的 `[data-slate-editor]` 下可能有一层 `<div>` 包装，该函数检测到这种情况时穿透到内层子元素，返回实际的内容节点数组。这对 `captureEditorBlocks` 的 DOM 克隆测高和 `exportLongImage` 的长图导出都至关重要。
|
||
|
||
## 2. wangeditor 集成
|
||
|
||
### 2.1 编辑器初始化
|
||
|
||
编辑器在 `phone_image.html` 模板脚本中初始化（L192-288）：
|
||
|
||
```javascript
|
||
var E = window.wangEditor;
|
||
var phoneImageEditor = E.createEditor({
|
||
selector: '#editor-text-area',
|
||
html: postData.contentHtml, // 初始内容，来自服务端渲染
|
||
config: editorConfig
|
||
});
|
||
var toolbar = E.createToolbar({
|
||
editor: phoneImageEditor,
|
||
selector: '#editor-toolbar',
|
||
config: {
|
||
excludeKeys: ['fullScreen'],
|
||
insertKeys: {
|
||
index: 24,
|
||
keys: ['divider'] // 分割线按钮，插入位置 index 24
|
||
}
|
||
}
|
||
});
|
||
window.phoneImageEditor = phoneImageEditor; // 全局引用
|
||
```
|
||
|
||
### 2.2 工具栏配置
|
||
|
||
- 排除 `fullScreen` 按钮
|
||
- 在 index 24 位置插入 `divider`（分割线）按钮
|
||
- 其余使用 wangeditor 默认按钮集
|
||
|
||
### 2.3 分割线与分页的关系
|
||
|
||
wangeditor 的 `divider` 按钮在编辑器中插入 `<hr>` 元素（带 `data-w-e-type="divider"` 属性）。渲染管线中 `parseHtmlToBlocks` 将 `<hr>` 识别为 `page-break` 类型的块（`phone-image.js:259-263`），`paginateContent` 遇到 `page-break` 时强制换页（`phone-image.js:455-466`）。`captureEditorBlocks` 也按 `page-break` 对 blocks 分组测高。
|
||
|
||
### 2.4 粘贴处理
|
||
|
||
`editorConfig.customPaste`（`phone_image.html:220-268`）拦截粘贴操作，将外部图片（`http` 开头的URL图片和 `data:` 开头的 base64 图片）上传到服务器后替换为本地URL，确保编辑器中的图片资源可控。
|
||
|
||
### 2.5 DOM 结构
|
||
|
||
```
|
||
div.content-flow-area (540px, overflow-y:auto)
|
||
+-- div#editor-toolbar (wangeditor 工具栏)
|
||
+-- div#editor-text-area (wangeditor 编辑区)
|
||
+-- div[data-slate-editor] (wangeditor 内部)
|
||
+-- div (可能的包装层)
|
||
+-- p / h1 / img / hr(divider) / ... (实际内容节点)
|
||
```
|
||
|
||
## 3. 数据流
|
||
|
||
### 3.1 数据源模型
|
||
|
||
重构后，wangeditor 编辑器成为运行时的权威内容源。引擎闭包变量 `postData.content_html` 仅作为初始化回退。
|
||
|
||
**权威数据源**：`window.phoneImageEditor.getHtml()`，通过 `getContentHtml()` API 统一访问（`phone-image.js:1280-1285`）：
|
||
|
||
```javascript
|
||
getContentHtml: function () {
|
||
if (window.phoneImageEditor) {
|
||
return window.phoneImageEditor.getHtml();
|
||
}
|
||
return postData.content_html; // 回退
|
||
}
|
||
```
|
||
|
||
**引擎公开 API**：
|
||
|
||
| API | 位置 | 用途 |
|
||
|-----|------|------|
|
||
| `getContentHtml()` | `phone-image.js:1280-1285` | 优先从 wangeditor 读取HTML，回退到闭包变量 |
|
||
| `updateConfig(newConfig)` | `phone-image.js:1286-1290` | 使用 `$.extend(config, newConfig)` 更新配置，不重置内容 |
|
||
| `saveConfig(postId, saveConfig, url)` | `phone-image.js:1138-1170` | 保存配置到服务端（不生成图片），返回 `{output_id}` |
|
||
| `saveImages(postId, saveConfig)` | `phone-image.js:1079-1129` | 截图并保存所有页面图片到服务端 |
|
||
| `exportLongImage()` | `phone-image.js:1192-1257` | 从编辑器DOM导出完整长图 |
|
||
|
||
**DOM `#post-content-html` 的角色**：仅作为初始化数据源（`phone_image.html:105`）和保存后的显示同步层（`phone_image.html:434,459`），保存操作不从中读取内容。
|
||
|
||
### 3.2 各操作的数据流
|
||
|
||
```
|
||
保存配置 (#btn-save):
|
||
content_html 取自 PhoneImageEngine.getContentHtml() -- L431
|
||
调用 PhoneImageEngine.saveConfig() API -- L428-432
|
||
保存后同步: $('#post-content-html').html(getContentHtml()) -- L434
|
||
|
||
生成并保存 (#btn-generate):
|
||
content_html 取自 PhoneImageEngine.getContentHtml() -- L454
|
||
调用 PhoneImageEngine.saveImages() API -- L451-455
|
||
保存后同步: $('#post-content-html').html(getContentHtml()) -- L459
|
||
|
||
重新排版 (doRender):
|
||
用 PhoneImageEngine.updateConfig(newConfig) -- L344
|
||
再调 PhoneImageEngine.render() -- L346
|
||
|
||
自动保存 (onChange):
|
||
wangeditor onChange -> 2.6s 防抖 -> doAutoSave() -- phone_image.html:209-216
|
||
doAutoSave 调用 PhoneImageEngine.saveConfig() -- phone_image.html:403-413
|
||
|
||
加载历史 (loadFromHistory):
|
||
window.phoneImageEditor.setHtml(res.data.content_html) -- phone_image.html:561 (加载到编辑器)
|
||
PhoneImageEngine.updateConfig(historyConfig) -- phone_image.html:578
|
||
PhoneImageEngine.render() -- phone_image.html:580
|
||
|
||
导出长图 (更多菜单 -> exportLong):
|
||
PhoneImageEngine.exportLongImage() -- phone_image.html:484
|
||
内部: getEditorChildren() -> 克隆非divider元素 -> html2canvas scale=2 -> 下载PNG
|
||
```
|
||
|
||
### 3.3 自动保存机制
|
||
|
||
编辑器内容变更时触发自动保存（`phone_image.html:206-413`）：
|
||
|
||
1. `editorConfig.onChange` 触发，设置 `autoSaveLock = true`，显示"等待保存..."状态
|
||
2. 清除之前的防抖定时器，设置新的 2.6 秒定时器
|
||
3. 定时器到期后调用 `doAutoSave()`
|
||
4. `doAutoSave()` 检查 `autoSaveLock`，通过 `PhoneImageEngine.saveConfig()` 发送保存请求
|
||
5. 保存状态通过 `#save-state` 指示器反馈（waiting/saving/saved/error，`phone_image.html:388-397`）
|
||
|
||
手动保存按钮点击时会清除自动保存定时器，避免冲突。
|
||
|
||
### 3.4 完整数据流图
|
||
|
||
```
|
||
[数据库 Post.content_html]
|
||
|
|
||
v
|
||
Post.php::phoneImage() (L355)
|
||
查询 PostOutput 取已保存的 content_html 副本
|
||
|
|
||
v
|
||
phone_image.html 模板渲染
|
||
- $layoutContentHtml (优先用已保存副本)
|
||
- $layoutConfig (已保存的配置)
|
||
|
|
||
v
|
||
前端初始化 (phone_image.html:152-294)
|
||
1. 构造 postData 局部对象，contentHtml 取自 #post-content-html (L173)
|
||
2. 恢复 savedConfig (L181-186)
|
||
3. wangeditor 初始化，html=postData.contentHtml (L270-274)
|
||
4. window.phoneImageEditor = phoneImageEditor (L288)
|
||
5. PhoneImageEngine.init(postData, initConfig) (L290)
|
||
6. doRender() 触发初始渲染 (L594)
|
||
|
|
||
v
|
||
渲染管线 (phone-image.js render())
|
||
- 读取 window.phoneImageEditor.getHtml() (唯一权威源)
|
||
- parseHtmlToBlocks + captureEditorBlocks(测高) + paginateContent(分页)
|
||
- staging 渲染 + html2canvas 截图
|
||
- 显示缩略图
|
||
|
|
||
v
|
||
用户交互
|
||
- 编辑内容 -> wangeditor -> onChange 自动保存(2.6s防抖)
|
||
- 分割线 -> wangeditor divider -> <hr> -> page-break 分页
|
||
- 保存配置 -> PhoneImageEngine.saveConfig() (content_html 取自 getContentHtml())
|
||
- 生成保存 -> PhoneImageEngine.saveImages() (content_html 取自 getContentHtml())
|
||
- 重新排版 -> updateConfig() + render()
|
||
- 加载历史 -> editor.setHtml() + updateConfig() + render()
|
||
- 导出长图 -> exportLongImage() (从编辑器DOM直接截图)
|
||
|
|
||
v
|
||
后端存储
|
||
- PostOutput.config (JSON字段，含 content_html 副本)
|
||
- PostOutputFile (每页图片文件记录)
|
||
```
|
||
|
||
## 4. 存储模型
|
||
|
||
### 4.1 数据库表
|
||
|
||
**`ul_post_output`** (模型: `app/model/PostOutput.php`)
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `id` | 主键 |
|
||
| `post_id` | 关联文章ID |
|
||
| `output_type` | 输出类型，固定为 `phone_image` |
|
||
| `config` | JSON字段，存储完整配置 + content_html 副本 |
|
||
| `status` | 0=生成中, 1=已完成, 2=失败 (常量定义 L20-22) |
|
||
| `page_count` | 页数 |
|
||
| `admin_id` | 操作管理员ID |
|
||
| `create_time` | 创建时间 (int) |
|
||
| `delete_time` | 软删除标记 (默认0，trait: SoftDelete) |
|
||
|
||
模型使用 `$json = ['config']` 自动序列化/反序列化配置（`PostOutput.php:18`）。
|
||
|
||
**`ul_post_output_file`** (模型: `app/model/PostOutputFile.php`)
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `id` | 主键 |
|
||
| `output_id` | 关联 post_output.id |
|
||
| `page` | 页码 (从1开始) |
|
||
| `file_path` | 相对路径，如 `/upload/post_output/20260511/5_1.jpg` |
|
||
| `file_url` | 访问URL (同 file_path) |
|
||
| `file_size` | 文件字节数 |
|
||
| `width` | 图片宽度 (px) |
|
||
| `height` | 图片高度 (px) |
|
||
|
||
关系: `PostOutput hasMany PostOutputFile`，`PostOutput belongsTo Post`。
|
||
|
||
### 4.2 config JSON 结构
|
||
|
||
```json
|
||
{
|
||
"size": "xiaohongshu",
|
||
"watermark": "",
|
||
"pageAlignments": { "1": "top", "2": "center" },
|
||
"content_html": "<p>文章HTML副本</p><hr><p>第二页内容</p>"
|
||
}
|
||
```
|
||
|
||
`content_html` 作为配置的一部分保存，使每次排版记录都携带当时的内容快照。含 `<hr>` 分页标记的 HTML 被完整保存，`parseHtmlToBlocks` 可以正确解析。
|
||
|
||
**向后兼容**：旧版 PostOutput 记录中保存的 `<hr>` 分页标记仍可被 `parseHtmlToBlocks` 正确识别为 `page-break`（`phone-image.js:259-263`），不影响历史记录加载和重新排版。
|
||
|
||
### 4.3 loadFromHistory 加载机制
|
||
|
||
```
|
||
loadFromHistory(outputId)
|
||
-> GET loadPostOutputConfig?id=XXX
|
||
-> window.phoneImageEditor.setHtml(res.data.content_html) -- 加载到编辑器
|
||
-> PhoneImageEngine.updateConfig(historyConfig) -- 更新配置
|
||
-> PhoneImageEngine.render() -- 重新渲染
|
||
```
|
||
|
||
不再使用 `init()` 全量重置，而是通过 `editor.setHtml()` 直接将历史内容加载到 wangeditor，然后 `updateConfig()` 更新配置后重新渲染。
|
||
|
||
### 4.4 文件存储
|
||
|
||
图片保存到 `public/upload/post_output/{Ymd}/{outputId}_{page}.jpg`（`PhoneImage.php:87-92`）。ZIP 临时文件生成到 `runtime/temp/` 目录，请求结束后通过 `register_shutdown_function` 清理（`Post.php:570-575`）。
|
||
|
||
## 5. wangeditor 配置与工具栏
|
||
|
||
### 5.1 编辑器配置
|
||
|
||
```javascript
|
||
editorConfig = {
|
||
MENU_CONF: {},
|
||
placeholder: '请输入排版内容，使用分割线标记分页位置',
|
||
scroll: false,
|
||
MENU_CONF: {
|
||
'uploadImage': {
|
||
server: '{:url("File/wangEditorSave")}',
|
||
fieldName: 'file',
|
||
meta: { type: 'editor' }
|
||
}
|
||
},
|
||
onChange: function(editor) { /* 自动保存 2.6s 防抖 */ },
|
||
customPaste: function(editor, event) { /* 外部图片上传处理 */ }
|
||
}
|
||
```
|
||
|
||
### 5.2 工具栏配置
|
||
|
||
```javascript
|
||
toolbar config = {
|
||
excludeKeys: ['fullScreen'],
|
||
insertKeys: {
|
||
index: 24, // 在第24个按钮位置后插入
|
||
keys: ['divider'] // 分割线按钮
|
||
}
|
||
}
|
||
```
|
||
|
||
保留 wangeditor 所有默认按钮（粗体、斜体、标题、列表、引用、图片、链接等），额外添加分割线按钮用于手动标记分页位置。
|
||
|
||
## 6. 配置体系
|
||
|
||
### 6.1 PHP 端配置字段定义
|
||
|
||
`PhoneImage::getConfigFields()` 定义了4个字段：
|
||
|
||
| 字段 | 类型 | 选项/范围 | 默认值 |
|
||
|------|------|-----------|--------|
|
||
| `size` | select | xiaohongshu/douyin | xiaohongshu |
|
||
| `fontSize` | number | 10-24 | 14 |
|
||
| `watermark` | text | - | '' |
|
||
| `pageAlignments` | json | - | '{}' |
|
||
|
||
### 6.2 JS 端实际使用的配置
|
||
|
||
`phone-image.js` 闭包内的 `config` 对象 (L14-23)：
|
||
|
||
```javascript
|
||
config = {
|
||
size: 'xiaohongshu',
|
||
watermark: '',
|
||
pageAlignments: {}, // 逐页对齐
|
||
sizes: { ... }, // 尺寸预设
|
||
contentPadding: 20
|
||
}
|
||
```
|
||
|
||
### 6.3 设置弹框
|
||
|
||
通过 layui layer 弹框实现（`phone_image.html:293-330`），提供：
|
||
- 尺寸选择：小红书 (1080x1440) / 抖音 (1080x1920)
|
||
- 水印输入：可选水印文字
|
||
|
||
确认后自动触发 `doRender()` 重新排版。
|
||
|
||
### 6.4 自动保存状态指示器
|
||
|
||
`<span id="save-state">` 元素（`phone_image.html:417`）动态显示保存状态：
|
||
- `waiting`：黄色，"等待保存..."
|
||
- `saving`：蓝色，"保存中..."
|
||
- `saved`：绿色，"已保存"
|
||
- `error`：红色，"保存失败"
|
||
|
||
## 7. UI 布局
|
||
|
||
### 7.1 整体结构
|
||
|
||
两栏布局，适配宽屏操作：
|
||
|
||
```
|
||
+----------------------------------------------------------+
|
||
| page-header (顶部操作栏) |
|
||
| [返回列表] 标题 [设置] [保存] [生成并保存] [更多v] 已保存 |
|
||
+------------------------------+---------------------------+
|
||
| content-flow-area (540px) | paginated-preview-area |
|
||
| +--------------------------+ | (flex:1, 横向滚动) |
|
||
| | #editor-toolbar | | |
|
||
| | (wangeditor工具栏) | | [缩略图1] [缩略图2] ... |
|
||
| +--------------------------+ | 每张带页码和对齐按钮 |
|
||
| | #editor-text-area | | |
|
||
| | (wangeditor编辑区) | | |
|
||
| | min-height:300px | | |
|
||
| +--------------------------+ | |
|
||
+------------------------------+---------------------------+
|
||
```
|
||
|
||
### 7.2 顶部操作栏
|
||
|
||
按钮直接显示：设置、保存、生成并保存。"更多"下拉菜单（纯 JS 实现，`phone_image.html:358-385`）包含：历史记录、重新生成、打包下载、导出长图。
|
||
|
||
layui 2.x 没有 dropdown 模块，更多菜单用纯 JS 实现的 `toggle` + `stopPropagation` + 外部点击关闭。
|
||
|
||
### 7.3 缩略图区域
|
||
|
||
右侧缩略图横向排列，每个缩略图带页码标签和对齐切换按钮（仅内容页显示，`phone-image.js:1017-1025`）。对齐按钮切换 `top`/`center` 垂直对齐。
|
||
|
||
## 8. 已删除的函数/组件
|
||
|
||
wangeditor 重构中移除的旧版函数和组件：
|
||
|
||
### 8.1 渲染管线相关
|
||
|
||
| 已删除函数 | 说明 |
|
||
|-----------|------|
|
||
| `renderContentFlow` | 旧版将块渲染到中间栏 `#content-flow`，已由 wangeditor 编辑器替代 |
|
||
| `convertFlowBlocksToImages` | 旧版表格/代码块预转换（html2canvas截图替换为img），新版不再需要 |
|
||
| `measureBlockHeights` | 旧版从中间栏DOM读取实测高度，已由 `captureEditorBlocks` 的测量容器方案替代 |
|
||
| `insertPageBreak` | 旧版中间栏"+"按钮插入分页标记，已由 wangeditor divider 替代 |
|
||
| `removePageBreak` | 旧版中间栏"-"按钮移除分页标记，已由编辑器直接删除 divider 替代 |
|
||
|
||
### 8.2 高度估算相关
|
||
|
||
| 已删除函数 | 说明 |
|
||
|-----------|------|
|
||
| `estimateTextHeight` | 旧版纯计算估算段落高度，已由 DOM 测量替代 |
|
||
| `estimateHeadingHeight` | 旧版估算标题高度 |
|
||
| `estimateListHeight` | 旧版估算列表高度 |
|
||
| `estimateBlockquoteHeight` | 旧版估算引用块高度 |
|
||
|
||
### 8.3 工具函数
|
||
|
||
| 已删除函数 | 说明 |
|
||
|-----------|------|
|
||
| `simpleHash` | 旧版 djb2 哈希，用于 `convertedBlockCache` 缓存key |
|
||
| `getContentWidth` | 旧版获取内容区宽度 |
|
||
|
||
### 8.4 UI 组件
|
||
|
||
| 已删除组件 | 说明 |
|
||
|-----------|------|
|
||
| `#content-flow` 中间栏 | 旧版内容渲染和交互区域，已由 wangeditor 编辑器替代 |
|
||
| 左侧工具栏 | 旧版编辑操作面板（分页标记按钮等） |
|
||
| `convertedBlockCache` | 旧版表格/代码块截图缓存，新版不再预转换 |
|
||
|
||
## 9. 已知限制
|
||
|
||
### 9.1 html2canvas 兼容性
|
||
|
||
html2canvas 截图不支持以下 CSS 特性：
|
||
- `transform`
|
||
- `filter`
|
||
- `clip-path`
|
||
- `backdrop-filter`
|
||
- CSS grid
|
||
- `object-fit`
|
||
|
||
在 wangeditor 编辑器和自定义样式中应避免使用这些属性，否则截图中可能显示异常。
|
||
|
||
### 9.2 wangeditor divider 特性
|
||
|
||
wangeditor 的 divider 是 void 元素，`::after` 伪元素可能不生效。编辑器中 divider 的视觉样式依赖 wangeditor 内部 CSS。
|
||
|
||
### 9.3 layui dropdown 缺失
|
||
|
||
layui 2.x 没有 dropdown 模块，"更多"菜单用纯 JS 实现（`phone_image.html:358-385`），包括 `toggle` 显示/隐藏、`stopPropagation` 阻止冒泡、全局 `click` 事件关闭。
|
||
|
||
### 9.4 保存数据量限制
|
||
|
||
`saveImages()` 有16MB的客户端检查（`phone-image.js:1096-1100`），但服务端没有对应的分块接收机制。大文章（超过约30页）的base64数据可能超出 PHP `post_max_size` 配置。
|
||
|
||
### 9.5 目录权限 0777
|
||
|
||
`PhoneImage.php:95` 和 `:140` 中 `mkdir` 使用 0777 权限，与项目其他位置的 anti-pattern 一致。
|
||
|
||
### 9.6 接口 `PostOutputManagerInterface` 未被充分利用
|
||
|
||
`PhoneImage` 实现了 `process()` 和 `getPreview()` 方法，但两者都返回空值（`PhoneImage.php:56-67`）。实际业务完全在控制器中直接调用 `PhoneImage` 的其他方法，绕过了接口定义的流程。接口仅作为类型约束存在。
|
||
|
||
### 9.7 `saveConfigOnly` 是静态方法但 `createOutput` 是实例方法
|
||
|
||
`PhoneImage::saveConfigOnly()` 是 static 方法（L223），而同类的 `createOutput()` 是实例方法（L193）。两者的实现几乎相同（都是 `PostOutput::create()`），但调用方式不同。控制器中 `savePostOutput` 通过实例调用 `createOutput`，`savePostOutputConfig` 通过静态调用 `saveConfigOnly`，风格不统一。
|
||
|
||
## 10. API 端点清单
|
||
|
||
所有端点位于 `app/admin/controller/Post.php`，通过 ThinkPHP 自动路由访问，URL前缀为 `/index.php/admin/post/`。
|
||
|
||
| 端点 | 方法 | 说明 | 前端调用方 |
|
||
|------|------|------|-----------|
|
||
| `phoneImage/{id}` | GET | 排版操作页（渲染模板） | 页面跳转 |
|
||
| `savePostOutput` | POST (JSON) | 保存输出记录+图片 | `PhoneImageEngine.saveImages()` (phone-image.js:1103) |
|
||
| `savePostOutputConfig` | POST (JSON) | 仅保存配置（不生成图片） | `PhoneImageEngine.saveConfig()` (phone-image.js:1152) |
|
||
| `loadPostOutputConfig` | GET | 加载历史记录配置 | `loadFromHistory()` (phone_image.html:550) |
|
||
| `getOutputListJson` | GET | 获取输出记录列表 | 历史弹窗 (phone_image.html:504) |
|
||
| `deletePostOutput` | POST/GET | 删除输出记录及文件 | 未在前端模板中直接调用 |
|
||
| `regeneratePostOutput` | POST/GET | 删除旧记录，返回配置 | 未在前端模板中直接调用 |
|
||
| `downloadPostOutputZip/{id}` | GET | 打包下载ZIP | 更多菜单 -> 打包下载 |
|
||
| `postOutputList/{id}` | GET | 输出管理列表页 | 独立页面入口 |
|
||
|
||
### 请求/响应格式
|
||
|
||
**savePostOutput** 请求体:
|
||
```json
|
||
{
|
||
"post_id": 123,
|
||
"output_type": "phone_image",
|
||
"config": { "size": "...", "watermark": "...", ... },
|
||
"content_html": "<p>...</p>",
|
||
"pages": ["data:image/jpeg;base64,..."]
|
||
}
|
||
```
|
||
|
||
**savePostOutputConfig** 请求体:
|
||
```json
|
||
{
|
||
"post_id": 123,
|
||
"output_type": "phone_image",
|
||
"config": { "size": "...", "watermark": "...", "pageAlignments": {} },
|
||
"content_html": "<p>...</p>"
|
||
}
|
||
```
|
||
|
||
**通用响应格式**:
|
||
```json
|
||
{ "code": 0, "msg": "", "data": { "output_id": 456 } }
|
||
```
|
||
失败时 `code` 为 500。
|
||
|
||
## 11. 修复记录
|
||
|
||
### 11.1 数据源统一修复（wangeditor 重构前）
|
||
|
||
**修复日期**：2026-05-11
|
||
|
||
**核心原理**：将三个独立的数据源（DOM、闭包变量、模板局部变量）统一为单一权威数据源，通过新增的引擎 API 对外暴露。
|
||
|
||
**变更清单**：
|
||
|
||
| 变更 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| 新增 `getContentHtml()` | `phone-image.js:1280-1285` | 优先从 wangeditor 读取，回退到闭包变量 |
|
||
| 新增 `updateConfig(newConfig)` | `phone-image.js:1286-1290` | 使用 `$.extend` 更新配置，不重置内容 |
|
||
| 新增 `saveConfig()` API | `phone-image.js:1138-1170` | 引擎级保存配置方法 |
|
||
| 新增 `exportLongImage()` | `phone-image.js:1192-1257` | 从编辑器DOM导出长图 |
|
||
| 保存按钮改用 `getContentHtml()` | `phone_image.html:431` | content_html 取自引擎 API |
|
||
| 生成按钮改用 `getContentHtml()` | `phone_image.html:454` | content_html 取自引擎 API |
|
||
| 自动保存机制 | `phone_image.html:206-413` | onChange 2.6s 防抖自动保存 |
|
||
| `doRender` 改用 `updateConfig()` | `phone_image.html:344` | 替代 `init()` 调用 |
|
||
| `loadFromHistory` 用 `editor.setHtml()` | `phone_image.html:561` | 加载到编辑器而非重置引擎 |
|
||
|
||
### 11.2 wangeditor 重构
|
||
|
||
**重构日期**：2026-05-11
|
||
|
||
**核心变更**：将内容编辑从旧版中间栏（`#content-flow` + 手动分页标记）迁移到 wangeditor 富文本编辑器。
|
||
|
||
**主要变更**：
|
||
|
||
| 变更 | 说明 |
|
||
|------|------|
|
||
| 引入 wangeditor v5 | 替代旧版中间栏内容展示和编辑 |
|
||
| 新增 `captureEditorBlocks` | DOM 测量方案替代旧版高度估算 |
|
||
| 新增 `getEditorChildren` | 穿透 wangeditor DOM 包装层 |
|
||
| 新增 `exportLongImage` | 从编辑器DOM导出完整长图 |
|
||
| 分割线替代分页标记按钮 | wangeditor divider (`<hr>`) = page-break |
|
||
| 自动保存 | 编辑器 onChange 触发 2.6s 防抖保存 |
|
||
| 更多菜单纯 JS 实现 | 替代 layui dropdown（不存在） |
|
||
| 删除旧版渲染管线 | renderContentFlow / convertFlowBlocksToImages / measureBlockHeights 等 |
|
||
| 删除旧版高度估算 | estimateTextHeight 等，由 DOM 测量替代 |
|
||
| 删除旧版 UI | 左侧工具栏、中间栏交互 |
|
||
|
||
**重构效果**：
|
||
- 内容编辑体验从"预览+标记"模式变为"所见即所得"编辑模式
|
||
- 分页标记通过分割线直观可见和可编辑
|
||
- 自动保存减少手动操作
|
||
- DOM 测量替代估算，分页精度提升
|
||
|
||
---
|
||
|
||
*文档基于以下源文件的完整阅读:*
|
||
- `public/static/js/phone-image.js` (1292行)
|
||
- `view/admin/post/phone_image.html` (600行)
|
||
- `app/admin/controller/Post.php` (L350-579)
|
||
- `app/common/tools/PhoneImage.php` (229行)
|
||
- `app/common/tools/PostOutputManagerInterface.php` (28行)
|
||
- `app/model/PostOutput.php` (62行)
|
||
- `app/model/PostOutputFile.php` (26行)
|