# 本地漫画导入

英文版本：[import_comic.en.md](import_comic.en.md)

## 简介

VeneraNext 支持从本地文件导入漫画，但本地文件需要符合特定目录或压缩包格式。

## 恢复本地下载

如果迁移应用时保留了本地下载文件夹，但丢失了 `local.db`，可以通过扫描当前本地路径恢复本地数据库。

- 打开 `本地` -> `导入` -> `恢复本地下载`。
- 应用会扫描当前本地存储路径并重建条目。
- 该操作不会复制文件，也不会添加收藏。
- 同名标题或目录会被视为重复并跳过。

执行前请确认设置中的本地存储路径指向包含已下载漫画的目录。

## 漫画目录

目录只有符合以下两种结构之一时，才会被视为漫画目录。

**无章节目录**

```text
comic_directory
├── cover.[ext]
├── img1.[ext]
├── img2.[ext]
├── img3.[ext]
├── ...
```

**包含章节目录**

```text
comic_directory
├── cover.[ext]
├── chapter1
│   ├── img1.[ext]
│   ├── img2.[ext]
│   ├── img3.[ext]
│   ├── ...
├── chapter2
│   ├── img1.[ext]
│   ├── img2.[ext]
│   ├── img3.[ext]
│   ├── ...
├── ...
```

图片文件名可以任意命名，但扩展名必须是有效图片格式。

页面顺序由文件名决定。应用会按文件名排序后按顺序显示。

封面图是可选的。如果目录中存在 `cover.[ext]`，它会被识别为封面；否则第一张图片会被用作封面。

漫画标题使用漫画目录名。章节标题使用章节目录名。

## 压缩包

VeneraNext 支持从压缩包导入漫画。

压缩包适合作为导入、导出、归档、迁移和分发格式，应符合 [Comic Book Archive](https://en.wikipedia.org/wiki/Comic_book_archive_file) 格式。

当前支持以下压缩包格式：

- `.cbz`
- `.cb7`
- `.zip`
- `.7z`

压缩包可以直接包含图片，也可以包含一个顶层目录；如果顶层目录下是多个章节目录，应用会按章节目录导入。

```text
猫之眼[北条司].cbz
└── 猫之眼[北条司]
    ├── cover.jpg
    ├── 第01卷
    │   ├── 001.jpg
    │   └── 002.jpg
    └── 第02卷
        ├── 001.jpg
        └── 002.jpg
```

如果根目录没有 `cover.[ext]`，应用会使用第一章的第一张图片作为封面。

## WebDAV 在线漫画库

WebDAV 漫画库是在线阅读渠道，和本地导入导出、WebDAV CBZ 归档是不同能力。

在线阅读只读取远端目录图片，应用会按需列目录和加载图片，不会把远端 CBZ/ZIP/7Z 当作在线预览内容。可以直接使用普通图片目录，也可以把 VeneraNext 导出的单本 CBZ 解压后放到 WebDAV，以保留标题、作者、标签和章节信息。

### 普通目录模式

推荐结构：

```text
/venera_comics/
└── 猫之眼[北条司]
    ├── cover.jpg
    ├── 第01卷
    │   ├── 001.jpg
    │   └── 002.jpg
    └── 第02卷
        ├── 001.jpg
        └── 002.jpg
```

普通目录模式的规则：

- 漫画标题取漫画文件夹名。
- 子目录作为章节；如果根目录直接包含图片，则根目录图片可作为单章节漫画阅读。
- 页面和章节按文件名排序，推荐使用补零编号，例如 `0001.jpg`、`0002.jpg`。
- 封面优先使用根目录下文件名为 `cover` 的图片；支持 `jpg`、`jpeg`、`png`、`webp`、`gif`、`jpe`。没有独立封面时，依次使用根目录首图、首个可读章节的 `cover.*` 或首图。
- 不要求 `metadata.json` 或 `ComicInfo.xml`。

### CBZ 解压增强模式

VeneraNext 导出的单本 CBZ 解压后通常是扁平图片目录：

```text
/venera_comics/
└── 猫之眼
    ├── metadata.json
    ├── ComicInfo.xml
    ├── cover.jpg
    ├── 0001.jpg
    ├── 0002.jpg
    ├── 0003.jpg
    └── 0004.jpg
```

`metadata.json` 模板：

```json
{
  "title": "猫之眼",
  "author": "北条司",
  "tags": ["动作", "漫画"],
  "chapters": [
    {"title": "第01卷", "start": 1, "end": 2},
    {"title": "第02卷", "start": 3, "end": 4}
  ]
}
```

字段规则：

| 字段 | 类型 | 说明 |
|---|---|---|
| `title` | 字符串 | 漫画标题；空字符串会回退为文件夹名 |
| `author` | 字符串 | 作者，可为空字符串 |
| `tags` | 字符串数组 | 漫画标签，可为空数组 |
| `chapters` | 数组或 `null` | 章节范围；为 `null` 或空数组时，根目录图片作为单章节 |
| `chapters[].title` | 字符串 | 章节显示名称，不可为空 |
| `chapters[].start` | 整数 | 章节起始页，从 1 开始，包含该页 |
| `chapters[].end` | 整数 | 章节结束页，包含该页 |

章节范围必须按顺序排列、不得重叠、不得反向，并且不能超过根目录实际页面数。`cover.*` 不计入页面编号。元数据允许存在额外字段，以便后续扩展；当前不会从元数据读取远端 URL、脚本或本地绝对路径。

`metadata.json` 使用 UTF-8 编码，文件名匹配不区分大小写。`ComicInfo.xml` 会随 CBZ 导出保留，用于其他漫画阅读器兼容；VeneraNext WebDAV 漫画库当前以 `metadata.json` 为增强信息来源。

如果元数据文件缺失、无法读取、JSON 损坏、字段类型错误或章节范围不合法，应用会记录警告并回退普通目录模式。漫画仍以文件夹名显示，目录中的图片和章节子目录仍可阅读。

这里的 `metadata.json` 是单本 CBZ 的元数据格式，不是 `.venera-comics` 批量导出包中的漫画列表格式，两者不可混用。

### 压缩包与在线阅读

CBZ/ZIP/7Z 仍然可以通过 WebDAV 归档功能上传、下载和恢复，但它们属于备份与分发格式，不用于在线阅读。需要在线阅读时，请先在 WebDAV 服务端解压；应用只按需读取解压目录中的图片，不会下载整个压缩包。