# 整页图片与背景功能指南

## 功能概览

| 功能 | 标签 | 用途 |
|------|------|------|
| `fullimage` | 整页图片 | 图片占满整页，无边距无文字 |
| `pagebg` | 浅色背景页 | 背景图 + 黑色文字 |
| `pagebgwhite` | 深色背景页 | 背景图 + 白色文字 |

---

## 1. fullimage 整页图片

图片铺满整页，无边距、无页眉页脚。

**Markdown 语法：**
```markdown
::: {#fullimage}
images/cover.jpg
:::
```

**注意：** 文件名含下划线 `_` 会被自动处理（pandoc 转义）。

---

## 2. pagebg / pagebgwhite 背景内容页

背景图作为页面背景，文字内容显示在上面。

**语法：**
```markdown
::: {#pagebgwhite}
bg=images/dark-bg.svg

# 标题
内容（白色字体）
:::
```

| 标签 | 字体颜色 | 适用背景 |
|------|---------|----------|
| `pagebg` | 黑色 | 浅色背景 |
| `pagebgwhite` | 白色 | 深色背景 |

**配置行：** 第一行必须是 `bg=图片路径`，空行后写正文。

---

## 3. 现有 SVG 背景模板

| 文件 | 风格 | 配合标签 |
|------|------|----------|
| `images/test-bg.svg` | 紫蓝深色渐变 | `pagebgwhite` |
| `images/test-bg-light.svg` | 浅紫粉渐变 | `pagebg` |

---

## 4. checkimagesize 图片检查工具

检查图片是否适合全页显示，支持裁切转换。

**用法：**
```bash
# 列出支持的纸型
uv run scripts/checkimagesize.py list

# 检查图片（默认 A4）
uv run scripts/checkimagesize.py check images/photo.jpg

# 指定纸型
uv run scripts/checkimagesize.py check images/photo.jpg --paper a3

# 裁切转换为 A4
uv run scripts/checkimagesize.py check images/photo.jpg --crop
```

**支持的纸型（@ 300dpi）：**
| 纸型 | 尺寸 |
|------|------|
| a4 | 2480 × 3508 |
| a3 | 3508 × 4961 |
| a5 | 1748 × 2480 |
| letter | 2550 × 3300 |
| legal | 2550 × 4200 |
| b5 | 2079 × 2953 |
| 16:9 | 1920 × 1080 |
| 4:3 | 1600 × 1200 |

**`--crop` 转换：**
- 保持比例裁切（cover 模式）
- 输出文件：`原名_fullpage.jpg`
- 不覆盖原文件

---

## 5. 技术实现说明

### content-to-string 辅助函数

pandoc 转换的 fenced div 内容是 `content` 对象而非字符串，需递归提取：

```typst
#let content-to-string(content, sep: "\n") = {
  let result = if content.has("text") {
    content.text
  } else if content.has("children") {
    content.children.map(c => content-to-string(c, sep: sep)).join(sep)
  } else if content.has("body") {
    content-to-string(content.body, sep: sep)
  } else { "" }
  // 处理 pandoc 转义
  result.replace("\\_", "_")
}
```

**参数：**
- `sep: "\n"` — pagebg 用换行符分行解析
- `sep: ""` — fullimage 用空字符串（单行文件名）

### show 规则

```typst
show <fullimage>: it => fullimage(content-to-string(it.body, sep: "").trim())
show <pagebg>: it => pagebg(it.body, content-to-string(it.body))
show <pagebgwhite>: it => pagebg-white(it.body, content-to-string(it.body))
```

---

## 6. 测试文件

| 文件 | 测试内容 |
|------|----------|
| `_working/in/fullimage-test.md` | 整页图片各种尺寸 |
| `_working/in/svg-bg-test.md` | SVG 背景页（深色/浅色） |
| `_working/in/pagebg-test.md` | pagebg 综合测试 |
