Hina Music Player WP Registry grade A. No security issues foundWP RegistryNo security issues foundOpen the reportA

一个面向个人博客的轻量级 WordPress 全站音乐播放器。它使用 WordPress 媒体库管理音频和封面，支持拖拽排序、前台选歌、音量记忆、位置记忆，以及 Argon 主题的 PJAX 与动态配色。

安装插件时请从 Releases 下载 hina-music-player-x.y.z.zip，不要直接安装 GitHub 自动生成的 Source code 压缩包。

English README

功能

• 从 WordPress 媒体库上传或选择音频、封面
• 批量导入歌曲并拖拽调整播放顺序
• 前台歌单、列表循环、单曲循环和随机播放
• 可拖动悬浮播放器，并记住每个浏览器的位置
• 一键折叠为圆形封面，播放不中断并记住访客选择
• 独立音量滑块，支持静音和恢复上次音量
• 透明中性界面，支持 Argon 明暗模式
• 自动读取 Argon 的 --themecolor，前台换色时同步更新
• 支持 Argon PJAX 切换，不重复创建播放器
• 不依赖第三方音乐 API；APlayer 已随插件本地提供

环境要求

• WordPress 6.0 或更高版本
• PHP 7.4 或更高版本
• 支持现代 CSS 与 JavaScript 的浏览器

Argon 不是必需依赖。使用其他主题时，播放器会读取页面的 theme-color，或使用后台设置的自定义颜色。

安装

1. 在 Releases 下载最新发布包。
2. 进入 WordPress 后台 → 插件 → 安装插件 → 上传插件。
3. 选择 ZIP 并启用 Hina Music Player。
4. 打开后台左侧“音乐播放器”，导入歌曲、选择封面并保存。

升级时直接上传新版 ZIP 并选择“替换当前版本”。不要先删除旧插件，因为卸载操作会删除插件设置；媒体库里的音频和图片不会被删除。

配色方式

后台“播放器配色”提供两种模式：

• 跟随网站主题：优先读取 Argon 的 --themecolor，其次读取 <meta name="theme-color">。
• 使用自定义颜色：始终使用插件后台选择的颜色。

跟随模式下，Argon 前台颜色选择器改变 --themecolor 后，播放器会通过 CSS 级联即时同步，不需要刷新页面。

隐私与网络请求

插件不会收集访问数据，也不会把歌单发送到外部服务。音频和封面 URL 来自你的 WordPress 媒体库或手动填写的地址。第三方组件 APlayer 随插件本地加载，不依赖公共 CDN。

开发

主要目录：

hina-music-player/
├─ assets/                 # 前后台 CSS 与 JavaScript
├─ includes/               # WordPress 插件逻辑
├─ vendor/aplayer/         # APlayer 1.10.1
├─ tools/                  # 本地发布脚本
├─ .github/workflows/      # CI 与 GitHub Release
├─ hina-music-player.php   # 插件入口
└─ uninstall.php           # 卸载清理

本地检查：

Get-ChildItem -Recurse -Filter *.php | ForEach-Object { php -l $_.FullName }
node --check assets/js/admin.js
node --check assets/js/player.js
composer validate --strict --no-check-publish

构建可安装 ZIP：

powershell -ExecutionPolicy Bypass -File tools/build-release.ps1

Linux/macOS：

bash tools/build-release.sh

产物会写入 dist/。推送形如 v1.2.0 的标签时，发布工作流会校验标签与插件版本一致，并创建带 SHA-256 校验文件的 GitHub Release。

贡献与安全

• 首次建立 GitHub 仓库请阅读 docs/PUBLISHING.md。
• 提交代码前请阅读 CONTRIBUTING.md。
• 安全问题请按照 SECURITY.md 私下报告，不要直接创建公开 Issue。
• 普通缺陷和功能建议可以使用仓库内置的 Issue 模板。

许可证

本项目使用 GPL-2.0-or-later。内置的 APlayer 1.10.1 使用 MIT License，详情见 THIRD-PARTY-NOTICES.txt。