# jellyfin-actor-web

**Repository Path**: oneonly/jellyfin-actor-web

## Basic Information

- **Project Name**: jellyfin-actor-web
- **Description**: Jellyfin 原生缺少全局演员浏览页面。
现有 ActorsIndex 插件功能有限、无中文、强耦合插件系统。
本项目是独立轻量前端，直接调用 Jellyfin API，提供完整演员管理工具，以卡片形式展示所有演员，支持收藏、归档、筛选和搜索。开箱即用无需安装插件。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jellyfin 演员列表库

一个基于 Jellyfin API 的演员管理工具，以卡片形式展示所有演员，支持收藏、归档、筛选、排序和搜索，演员数据可同步到本地持久化。

## 功能特性

- 连接 Jellyfin 服务器，拉取所有演员数据
- 演员卡片展示：头像、名称、作品数量
- 收藏 / 归档管理，数据持久化到 `data.json`
- 一键同步演员数据到本地 `actor.json`，断网也能浏览
- 深色主题 UI，现代化设计
- 工具栏：搜索、多级作品数量筛选、收藏/归档/头像状态筛选
- 多维度排序：名称、作品数量
- 可调节卡片大小（小 / 中 / 大）
- 前端分页，可自定义每页条数（20 / 30 / 60）
- 点击卡片跳转 Jellyfin 演员详情页
- 响应式布局，适配手机 / 平板 / 桌面

## 页面展示
![输入图片说明](image/%E5%88%97%E8%A1%A8.png)
![输入图片说明](image/%E9%85%8D%E7%BD%AE.png)
![输入图片说明](image/%E6%94%B6%E8%97%8F.png)
![输入图片说明](image/%E8%B7%B3%E8%BD%AC.png)
## 快速开始

### 环境要求

- [Node.js](https://nodejs.org) 14+（推荐）

### 启动

**Windows 用户**：双击 `start.bat`

**命令行**：

```bash
# Node.js（推荐）
node server.js

# 或 npm
npm start
```

浏览器自动打开 `http://localhost:3000`。

### 配置 Jellyfin 连接

1. 在 Jellyfin 管理后台 → 高级 → API 密钥 中生成一个 API Key
2. 在页面顶部配置面板填入：
   - **服务器地址**：Jellyfin 的 IP（如 `192.168.1.100`）
   - **端口**：默认 `8096`
   - **API Key**：上一步生成的密钥
3. 点击 **🔗 连接**

配置信息自动保存到浏览器本地存储，下次打开页面自动连接。

## 使用说明

### 演员卡片

| 操作 | 说明 |
|------|------|
| 点击卡片 | 在新标签页打开 Jellyfin 演员详情页 |
| ⭐ 收藏 | 收藏演员，卡片边框高亮为金色 |
| 📦 归档 | 归档演员，卡片半透明 + 灰度 |

### 工具栏

| 功能 | 说明 |
|------|------|
| 搜索框 | 实时搜索演员姓名 |
| 作品数量 | 筛选 ≤ 3 / ≤ 10 / ≥ 1 / ≥ 2 / ≥ 3 / ≥ 10 / ≥ 20 / ≥ 30 / ≥ 50 部作品 |
| ⭐ 已收藏 | 仅显示已收藏的演员 |
| ☆ 未收藏 | 仅显示未收藏的演员 |
| 📦 已归档 | 仅显示已归档的演员 |
| 📥 未归档 | 仅显示未归档的演员 |
| 🖼️ 有图 | 仅显示有头像的演员 |
| 🚫 无图 | 仅显示无头像的演员 |
| 排序 | 名称 A→Z / Z→A / 作品数量 多→少 / 少→多 |
| 卡片大小 | 小 / 中 / 大 三种尺寸切换 |
| 🔄 重置 | 清除所有筛选条件 |

### 同步演员数据

连接服务器后，点击顶部的 **💾 同步** 按钮，将服务器上的演员数据拉取并保存到本地 `actor.json` 文件中。同步完成后会自动获取每位演员的作品数量。

- 再次连接同一服务器时，优先加载本地缓存，无需重新同步
- 点击 **🗑️ 清除缓存** 可删除当前服务器的本地缓存数据
- 收藏和归档数据不受清除缓存影响

### 分页

- 默认每页显示 60 条，可在分页栏切换为 20 / 30 条
- 支持上一页 / 下一页翻页和直接跳转到指定页码
- 每页条数设置自动保存到浏览器本地存储

### 数据持久化

| 文件 | 内容 |
|------|------|
| `data.json` | 收藏/归档数据，按服务器地址区分，不会因清除浏览器缓存而丢失 |
| `actor.json` | 同步的演员缓存数据，包含演员基本信息、作品数量和同步时间 |

## 文件结构

```
├── jellyfin-actors.html   # 主页面（HTML + JavaScript）
├── jellyfin-actors.css    # 样式表
├── server.js              # HTTP 服务器 + API
├── data.json              # 收藏/归档持久化数据
├── actor.json             # 演员缓存数据
├── image/                 # 截图等图片资源
├── start.bat              # Windows 一键启动脚本
├── package.json           # 项目信息
└── README.md              # 本文件
```

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/data?server=ip:port` | 获取指定服务器的收藏/归档数据 |
| `POST` | `/api/data` | 保存收藏/归档数据 |
| `GET` | `/api/actors?server=ip:port` | 获取指定服务器的演员缓存数据 |
| `POST` | `/api/actors` | 保存演员缓存数据（含同步时间） |
| `DELETE` | `/api/actors?server=ip:port` | 删除指定服务器的演员缓存 |

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | `3000` | HTTP 服务端口 |