📋 短剧信息与数据接口

pangrowth_content 插件对 DJX SDK 的短剧数据能力进行了完整封装，涵盖短剧列表、个性化推荐、分类检索、收藏/点赞、剧集解锁状态等常用场景。本章节示例均基于 Flutter API，Android 与 iOS 已实现同名通道。

✨ 可用能力总览

短剧列表：分页列表、分类筛选、按 ID 批量获取
推荐与搜索：个性化推荐、关键词搜索
用户留存：观看历史、收藏列表、清理历史
互动行为：收藏/取消收藏、点赞/取消点赞
剧集控制：查询剧集锁定状态、校验解锁参数

🚀 API 详解

1. 获取短剧列表

final dramas = await PangrowthContent.getDramaList(
  page: 1,
  count: 20,
  order: true, // true 正序，false 倒序
);

2. 个性化推荐列表

final recommended = await PangrowthContent.getRecommendedDramaList(
  page: 1,
  count: 10,
);

3. 按分类获取短剧

final dramasByCategory = await PangrowthContent.getDramaListByCategory(
  '甜宠',
  page: 1,
  count: 20,
  ascending: false,
);

4. 按 ID 批量获取

final dramasByIds = await PangrowthContent.getDramaListByIds(<int>[
  1008611,
  1008612,
]);

5. 获取短剧分类列表

final categories = await PangrowthContent.getCategoryList();

6. 搜索短剧

final searchResults = await PangrowthContent.searchDrama(
  '都市',
  isFuzzy: true,
  page: 1,
  count: 15,
);

7. 观看历史

final history = await PangrowthContent.getDramaHistory(page: 1, count: 30);

清理历史：

await PangrowthContent.clearDramaHistory();

8. 收藏与收藏列表

// 收藏/取消收藏（episodeIndex 可选，Android SDK 需要传入）
await PangrowthContent.setDramaFavorite(1008611, favorite: true, episodeIndex: 0);

// 收藏列表（返回 DramaPageResult）
final favorPage = await PangrowthContent.getDramaFavorList(page: 1, count: 20);
print('收藏总数: ${favorPage.total}, 是否还有更多: ${favorPage.hasMore}');

9. 点赞剧集

await PangrowthContent.likeDramaEpisode(1008611, 3, like: true);

10. 剧集解锁状态

final episodes = await PangrowthContent.getDramaEpisodesStatus(
  dramaId: 1008611,
  freeSet: 3,
);
// EpisodeStatus(index: 4, isLocked: true)

11. 校验短剧解锁参数

final verifyResult = await PangrowthContent.verifyDramaParams(
  total: 30,
  freeSet: 3,
  lockSet: 2,
);

返回值结构：

Map<String, dynamic> {
  'total': int,      // 总集数
  'freeSet': int,    // 免费集数
  'lockSet': int,    // 解锁集数
  'verified': bool,  // 是否通过校验
}

平台差异：

Android: 返回 SDK 校验后的真实结果，verified 为 SDK 计算的校验状态
iOS: 暂未提供原生校验接口，返回输入值并附带 verified: false

示例：

final result = await PangrowthContent.verifyDramaParams(
  total: 30,
  freeSet: 3,
  lockSet: 2,
);

if (result['verified'] == true) {
  debugPrint('参数校验通过: ${result['freeSet']}集免费, ${result['lockSet']}集解锁');
} else {
  debugPrint('参数校验失败或平台不支持');
}

📦 `DramaInfo` 数据结构

class DramaInfo {
  final int id;                // 短剧 ID
  final String title;          // 标题
  final String coverImage;     // 封面 URL
  final String desc;           // 简介
  final int total;             // 总集数
  final int index;             // 当前进度/历史记录中的最后集数
  final String type;           // 分类名称（可能为空）
  final int typeId;            // 分类 ID（Android）
  final int status;            // 状态（0 已完结 / 1 连载）
  final int freeSet;           // 免费集数
  final int lockSet;           // 单次可解锁集数
  final int createTime;        // 创建时间时间戳（ms）
  final int actionTime;        // 历史记录操作时间（ms）
  final String scriptName;     // 原著名称
  final String scriptAuthor;   // 原著作者
  final bool isFavor;          // 是否收藏
  final int favoriteCount;     // 收藏次数
  final int favoriteTime;      // 收藏时间戳（ms）
  final int levelLabel;        // 等级标签（1:S / 2:A / 3:B）
  final bool isPotential;      // 是否潜力剧
  final String icpNumber;      // 备案号
  final int groupId;           // 当前播放剧集的 groupId（iOS）
  final List<EpisodeStatus> episodeStatusList; // 剧集锁定信息
}

EpisodeStatus：

class EpisodeStatus {
  final int index;     // 集数（从 1 开始）
  final bool isLocked; // 是否上锁
}

收藏列表接口返回 DramaPageResult：

class DramaPageResult {
  final List<DramaInfo> items;   // 短剧列表
  final int total;               // 总条数（若 SDK 未返回，则为本页数量）
  final bool hasMore;            // 是否还有下一页
  final Map<String, dynamic> others; // SDK 透出的其他字段
}

💡 常用开发模式

批量加载 + 分类筛选

final categories = await PangrowthContent.getCategoryList();
if (categories.isNotEmpty) {
  final dramas = await PangrowthContent.getDramaListByCategory(categories.first);
  // 根据业务渲染 UI
}

收藏开关

Future<void> toggleFavorite(DramaInfo info) async {
  final nextState = !info.isFavor;
  await PangrowthContent.setDramaFavorite(info.id, favorite: nextState);
  await PangrowthContent.getDramaFavorList(page: 1, count: 20);
}

剧集解锁提示

final statuses = await PangrowthContent.getDramaEpisodesStatus(
  dramaId: info.id,
  freeSet: info.freeSet,
);
final lockedEpisode = statuses.firstWhere((e) => e.isLocked, orElse: () => const EpisodeStatus(index: 0, isLocked: false));
if (lockedEpisode.index > 0) {
  // 提示用户完成激励行为以解锁剧集 lockedEpisode.index
}

通过上述接口可以快速搭建短剧内容的自建列表、推荐位、收藏中心等功能；若还需要自建聚合页或播放页，可继续参考后续章节。