xfy
987a0d9671
文章图片 blur-up 渐进加载设计文档,经 brainstorming 流程产出: - 低分辨率占位图(?w=20,SSR 内嵌)+ 高清缩略图双层叠加 - 服务端读图片 header 拿真实尺寸生成 aspect-ratio(零 CLS) - dimensions 用 moka sync cache 缓存(TTL 可配置,默认 24h) - 三处图片位置统一(卡片封面/详情封面/正文图) - Markdown 渲染器把 img 转双层 wrapper,post-content.js 懒加载高清 - sanitizer 扩展放行 data-src/class/style(仅文章,评论不动) - 外链图不处理,JS 禁用时渐进降级到模糊占位图 webp 尺寸读取风险已排除(zenwebp info() 只读 header)。 验收标准 12 条。不含实现,仅设计。
314 lines
14 KiB
Markdown
314 lines
14 KiB
Markdown
# 文章图片 Blur-up 渐进加载设计
|
||
|
||
## 背景与目标
|
||
|
||
文章页面的缩略图（卡片封面 `?thumb=400x300`、详情封面 `?w=1200`、正文图 `?w=800`）在加载过程中**没有任何占位**：`<img>` 裸标签无 width/height/aspect-ratio，加载时区域高度为 0，加载完撑开——导致 CLS（布局跳动）明显，尤其在列表页和长文章里。
|
||
|
||
本设计的目标：
|
||
- 加载前先显示**低分辨率模糊占位图**（`?w=20`），消除空白与跳动
|
||
- 加载完高清缩略图后，**平滑过渡**到清晰（opacity 淡入）
|
||
- 服务端 SSR 内嵌占位图（渐进增强，JS 禁用也能看到占位）
|
||
- 三处图片位置（卡片封面、详情封面、正文图）统一应用
|
||
|
||
## 关键决策
|
||
|
||
| 决策点 | 选择 |
|
||
|--------|------|
|
||
| 占位图来源 | SSR 内嵌（HTML 里 img src 就是占位图 URL，JS 替换高清） |
|
||
| 过渡实现 | 双层叠加 + opacity 淡入（底层占位图常驻，上层高清图淡入覆盖） |
|
||
| 作用范围 | 三处都加（卡片封面、详情封面、正文图） |
|
||
| 占位图尺寸 | 统一 `?w=20` |
|
||
| DOM 生成方式 | 方案 A：SSR 渲染双层结构 + JS 接管高清加载 |
|
||
| aspect-ratio 尺寸来源 | 方案 B2：渲染时实时读图片 header + moka 缓存（零迁移） |
|
||
| 外链图 | 不处理（保持原生 img，无法生成占位图） |
|
||
| dimensions 缓存 TTL | 24h，可通过 `IMAGE_DIMENSIONS_CACHE_TTL_SECS` 环境变量配置 |
|
||
|
||
## 技术约束（探索结论）
|
||
|
||
- **服务端图片能力现成**：`/uploads/{path}` 支持 `?w=`/`?thumb=`，已有内存+磁盘两级缓存（`src/api/image.rs`）。`?w=20` 产出 <1KB 的极小图。
|
||
- **sanitizer 约束**：当前 `clean_post_html` 对 img 只放行 `src/alt/width/height/align`，对 span 放行 `class`。双层结构需要额外放行 `data-src`/`class`/`style`（img）和 `style`（span）。评论配置不动。
|
||
- **现有缓存是异步的**：`src/cache.rs` 用 `moka::future::Cache`（`.get().await`），但 `render_markdown_enhanced` 是同步函数。dimensions 缓存需要用 `moka::sync::Cache`（同步版本）。
|
||
- **webp 尺寸读取可行**：`zenwebp::WebPDecoder::build(data)` + `.info()` 只解析 WebP header（RIFF chunk）就能拿到 width/height，**不需要全量解码像素**（见 `src/webp.rs:143-145` 现有代码在 decode 前就读了 info）。开销极小。GIF/PNG/JPEG 走 `image::ImageReader::into_dimensions()`（只读 header）。
|
||
- **上传后磁盘格式**：非 gif/webp 统一转 webp，gif 保持 gif，webp 保持 webp。所以 dimensions 读取要支持 webp + gif/png/jpeg。
|
||
|
||
## 详细设计
|
||
|
||
### 架构总览
|
||
|
||
```
|
||
SSR 渲染文章/封面时
|
||
↓
|
||
对每张 /uploads/ 图片:
|
||
├─ get_image_dimensions(path) → (w, h) [sync moka cache + 读 header]
|
||
└─ 产出双层 DOM:
|
||
<span class="blur-img" style="--ar: W/H;">
|
||
<img class="blur-img-placeholder" src="...?w=20"> ← SSR 内嵌,立即加载
|
||
<img class="blur-img-full" data-src="...?w=800"> ← JS 懒加载
|
||
</span>
|
||
|
||
前端 JS (post-content.js / image-viewer 初始化)
|
||
├─ IntersectionObserver 监听 .blur-img 进入视口
|
||
├─ 把 .blur-img-full 的 data-src 赋给 src → 触发高清图加载
|
||
└─ 高清图 onload → 加 .is-loaded class → CSS opacity 0→1 淡入
|
||
```
|
||
|
||
### 1. Dimensions 缓存与读取（新增）
|
||
|
||
**`src/api/image.rs` 新增**（`#[cfg(feature = "server")]`）：
|
||
|
||
```rust
|
||
use moka::sync::Cache;
|
||
use std::sync::LazyLock;
|
||
use std::time::Duration;
|
||
|
||
static IMAGE_DIMENSIONS_CACHE: LazyLock<Cache<String, (u32, u32)>> = LazyLock::new(|| {
|
||
let ttl = std::env::var("IMAGE_DIMENSIONS_CACHE_TTL_SECS")
|
||
.ok()
|
||
.and_then(|s| s.parse::<u64>().ok())
|
||
.map(Duration::from_secs)
|
||
.unwrap_or(Duration::from_secs(86400)); // 默认 24h
|
||
Cache::builder().time_to_live(ttl).build()
|
||
});
|
||
|
||
/// 读取图片真实尺寸（只读 header，不解码像素）。
|
||
/// 路径如 "2026/06/22/xxx.webp"（不含 /uploads/ 前缀）。
|
||
/// 失败返回 None（渲染时回退到不设 aspect-ratio）。
|
||
pub fn get_image_dimensions(rel_path: &str) -> Option<(u32, u32)> {
|
||
if let Some(dims) = IMAGE_DIMENSIONS_CACHE.get(rel_path) {
|
||
return Some(dims);
|
||
}
|
||
let full_path = std::path::Path::new("uploads").join(rel_path);
|
||
let data = std::fs::read(&full_path).ok()?;
|
||
let dims = read_dimensions_from_bytes(&data, rel_path)?;
|
||
IMAGE_DIMENSIONS_CACHE.insert(rel_path.to_string(), dims);
|
||
Some(dims)
|
||
}
|
||
|
||
/// 按扩展名分发：webp 走 zenwebp header，其他走 image crate。
|
||
fn read_dimensions_from_bytes(data: &[u8], path: &str) -> Option<(u32, u32)> {
|
||
let ext = std::path::Path::new(path).extension()?.to_str()?.to_lowercase();
|
||
match ext.as_str() {
|
||
"webp" => {
|
||
let decoder = zenwebp::WebPDecoder::build(data).ok()?;
|
||
let info = decoder.info();
|
||
Some((info.width, info.height))
|
||
}
|
||
"gif" | "png" | "jpg" | "jpeg" => {
|
||
let reader = image::ImageReader::new(std::io::Cursor::new(data))
|
||
.with_guessed_format().ok()?;
|
||
reader.into_dimensions().ok()
|
||
}
|
||
_ => None,
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**：这是同步函数，在 server function 的异步上下文里同步读文件头。文件头很小（几十到几百字节），开销可接受；moka cache 命中时不读盘。`std::fs::read` 读整个文件——优化点：可改为只读前 N 字节（webp/jpeg/png/gif 的 header 都在前几百字节内），但首版用 `std::fs::read` 保持简单，配合 cache 降低频率。
|
||
|
||
### 2. 双层 DOM 结构
|
||
|
||
```html
|
||
<span class="blur-img" style="--ar: 16/9;">
|
||
<img class="blur-img-placeholder" src="/uploads/x.webp?w=20" alt="...">
|
||
<img class="blur-img-full" data-src="/uploads/x.webp?w=800" alt="...">
|
||
</span>
|
||
```
|
||
|
||
- **`span.blur-img`**：相对定位容器，`aspect-ratio: var(--ar)` 预留空间（零 CLS），`overflow: hidden` 裁剪模糊边缘
|
||
- **`img.blur-img-placeholder`**：SSR 内嵌的 `?w=20` 占位图，绝对定位填满容器，CSS 模糊放大
|
||
- **`img.blur-img-full`**：`data-src` 存高清 URL，初始无 src（不立即加载），JS 接管；绝对定位，初始 `opacity: 0`，加载完 `.is-loaded` → `opacity: 1`
|
||
|
||
`--ar` 由服务端用 `get_image_dimensions` 拿到的真实宽高生成（如 `16/9`）。dimensions 读取失败时不设 `--ar`，退化为无 aspect-ratio（轻微 CLS，但不阻塞渲染）。
|
||
|
||
### 3. Markdown 渲染器改造（`render_markdown_enhanced`）
|
||
|
||
正文图转换发生在 Markdown→HTML 阶段。当前用 `pulldown_cmark::html::push_html` 产出 `<img src="..." alt="...">`。
|
||
|
||
**改造**：在 `push_html` 产出 HTML 后、`clean_html` 之前，对字符串里的 `<img>` 做后处理：
|
||
|
||
```rust
|
||
fn wrap_images_with_blur(html: &str) -> String {
|
||
// 用正则/简单解析找到 <img src="/uploads/..." ...> 标签
|
||
// 对每个匹配的 img:
|
||
// 1. 提取 src（如 /uploads/2026/06/22/x.webp）
|
||
// 2. 从 src 解析出 rel_path（去掉 /uploads/ 前缀和 query）
|
||
// 3. get_image_dimensions(rel_path) → (w,h)，算 --ar
|
||
// 4. 生成双层结构替换原 img
|
||
// 非 /uploads/ 的外链图不处理（保持原样）
|
||
}
|
||
```
|
||
|
||
**正则选择**：用 `regex` crate（已是 server feature 的 optional 依赖）匹配 `<img\s+[^>]*src="(/uploads/[^"?]+)[^"]*"[^>]*>`。注意 HTML 用正则有边界情况，但 img 标签由 pulldown-cmark 生成，格式可控（属性顺序固定：src 在前，alt 在后）。
|
||
|
||
### 4. ImageViewer 改造（卡片封面 / 详情封面）
|
||
|
||
`ImageViewer` 当前渲染单层 img + 灯箱。改为渲染双层结构：
|
||
|
||
```rust
|
||
ImageViewer {
|
||
src: cover.clone(),
|
||
thumb_params: "?w=1200", // 高清尺寸 → data-src
|
||
placeholder_params: "?w=20", // 占位图尺寸
|
||
alt: "封面图片",
|
||
}
|
||
```
|
||
|
||
ImageViewer 内部：
|
||
- **dimensions 获取**：组件内部调用 `get_image_dimensions`（`#[cfg(feature = "server")]`）。SSR 渲染时组件树在服务端执行，server-only 函数可用；dimensions 有 moka 缓存，命中时是内存查询，miss 时读小文件头。调用方（`post_card.rs`/`post_cover.rs`）无需改动 dimensions 相关逻辑。WASM 端无法调此函数，但图片的 `--ar` 在 SSR 阶段已渲染进 HTML，前端无需再算。
|
||
- 底层 placeholder：`src = {原图}{placeholder_params}`
|
||
- 上层 full：`data-src = {原图}{thumb_params}`
|
||
- `--ar` 由 dimensions 计算，SSR 时写入 `style`
|
||
- 灯箱逻辑不变（点击用原图 src 放大）
|
||
|
||
`get_image_dimensions` 在组件里调用属于 SSR 渲染时的同步读盘。首版接受这个阻塞（小文件 + cache）；如 SSR 性能成问题，后续可改为 server function 预算 + 模型字段传递。
|
||
|
||
### 5. post-content.js 改造
|
||
|
||
当前职责：把 img.src 改成 `?w=800`、加灯箱。
|
||
|
||
**新职责**：
|
||
- **不再改 src**（渲染器已产出双层结构，placeholder src 已是 `?w=20`）
|
||
- **加载高清图**：用 `IntersectionObserver` 监听 `.blur-img` 进入视口，把 `.blur-img-full` 的 `data-src` 赋给 `src`
|
||
- **触发淡入**：高清 img 的 `onload` 加 `.is-loaded` class，CSS 控制 opacity 过渡
|
||
- **灯箱**：保留现有点击放大。灯箱用 `.blur-img-full` 的 `data-src`（高清图 URL）作为放大图源——灯箱是看大图，应用高清版本而非 20px 占位图。
|
||
|
||
```javascript
|
||
function initBlurUp(root) {
|
||
var containers = root.querySelectorAll('.blur-img');
|
||
if (!('IntersectionObserver' in window)) {
|
||
// 不支持 IO 的浏览器：直接加载所有
|
||
containers.forEach(loadFull);
|
||
return;
|
||
}
|
||
var io = new IntersectionObserver(function(entries) {
|
||
entries.forEach(function(entry) {
|
||
if (entry.isIntersecting) {
|
||
loadFull(entry.target);
|
||
io.unobserve(entry.target);
|
||
}
|
||
});
|
||
}, { rootMargin: '200px' });
|
||
containers.forEach(function(c) { io.observe(c); });
|
||
}
|
||
|
||
function loadFull(container) {
|
||
var full = container.querySelector('.blur-img-full');
|
||
if (!full || !full.dataset.src) return;
|
||
full.onload = function() { full.classList.add('is-loaded'); };
|
||
full.src = full.dataset.src;
|
||
}
|
||
```
|
||
|
||
### 6. CSS
|
||
|
||
新增到全局样式（`input.css` 或对应样式入口）：
|
||
|
||
```css
|
||
.blur-img {
|
||
position: relative;
|
||
display: block;
|
||
overflow: hidden;
|
||
aspect-ratio: var(--ar);
|
||
background: var(--color-paper-code-bg, #f5f5f5); /* 加载中灰底 */
|
||
}
|
||
.blur-img-placeholder {
|
||
position: absolute;
|
||
inset: 0;
|
||
width: 100%;
|
||
height: 100%;
|
||
object-fit: cover;
|
||
filter: blur(20px) saturate(1.2);
|
||
transform: scale(1.1); /* 放大遮住 blur 边缘 */
|
||
}
|
||
.blur-img-full {
|
||
position: absolute;
|
||
inset: 0;
|
||
width: 100%;
|
||
height: 100%;
|
||
object-fit: cover;
|
||
opacity: 0;
|
||
transition: opacity 0.4s ease;
|
||
z-index: 1;
|
||
}
|
||
.blur-img-full.is-loaded {
|
||
opacity: 1;
|
||
}
|
||
```
|
||
|
||
暗色模式：`.blur-img` 的 background 用暗色灰底。
|
||
|
||
### 7. sanitizer 配置扩展
|
||
|
||
`clean_post_html`（文章专用）扩展放行属性：
|
||
- img：额外放行 `data-src`、`class`、`style`
|
||
- span：额外放行 `style`（用于 `--ar`）
|
||
|
||
评论配置（`clean_comment_html`）**不动**（评论无 img）。
|
||
|
||
## 实现边界与清单
|
||
|
||
### 服务端（`#[cfg(feature = "server")]`）
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `src/api/image.rs` | 新增 `IMAGE_DIMENSIONS_CACHE`（moka sync）+ `get_image_dimensions` + `read_dimensions_from_bytes` |
|
||
| `src/api/markdown.rs` | `render_markdown_enhanced` 增加 `wrap_images_with_blur` 后处理（在 clean_html 前） |
|
||
| `src/api/sanitizer.rs` | `clean_post_html` 扩展 img 放行 `data-src/class/style`、span 放行 `style` |
|
||
|
||
### 前端（Rust 组件）
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `src/components/image_viewer.rs` | 渲染双层结构（placeholder + full），接收 dimensions/aspect-ratio |
|
||
| `src/components/post_card.rs` | 调 ImageViewer 时传入 dimensions（SSR 算好） |
|
||
| `src/components/post/post_cover.rs` | 同上 |
|
||
|
||
### 前端（JS）
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `public/js/post-content.js` | 删除改 src 逻辑；新增 IntersectionObserver 懒加载 + onload 淡入；灯箱改用 data-src |
|
||
|
||
### 样式
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `input.css`（或全局样式入口） | 新增 `.blur-img*` 样式（含暗色模式） |
|
||
|
||
### 配置
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `.env.example` | 新增 `IMAGE_DIMENSIONS_CACHE_TTL_SECS=86400` |
|
||
|
||
### 不做的事
|
||
|
||
- 不改评论图片（评论无 img）
|
||
- 不处理外链图（非 `/uploads/` 的图保持原生 img）
|
||
- 不给上传流程加尺寸持久化（B2 方案零迁移，实时读 + 缓存）
|
||
- 不做 LQIP 之外的图片优化（avif 转码、响应式 srcset 等）
|
||
- 不改图片服务端点（`/uploads/{path}` 的 `?w=` 能力现成）
|
||
|
||
## 实现风险
|
||
|
||
1. **正则解析 img 标签**：`wrap_images_with_blur` 用正则匹配 img。pulldown-cmark 产出的 img 格式可控（src 在前、alt 在后），但需写测试覆盖各种 src 格式（带/不带 query、外链、相对路径）。
|
||
|
||
2. **`std::fs::read` 读全文件**：首版 `get_image_dimensions` 读整个文件再解析 header。对大图（几 MB）有内存/IO 开销。优化：改为只读前 N 字节（webp/jpeg/png/gif header 都在前 100 字节内）。首版保持简单，配合 cache 降低频率，后续可优化。
|
||
|
||
3. **SSR 阶段 ImageViewer 拿 dimensions**：ImageViewer 是通用组件，dimensions 是 server-only。需在 SSR 上层（post_card/post_cover）算好传入，避免组件内部调用 server-only 函数。
|
||
|
||
## 验收标准
|
||
|
||
- [ ] 文章正文图片加载时先显示模糊的 `?w=20` 占位图，无布局跳动（aspect-ratio 预留空间）
|
||
- [ ] 高清缩略图加载完后，opacity 平滑淡入覆盖占位图（0.4s 过渡）
|
||
- [ ] 视口外的高清图不加载（IntersectionObserver 懒加载）
|
||
- [ ] 卡片封面、详情封面同样有 blur-up 效果
|
||
- [ ] 外链图（非 /uploads/）保持原生 img，无 blur-up
|
||
- [ ] JS 禁用时，正文图显示 `?w=20` 模糊占位图（渐进增强，可读但模糊）
|
||
- [ ] dimensions 缓存命中时不读盘（二次访问快）
|
||
- [ ] webp/gif/png/jpeg 图片的尺寸都能正确读取
|
||
- [ ] `.env.example` 含 `IMAGE_DIMENSIONS_CACHE_TTL_SECS=86400`
|
||
- [ ] sanitizer 不误删双层结构的 `data-src`/`class`/`style` 属性
|
||
- [ ] 评论图片不受影响（评论无 img，配置不动）
|
||
- [ ] 点击图片放大（灯箱）功能仍正常工作
|