astro-bangumi
v1.0.0
Published
A Bangumi integration for Astro, similar to hexo-bilibili-bangumi
Maintainers
yuzifuReadme
astro-bangumi
一个用于 Astro 的追番集成，灵感来自 hexo-bilibili-bangumi。
功能特性
- 🎬 多数据源支持 - 支持 Bilibili 和 Bangumi.tv API
- 📊 追番状态管理 - 想看、在看、看过三种状态
- 🎭 分类筛选 - 支持番剧和影视分类筛选
- 📄 分页功能 - 每页显示 10 个项目，支持平滑滚动
- 🌓 暗色模式 - 自动检测系统主题，支持自定义暗色选择器
- 🎨 主题定制 - 使用 CSS 变量，方便自定义主题颜色
- 🖼️ 图片代理 - 支持封面图片镜像，解决防盗链问题
- 📱 响应式设计 - 完美适配移动端和桌面端
- 🔢 数字格式化 - 自动格式化大数字（万、亿）
- ⚡ 懒加载 - 图片懒加载优化性能
- 🔄 开发环境支持 - 开发模式下自动获取最新数据
- 🔗 刷新 API - 提供数据刷新端点，支持手动更新
安装
npm install astro-bangumi使用方法
1. 配置集成
在 astro.config.mjs 中添加集成：
import { defineConfig } from 'astro/config';
import bangumi from 'astro-bangumi';
export default defineConfig({
integrations: [
bangumi({
source: 'bili',
vmid: '你的B站UID',
title: '追番列表',
quote: '生命不息，追番不止！',
coverMirror: '',
category: [1, 2],
})
]
});2. 在页面中使用组件
创建一个页面（如 src/pages/bangumi.astro）：
---
import Bangumi from 'astro-bangumi/Bangumi';
---
<html>
<head>
<title>追番列表</title>
</head>
<body>
<Bangumi
title="我的追番"
quote="生命不息，追番不止！"
show={1}
lazyload={true}
darkSelector="html:not([theme='dark'])"
categoryFilter="all"
/>
</body>
</html>配置选项
集成配置（astro.config.mjs）
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| source | 'bili' \| 'bgmv0' | 'bili' | 数据源选择 |
| vmid | string | - | 用户 ID（必填） |
| title | string | '追番列表' | 页面标题 |
| quote | string | '生命不息，追番不止！' | 页面引言 |
| coverMirror | string | '' | 封面图片代理地址，用于解决防盗链 |
| category | number \| number[] | [1, 2] | 分类：1=番剧, 2=影视（仅 bili 源） |
| lazyload | boolean | true | 启用图片懒加载 |
| devMode | boolean | true | 启用开发模式，开发环境下自动获取数据 |
| refreshEndpoint | string \| false | '/api/bangumi/refresh' | 刷新 API 端点路径，设为 false 禁用 |
| showMyComment | boolean | false | 显示个人评论（仅 bgmv0 源） |
| localDataPath | string | - | 本地番剧数据文件路径（相对项目根目录） |
| extraOrder | number | 0 | 本地数据显示顺序：1=优先显示，其他=默认顺序 |
数据源说明
| 数据源 | 说明 | vmid 格式 | 特点 |
|--------|------|-----------|------|
| bili | Bilibili API | B站用户 UID（数字） | 支持番剧/影视分类，数据丰富 |
| bgmv0 | Bangumi.tv API v0 | Bangumi 用户名或用户 ID | 官方 API，支持自动分页获取全部数据 |
Bangumi API v0 说明
使用 bgmv0 数据源时：
- API 基础地址:
https://api.bgm.tv/v0 - 默认获取动漫类型数据 (
subject_type=2) - 每页最多 50 条记录，自动分页获取全部数据
- 请求间隔 100ms 防止频率限制
- 支持显示个人评论和评分（需设置
showMyComment: true） - vmid 支持两种格式：
- 用户名（推荐）：如
sai - 用户 ID：如
123456
- 用户名（推荐）：如
获取 Bangumi 用户名/ID 方法：
- 登录 Bangumi.tv
- 进入个人主页
- 从 URL 获取：
https://bgm.tv/user/sai→ 用户名为saihttps://bgm.tv/user/123456→ 用户 ID 为123456
本地番剧数据
支持添加本地番剧数据，用于补充 API 中没有的番剧或完全使用本地数据。
数据文件格式
创建 JSON 文件（如 bangumi-local.json）：
{
"want": [
{
"id": "local_001",
"title": "自定义番剧名称",
"cover": "https://example.com/cover.jpg",
"url": "https://bgm.tv/subject/12345",
"status": 1,
"total": 12,
"progress": 0,
"score": 8.5,
"desc": "简介内容",
"airDate": "2024-01-01",
"type": "TV",
"follow": 10000
}
],
"watching": [],
"watched": []
}使用方式
方式一：API + 本地数据（混合模式）
从 API 获取数据，同时合并本地数据：
// astro.config.mjs
bangumi({
source: 'bgmv0',
vmid: '你的Bangumi用户名',
localDataPath: './bangumi-local.json', // 本地数据文件路径
extraOrder: 1, // 1=本地数据优先显示，0=默认顺序
})方式二：纯本地数据模式
不使用 API，完全使用本地数据：
// astro.config.mjs
bangumi({
localDataPath: './bangumi-local.json', // 只配置本地数据路径，不配置 vmid
title: '我的追番列表',
})字段说明
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | ✅ | 唯一标识符 |
| title | string | ✅ | 番剧标题 |
| cover | string | ✅ | 封面图片 URL |
| url | string | ✅ | 番剧链接 |
| status | 1 \| 2 \| 3 | ✅ | 1=想看, 2=在看, 3=看过 |
| total | number | - | 总集数 |
| progress | number | - | 当前观看进度 |
| score | number | - | 评分（0-10） |
| desc | string | - | 简介 |
| airDate | string | - | 上映日期 |
| type | string | - | 类型（TV, Movie, OVA 等） |
| follow | number | - | 追番人数 |
| view | number | - | 播放数 |
| comment | string | - | 个人评论 |
| myScore | number | - | 个人评分 |
组件属性（Bangumi 组件）
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| title | string | '追番列表' | 标题 |
| quote | string | '生命不息，追番不止！' | 引言 |
| show | 0 \| 1 \| 2 | 1 | 默认显示的标签页：0=想看, 1=在看, 2=看过 |
| lazyload | boolean | true | 启用图片懒加载 |
| darkSelector | string | - | 暗色模式 CSS 选择器 |
| categoryFilter | 'all' \| '1' \| '2' | 'all' | 分类筛选：'all'=全部, '1'=番剧, '2'=影视 |
主题定制
CSS 变量
组件使用 CSS 变量定义主题颜色，你可以在父元素中覆盖这些变量：
.bangumi-container {
--bangumi-bg: #ffffff; /* 背景色 */
--bangumi-bg-secondary: #f4f4f4; /* 次要背景色 */
--bangumi-text: #333333; /* 主文本颜色 */
--bangumi-text-secondary: #666; /* 次要文本颜色 */
--bangumi-text-muted: #999; /* 弱化文本颜色 */
--bangumi-border: #eeeeee; /* 边框颜色 */
--bangumi-shadow: rgba(0,0,0,0.1); /* 阴影颜色 */
--bangumi-primary: #00a1d6; /* 主题色 */
--bangumi-primary-hover: #00a1d6; /* 主题色悬停 */
--bangumi-primary-text: #fff; /* 主题文本色 */
}
/* 暗色模式 */
.bangumi-container.dark {
--bangumi-bg: #1a1a1a;
--bangumi-bg-secondary: #2a2a2a;
--bangumi-text: #e0e0e0;
--bangumi-text-secondary: #b0b0b0;
--bangumi-text-muted: #808080;
--bangumi-border: #333333;
--bangumi-shadow: rgba(0,0,0,0.3);
}暗色模式
组件自动检测系统暗色模式，也支持手动控制：
自动检测
<Bangumi />自定义暗色选择器
如果你的博客使用特定的暗色模式类名或属性：
<!-- 当 html 元素没有 theme='dark' 属性时为暗色模式 -->
<Bangumi darkSelector="html:not([theme='dark'])" />
<!-- 当 html 元素包含 dark 类时为暗色模式 -->
<Bangumi darkSelector="html:not(.dark)" />JavaScript API
// 获取当前主题
const theme = window.bangumiTheme.getTheme(); // 'light' | 'dark'
// 设置主题
window.bangumiTheme.setTheme('dark'); // 'auto' | 'dark' | 'light'数据格式
BangumiItem 接口
interface BangumiItem {
id: string; // 番剧 ID
title: string; // 标题
cover: string; // 封面图片 URL
url: string; // 番剧链接
status: 1 | 2 | 3; // 1=想看, 2=在看, 3=看过
category?: 1 | 2; // 1=番剧, 2=影视
total?: number; // 总集数
progress?: number; // 观看进度
score?: number; // 评分
desc?: string; // 描述
airDate?: string; // 上映日期
type?: string; // 类型
follow?: number; // 追番数
view?: number; // 播放数
danmaku?: number; // 弹幕数
reply?: number; // 评论数
coin?: number; // 投币数
likes?: number; // 点赞数
favorite?: number; // 收藏数
comment?: string; // 个人评论（仅 bgm/bgmv0）
myScore?: number; // 个人评分（仅 bgm/bgmv0）
}数据存储
数据会在构建时获取并存储在 node_modules/.astro-bangumi/bangumi-data.json 中。
开发环境支持
自动获取数据
在开发模式下（astro dev），插件会自动获取最新数据：
- 每次启动开发服务器时自动获取数据
- 支持配置
devMode: false禁用此功能
刷新 API
开发模式下提供数据刷新端点，默认路径为 /api/bangumi/refresh。
触发方式
浏览器直接访问：
http://localhost:4321/api/bangumi/refresh使用 curl：
curl http://localhost:4321/api/bangumi/refresh在页面中添加刷新按钮：
---
import Bangumi from 'astro-bangumi/Bangumi';
---
<Bangumi />
<script>
async function refreshBangumi() {
const res = await fetch('/api/bangumi/refresh');
const data = await res.json();
if (data.success) {
alert('刷新成功！');
location.reload();
} else {
alert('刷新失败：' + data.error);
}
}
document.querySelector('#refresh-bangumi')?.addEventListener('click', refreshBangumi);
</script>
<button id="refresh-bangumi">刷新追番数据</button>返回格式
{
"success": true,
"message": "Data refreshed successfully",
"stats": {
"want": 10,
"watching": 5,
"watched": 20,
"lastUpdate": "2026-04-04T01:40:00.000Z"
}
}自定义端点路径
// astro.config.mjs
bangumi({
vmid: '你的B站UID',
refreshEndpoint: '/api/my-refresh', // 自定义路径
// refreshEndpoint: false, // 禁用刷新端点
})图片代理
由于 Bilibili 图片有防盗链限制，可以使用图片代理：
// astro.config.mjs
bangumi({
coverMirror: 'https://your-image-proxy.com/?url='
})代理 URL 格式：
https://proxy.com/?url=+ encodeURIComponent(imageUrl)- 或
https://proxy.com/+ imageUrl
示例
使用 Bilibili 数据源
// astro.config.mjs
bangumi({
source: 'bili',
vmid: '你的B站UID',
title: '追番列表',
category: [1, 2], // 番剧和影视
})使用 Bangumi API v0 数据源
// astro.config.mjs
bangumi({
source: 'bgmv0',
vmid: '你的Bangumi用户名',
title: '追番列表',
showMyComment: true, // 显示个人评论
})基础用法
---
import Bangumi from 'astro-bangumi/Bangumi';
---
<Bangumi />自定义配置
---
import Bangumi from 'astro-bangumi/Bangumi';
---
<Bangumi
title="我的追番"
quote="追番使我快乐"
show={1}
categoryFilter="1"
darkSelector="html.dark"
/>仅显示番剧
---
import Bangumi from 'astro-bangumi/Bangumi';
---
<Bangumi categoryFilter="1" />使用本地数据补充
// astro.config.mjs
bangumi({
source: 'bgmv0',
vmid: '你的Bangumi用户名',
localDataPath: './bangumi-local.json', // 补充 API 中没有的番剧
extraOrder: 1, // 本地数据优先显示
})纯本地数据模式
// astro.config.mjs
bangumi({
// 不配置 vmid，只使用本地数据
localDataPath: './bangumi-local.json',
title: '我的追番列表',
quote: '手动维护的追番记录',
})开发
# 安装依赖
npm install
# 构建
npm run build
# 开发模式
npm run dev许可证
MIT
致谢
- 灵感来源：hexo-bilibili-bangumi
- 数据来源：Bilibili、Bangumi.tv