PicaComic 核心 API 全解析：漫画源接入与数据交互指南

PicaComic 核心 API 全解析：漫画源接入与数据交互指南

漫画源架构概览

PicaComic 通过模块化设计实现多漫画源接入，核心抽象类 ComicSource 定义了统一接口。系统内置支持 Picacg、E-Hentai 等主流漫画平台，同时允许通过 JavaScript 脚本扩展自定义源。

核心模块路径：

• 漫画源接口定义：lib/comic_source/comic_source.dart
• 内置漫画源实现：lib/comic_source/built_in/
• 自定义源解析器：lib/comic_source/parser.dart

核心 API 接口详解

ComicSource 类结构

ComicSource 类是所有漫画源的基类，包含元数据、数据加载方法和交互回调：

class ComicSource {
  final String name;          // 源名称
  final String key;           // 唯一标识
  final List<ExplorePageData> explorePages;  // 发现页配置
  final SearchPageData? searchPageData;      // 搜索功能配置
  final LoadComicFunc? loadComicInfo;        // 漫画详情加载方法
  final LoadComicPagesFunc? loadComicPages;  // 章节图片加载方法
  // 更多属性...
}

关键方法包括：

• loadComicInfo(String id): 获取漫画详情
• loadComicPages(String id, String? ep): 获取章节图片列表
• commentsLoader/sendCommentFunc: 评论系统交互

数据模型定义

系统使用标准化数据模型实现跨源统一：

class ComicInfoData with HistoryMixin {
  final String title;          // 标题
  final String? subTitle;      // 副标题
  final String cover;          // 封面图URL
  final Map<String, List<String>> tags;  // 标签集合
  final Map<String, String>? chapters;   // 章节列表
  // 更多属性...
}

内置漫画源实现

以 Picacg 为例，展示内置源的典型实现方式：

final picacg = ComicSource.named(
  name: "picacg",
  key: "picacg",
  filePath: 'built-in',
  favoriteData: FavoriteData(
    key: "picacg",
    title: "Picacg",
    multiFolder: false,
    loadComic: (i, [folder]) => PicacgNetwork().getFavorites(i),
    addOrDelFavorite: (id, folder, isAdding) async {
      var res = await PicacgNetwork().favouriteOrUnfavouriteComic(id);
      return res ? const Res(true) : Res(false, errorMessage: "操作失败");
    },
  ),
  // 更多配置...
);

完整实现参见 lib/comic_source/built_in/picacg.dart

自定义漫画源开发

JavaScript 源开发规范

自定义漫画源通过 JS 脚本实现，需遵循以下结构：

class CustomComicSource extends ComicSource {
  constructor() {
    super();
    this.name = "自定义源";
    this.key = "custom_source";
    this.version = "1.0.0";
  }
  
  // 实现必要方法
  async comic.loadInfo(id) {
    return {
      title: "漫画标题",
      cover: "https://example.com/cover.jpg",
      chapters: {"1": "第一章", "2": "第二章"}
    };
  }
  
  async comic.loadEp(id, ep) {
    return {images: ["https://example.com/img1.jpg", "https://example.com/img2.jpg"]};
  }
}

解析流程与生命周期

自定义源加载流程：

1. 脚本解析：lib/comic_source/parser.dart 验证并加载 JS 源
2. 初始化：调用 init() 方法完成配置
3. 数据交互：通过预定义接口提供漫画数据

解析器核心代码：

Future<ComicSource> parse(String js, String filePath) async {
  // 代码验证与解析
  // 加载关键配置
  // 初始化数据加载函数
}

网络请求与缓存策略

图片加载优化

系统实现多级缓存机制，关键代码：

// 图片加载配置
final getImageLoadingConfig = (String imageKey, String comicId, String epId) {
  return {
    "headers": {"Referer": "https://example.com"},
    "cacheKey": "$comicId-$epId-$imageKey"
  };
};

缓存管理

缓存实现参见 lib/foundation/cache_manager.dart，支持：

• 内存缓存：近期访问图片
• 磁盘缓存：持久化存储
• 自动清理：按 LRU 策略管理缓存

高级功能实现

评论系统集成

评论功能通过以下接口实现：

typedef CommentsLoader = Future<Res<List<Comment>>> Function(
  String id, String? subId, int page, String? replyTo);

typedef SendCommentFunc = Future<Res<bool>> Function(
  String id, String? subId, String content, String? replyTo);

多源数据聚合

系统支持跨源搜索与收藏管理，核心实现：

• lib/comic_source/app_build_in_favorites.dart：统一收藏管理
• lib/pages/pre_search_page.dart：多源搜索入口

开发与调试工具

调试日志

启用详细日志：

log("$e\n$s", "Network", LogLevel.error);

日志查看界面：lib/pages/logs_page.dart

测试与验证

开发自定义源时，可通过以下步骤验证：

1. 将脚本放入 data/comic_source/ 目录
2. 在设置中启用源：lib/pages/settings/comic_source_settings.dart
3. 通过应用内日志监控加载过程

总结与扩展

PicaComic 的模块化架构为漫画源扩展提供了灵活框架，开发者可通过实现 ComicSource 接口快速接入新平台。核心优势包括：

• 统一数据模型简化 UI 适配
• 多缓存策略优化加载性能
• JS 脚本支持动态扩展

项目文档：doc/comic_source.md

后续开发建议：

• 实现更多内置源：支持 Nhentai、Hitomi 等平台
• 增强脚本调试工具：提供 JS 错误捕获与性能分析
• 优化图片加载：支持 WebP 格式与渐进式加载