# 多封面模式调研

---

## 1. 当前封面实现分析

### 1.1 核心文件: `nb-cover-lib.typ`

当前封面系统由 [nb-cover-lib.typ](./template/nb-cover-lib.typ) 提供，包含两个主要函数：

| 函数 | 用途 | 特点 |
|------|------|------|
| `coverpage()` | 封面页 | 红色侧边栏、英雄图片、引用区、标题、Logo |
| `backcoverpage()` | 封底页 | 灰色背景、居中 Logo、出版信息 |

---

**封面页布局结构：**
```
┌─────────────────────┬────────┐
│ 标题 (24pt 蓝色)    │ Edition│
├─────────────────────┤ (红色  │
│ Hero Image (14cm)   │ 侧边栏)│
│ + Caption           │        │
├─────────────────────┤        │
│ Quote (引用区块)    │        │
├─────────────────────┤        │
│ Logo    │ 出版信息  │        │
└─────────────────────┴────────┘
```


### 1.2 使用该封面库的模板

1. **[nb.typ](./template/nb.typ)** - Newsletter 模板
2. **[youth.typ](./template/youth.typ)** - 少年商学院模板（带水印和二维码）

两者都通过 `disables` 中的 `cover` 控制是否显示封面。

---

### 1.3 其他封面风格 (参考)

| 模板 | 封面风格 | 特点 |
|------|----------|------|
| [gaozhi-book.typ](./template/back/gaozhi-book.typ) | 全出血图片封面 | 图片填满整页，标题叠加于图片上方（白色字体） |
| [letter-cover.typ](./template/back/letter-cover.typ) | 无封面 | 法律信函风格，无专门封面页 |

---

## 2. 多封面模式可行性分析

### 2.1 设计方案：参数化封面类型

**建议添加 `cover-style` 参数来选择封面模式：**

```typst
#let coverpage(
  cover-style: "newsletter",  // 新增参数
  title: none,
  author: none,
  // ... 其他参数
) = {
  if cover-style == "newsletter" {
    // 当前的红色侧边栏风格
  } else if cover-style == "fullbleed" {
    // 全出血图片风格
  } else if cover-style == "minimal" {
    // 极简风格
  } else if cover-style == "academic" {
    // 学术风格
  }
}
```

---

### 2.2 可实现的封面模式

#### Mode 1: Newsletter (当前默认)
- 红色侧边栏
- Hero 图片 + Caption
- 引用区块
- 适合: Newsletter、杂志

---

#### Mode 2: Fullbleed (全出血)
- 图片填满整页
- 标题叠加于图片上
- 适合: 封面图视觉冲击力强的场景

```typst
#let coverpage_fullbleed(
  title: none,
  cover-image: none,
  text-color: white,
) = {
  set page(margin: 0pt)
  image(cover-image, width: 100%, height: 100%, fit: "cover")
  place(
    center + top,
    dy: 200pt,
    text(size: 6em, weight: "bold", fill: text-color, title)
  )
}
```

---

#### Mode 3: Minimal (极简)
- 纯文字居中
- 无图片，干净简洁
- 适合: 正式文档、报告

```typst
#let coverpage_minimal(
  title: none,
  author: none,
  date: none,
) = {
  set page(fill: white)
  align(center + horizon)[
    #text(size: 32pt, weight: "bold", title)
    #v(2em)
    #text(size: 14pt, author)
    #v(1em)
    #text(size: 12pt, date)
  ]
}
```

---

#### Mode 4: Academic (学术)
- 居中标题
- 作者、机构、日期
- 可选徽标
- 适合: 论文、学术报告

#### Mode 5: Book (书籍)
- 左对齐或居中标题
- 脊背设计考虑
- 适合: 电子书、长篇文档

---

## 3. 实现方案

---

### 方案 A: 单文件扩展 (推荐)

在 `nb-cover-lib.typ` 中添加多个封面函数：

```
nb-cover-lib.typ
├── coverpage()          # 默认 newsletter 风格
├── coverpage_fullbleed() 
├── coverpage_minimal()
├── coverpage_academic()
├── coverpage_book()
└── backcoverpage()      # 现有封底
```

**优点：** 修改集中，易于维护

---

### 方案 B: 拆分为独立模块

```
template/
├── covers/
│   ├── cover-newsletter.typ
│   ├── cover-fullbleed.typ
│   ├── cover-minimal.typ
│   └── cover-academic.typ
├── nb-cover-lib.typ     # 保持兼容，导入 covers/
└── ...
```

**优点：** 模块化，易于扩展新风格

---

### 方案 C: 配置驱动

创建配置文件定义封面参数，通过传入参数动态生成封面：

```typst
#let coverpage(
  style: (
    layout: "sidebar",      // sidebar, centered, fullbleed
    accent-color: red,
    show-hero: true,
    show-quote: true,
    title-size: 24pt,
    title-position: "left", // left, center
  ),
  ...
) = { ... }
```

**优点：** 高度灵活，用户可微调

---

