307 lines
9.2 KiB
Markdown
307 lines
9.2 KiB
Markdown
# HTML 预览架构优化
|
||
|
||
> 解决 Wails WebView 中 HTML 预览闪烁问题，优化资源路径处理
|
||
|
||
## 📋 目录
|
||
|
||
- [问题背景](#问题背景)
|
||
- [架构对比](#架构对比)
|
||
- [解决方案](#解决方案)
|
||
- [核心实现](#核心实现)
|
||
- [API 文档](#api-文档)
|
||
- [代码规范](#代码规范)
|
||
|
||
---
|
||
|
||
## 🔍 问题背景
|
||
|
||
### 现象
|
||
|
||
在 u-desk（Wails 桌面应用）中预览 HTML 文件时，点击链接切换到另一个 HTML 文件有明显闪烁，而在普通浏览器中不明显。
|
||
|
||
### 根因分析
|
||
|
||
1. **双重更新周期**：`selectedFileItem` 和 `fileContent` 分开更新，导致两次 Vue 渲染
|
||
2. **srcdoc 机制**：每次内容变化，iframe 完全重新解析 HTML
|
||
3. **WebView 差异**：Wails WebView2 对 srcdoc 处理比 Chrome 慢
|
||
|
||
### 技术债务
|
||
|
||
| 问题 | 影响 | 优先级 |
|
||
|------|------|--------|
|
||
| 前端路径转换逻辑复杂 | 维护困难 | P1 |
|
||
| 重复渲染导致闪烁 | 用户体验差 | P0 |
|
||
| 代码分散在前端 | 架构不清晰 | P2 |
|
||
|
||
---
|
||
|
||
## 🏗️ 架构对比
|
||
|
||
### 优化前
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端处理 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
||
│ │ 读取文件 │ → │ convertHtmlPaths │ → │ htmlContent │ │
|
||
│ │ fileContent│ │ 处理相对路径 │ │ WithTheme │ │
|
||
│ └──────────┘ └──────────────────┘ └───────┬───────┘ │
|
||
│ ↓ │
|
||
│ ┌───────────┐ │
|
||
│ │ srcdoc │ │
|
||
│ └───────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**问题**：
|
||
- srcdoc 每次变化都重新解析
|
||
- 前端逻辑复杂（200+ 行）
|
||
- 主题切换需要重新渲染
|
||
|
||
### 优化后
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端 后端 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────┐ ┌─────────────┐ │
|
||
│ │ 预览URL │ → /localfs/html-preview │ 读取HTML │ │
|
||
│ │ 生成 │ ?path=xxx │ 转换路径 │ │
|
||
│ └─────┬────┘ │ 注入脚本 │ │
|
||
│ ↓ └──────┬──────┘ │
|
||
│ ┌───────────┐ ↓ │
|
||
│ │ iframe │ ←──────────────────────── 返回处理后的HTML │
|
||
│ │ src │ │
|
||
│ └───────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**优点**：
|
||
- iframe 导航而非重建，无闪烁
|
||
- 浏览器可缓存
|
||
- 前端代码简化（减少 200+ 行）
|
||
|
||
---
|
||
|
||
## ✅ 解决方案
|
||
|
||
### 核心变更
|
||
|
||
| 变更 | 说明 |
|
||
|------|------|
|
||
| 使用 `:src` 替代 `:srcdoc` | iframe 导航而非重建 |
|
||
| 后端统一处理路径转换 | 前端逻辑移至后端 |
|
||
| 支持 CSS/JS 文件路径转换 | 动态 import 也正确解析 |
|
||
|
||
### 修改文件
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `internal/filesystem/asset_handler.go` | 新增路由、路径转换函数 |
|
||
| `frontend/.../FileEditorPanel.vue` | 改用 `:src`，移除前端处理逻辑 |
|
||
|
||
---
|
||
|
||
## 🔧 核心实现
|
||
|
||
### 1. 后端路由
|
||
|
||
```go
|
||
// 注册路由
|
||
mux.HandleFunc("/localfs/html-preview", handleHtmlPreviewRequest)
|
||
```
|
||
|
||
### 2. 预编译正则表达式
|
||
|
||
```go
|
||
var (
|
||
// CSS 相关
|
||
cssImportRegex = regexp.MustCompile(`@import\s+(?:url\s*\(\s*)?["']([^"']+)["']\s*\)?\s*;`)
|
||
cssUrlRegex = regexp.MustCompile(`url\(\s*["']?([^"')]+)["']?\s*\)`)
|
||
|
||
// HTML 标签
|
||
htmlLinkTagRegex = regexp.MustCompile(`<link\s+([^>]*)>`)
|
||
htmlScriptTagRegex = regexp.MustCompile(`<script\s+([^>]*)>`)
|
||
// ... 其他标签
|
||
|
||
// ES6 模块语句
|
||
es6ImportFromRegex = regexp.MustCompile(`import\s+([\s\S]*?)\s+from\s+["']([^"']+)["']`)
|
||
es6DynamicImport = regexp.MustCompile(`import\s*\(\s*["']([^"']+)["']\s*\)`)
|
||
es6BareImport = regexp.MustCompile(`(?m)^\s*import\s+["']([^"']+)["']`)
|
||
)
|
||
```
|
||
|
||
### 3. 统一路径解析
|
||
|
||
```go
|
||
// resolveHtmlPathToUrl 统一处理相对路径和绝对路径
|
||
func resolveHtmlPathToUrl(baseDir string, path string) string {
|
||
// 处理以 / 开头的绝对路径
|
||
if strings.HasPrefix(path, "/") {
|
||
path = path[1:]
|
||
}
|
||
// ... 解析并转换为 /localfs/ URL
|
||
}
|
||
```
|
||
|
||
### 4. 文件类型处理
|
||
|
||
```go
|
||
// CSS 文件：转换内容中的相对路径
|
||
if ext == ".css" {
|
||
transformedContent := transformCssContent(string(content), basePath)
|
||
}
|
||
|
||
// JS 文件：转换动态 import 路径
|
||
if ext == ".js" || ext == ".mjs" {
|
||
transformedContent := transformJsDynamicImports(string(content), basePath)
|
||
}
|
||
```
|
||
|
||
### 5. 前端调用
|
||
|
||
```vue
|
||
<iframe :src="htmlPreviewUrl"></iframe>
|
||
|
||
<script setup>
|
||
const htmlPreviewUrl = computed(() => {
|
||
if (!props.config.currentFileFullPath || !props.config.isHtmlFile) {
|
||
return ''
|
||
}
|
||
const encodedPath = encodeURIComponent(props.config.currentFileFullPath)
|
||
return `http://localhost:18765/localfs/html-preview?path=${encodedPath}`
|
||
})
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 API 文档
|
||
|
||
### HTML 预览接口
|
||
|
||
**路径**：`GET /localfs/html-preview`
|
||
|
||
**参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `path` | string | 是 | HTML 文件绝对路径（URL 编码） |
|
||
| `theme` | string | 否 | 主题（`light` / `dark`），默认 `light` |
|
||
|
||
**示例**：
|
||
|
||
```
|
||
GET /localfs/html-preview?path=E%3A%2Fdocs%2Fpreview.html&theme=dark
|
||
```
|
||
|
||
**返回**：
|
||
|
||
- Content-Type: `text/html; charset=utf-8`
|
||
- 处理后的 HTML 内容（资源路径已转换为 `/localfs/` URL）
|
||
|
||
### 处理流程
|
||
|
||
1. 读取 HTML 文件
|
||
2. 转换静态资源路径（link, script, img, video 等）
|
||
3. 转换内联样式中的 url()
|
||
4. 转换 ES6 import 语句
|
||
5. 注入链接点击拦截脚本
|
||
6. 返回处理后的 HTML
|
||
|
||
---
|
||
|
||
## 📐 代码规范
|
||
|
||
### DRY 原则
|
||
|
||
✅ **正确做法**：统一使用 `resolveHtmlPathToUrl` 处理所有路径
|
||
|
||
```go
|
||
// 路径处理统一在这个函数内部完成
|
||
newUrl := resolveHtmlPathToUrl(baseDir, path)
|
||
```
|
||
|
||
❌ **避免**：在多处重复判断 `/` 开头
|
||
|
||
```go
|
||
// 不要这样做
|
||
if strings.HasPrefix(path, "/") {
|
||
newUrl = resolveHtmlPathToUrl(baseDir, path[1:])
|
||
} else {
|
||
newUrl = resolveHtmlPathToUrl(baseDir, path)
|
||
}
|
||
```
|
||
|
||
### 正则表达式预编译
|
||
|
||
✅ **正确做法**：在 `var` 块中预编译
|
||
|
||
```go
|
||
var (
|
||
htmlLinkTagRegex = regexp.MustCompile(`<link\s+([^>]*)>`)
|
||
)
|
||
```
|
||
|
||
❌ **避免**：在函数内部动态编译
|
||
|
||
```go
|
||
// 不要这样做 - 每次调用都重新编译
|
||
func process(html string) {
|
||
regex := regexp.MustCompile(`<link\s+([^>]*)>`)
|
||
}
|
||
```
|
||
|
||
### 日志规范
|
||
|
||
- 保留关键操作的日志（请求开始/结束）
|
||
- 移除详细的调试日志
|
||
- 使用结构化日志格式
|
||
|
||
```go
|
||
// 保留
|
||
log.Printf("[HtmlPreview] 处理完成: %s (%d -> %d bytes)", filePath, len(content), len(finalContent))
|
||
|
||
// 移除
|
||
// log.Printf("[replaceHtmlTagAttribute] 找到属性 %s=%s", attrName, relativePath)
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试验证
|
||
|
||
### 测试场景
|
||
|
||
1. **基础 HTML 预览**：打开包含 CSS/JS 的 HTML 文件
|
||
2. **资源路径解析**：验证相对路径和绝对路径正确转换
|
||
3. **链接点击**：点击 HTML 内的链接，验证正确打开新文件
|
||
4. **Vite 构建产物**：验证 `/assets/` 路径的 Vue 构建产物正确加载
|
||
|
||
### 验证命令
|
||
|
||
```bash
|
||
# 构建
|
||
go build -o u-desk.exe .
|
||
|
||
# 测试文件
|
||
# E:/wk-lab/lab-admin/dist/index.html
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 收益总结
|
||
|
||
| 指标 | 优化前 | 优化后 |
|
||
|------|--------|--------|
|
||
| 前端代码行数 | ~230 行 | ~10 行 |
|
||
| 闪烁问题 | 明显 | 无 |
|
||
| 路径转换 | 仅前端 | 前后端统一 |
|
||
| 可维护性 | 中 | 高 |
|
||
|
||
---
|
||
|
||
*文档版本: 1.0*
|
||
*创建日期: 2026-02-28*
|
||
*作者: Claude Code*
|