## 4. CLI/API 集成考虑

### 4.1 Markdown Frontmatter 支持

```yaml
---
title: "文档标题"
cover-style: "fullbleed"   # 新增字段
cover-image: "./images/cover.jpg"
---
```

### 4.2 CLI 参数扩展

```bash
md2pdf sample.md --cover-style=fullbleed
```

---

### 4.3 需要修改的文件

| 文件 | 修改内容 |
|------|----------|
| `nb-cover-lib.typ` | 添加多种封面函数 |
| `nb.typ` / `youth.typ` | 添加 `cover-style` 参数传递 |
| `helper_typst.py` | 添加 `cover_style` pandoc 参数 |
| `cli.py` | 添加 `--cover-style` 选项 |
| `core.py` | API 支持 `cover_style` |

---

## 5. 推荐实施路径

### Phase 1: 基础功能 (优先)
1. 在 `nb-cover-lib.typ` 添加 `coverpage_fullbleed()` 函数
2. 在 `nb.typ` 中添加 `cover-style` 参数
3. 测试新封面风格

### Phase 2: CLI 集成
1. 扩展 `helper_typst.py` 支持 `cover_style`
2. 添加 CLI `--cover-style` 选项
3. 更新文档

### Phase 3: 更多风格
1. 添加 minimal、academic、book 风格
2. 考虑配置驱动方案

---

## 6. 总结

| 问题 | 回答 |
|------|------|
| **能否实现多封面模式？** | ✅ 完全可行 |
| **推荐方案** | 方案 A (单文件扩展) 或 方案 B (模块拆分) |
| **最小改动** | 添加 `cover-style` 参数 + 新封面函数 |
| **复杂度** | 中等（主要是 Typst 布局代码） |


> 建议从 **Fullbleed** 和 **Minimal** 两种风格开始，它们实现简单且覆盖不同使用场景。

---

## 7. Typst 官方 API 核查

基于 [Typst 官方文档](https://typst.app/docs/reference/) 验证方案可行性：

---

### 7.1 核心函数验证

| 函数 | 关键参数 | 用途 | 验证状态 |
|------|----------|------|----------|
| `page()` | `fill`, `background`, `margin`, `width`, `height` | 设置页面属性 | ✅ 官方支持 |
| `place()` | `alignment`, `dx`, `dy`, `scope` | 绝对定位元素 | ✅ 官方支持 |
| `image()` | `width`, `height`, `fit` | 显示图片 | ✅ 官方支持 |

---

### 7.2 关键语法验证

#### 全出血封面关键语法
```typst
// ✅ 零边距页面设置
set page(margin: 0pt)

// ✅ 图片填充模式
image("cover.jpg", width: 100%, height: 100%, fit: "cover")

// ✅ 绝对定位标题叠加
place(
  center + top,
  dy: 200pt,
  text(size: 6em, weight: "bold", fill: white, "标题")
)
```

#### image fit 参数值
| 值 | 说明 | 来源 |
|----|------|------|
| `"cover"` | 填满区域，按比例裁剪（默认） | 官方文档 |
| `"contain"` | 完整显示，可能有留白 | 官方文档 |
| `"stretch"` | 拉伸填满，不保持比例 | 官方文档 |

---

### 7.3 One-off Page 模式

官方文档明确支持**单页覆盖**模式，完美适合封面实现：

```typst
// 临时覆盖页面设置，仅对封面有效
#page(
  margin: 0pt,
  background: image("cover.jpg", width: 100%, height: 100%, fit: "cover")
)[
  #place(center + horizon, text(size: 48pt, fill: white, weight: "bold", "标题"))
]
// 后续内容自动恢复原页面设置
```

> [!IMPORTANT]
> 使用 `page()` 函数调用（而非 `set page()`）可以创建独立封面页，不影响后续页面格式。这是官方推荐的封面实现方式。

---

### 7.4 修正后的 Fullbleed 封面实现

```typst
#let coverpage_fullbleed(
  title: none,
  subtitle: none,
  cover-image: none,
  text-color: white,
) = {
  page(
    margin: 0pt,
    background: image(cover-image, width: 100%, height: 100%, fit: "cover")
  )[
    #place(
      center + top,
      dy: 40%,
      {
        text(size: 48pt, weight: "bold", fill: text-color, title)
        v(1em)
        if subtitle != none {
          text(size: 24pt, fill: text-color, subtitle)
        }
      }
    )
  ]
}
```

---

### 7.5 结论

| 检查项 | 结果 |
|--------|------|
| 方案语法正确性 | ✅ 全部通过 |
| 关键 API 可用性 | ✅ 全部可用 |
| 官方推荐实践 | ✅ 符合 one-off page 模式 |

**验证来源：**
- [Page Function](https://typst.app/docs/reference/layout/page/)
- [Place Function](https://typst.app/docs/reference/layout/place/)
- [Image Function](https://typst.app/docs/reference/visualize/image/)
- [Page Setup Guide](https://typst.app/docs/guides/page-setup/)
