Zibll Audio Upload 插件说明文档

功能特性

• 在 TinyMCE 编辑器工具栏添加音频上传按钮
• 支持拖拽上传和点击选择文件
• 支持外链音频 URL 插入
• 实时上传进度显示（含百分比）
• 友好的 Toast 提示反馈
• 完善的权限控制和 CSRF 安全防护
• 可配置最大上传文件大小
• 多主题兼容性（自动适配不同编辑器 DOM 结构）

支持的音频格式

系统要求

• WordPress 5.0+
• 子比主题（Zibll）7.0+
• PHP 7.4+

安装步骤

1. 下载插件文件夹 zibll-audio-upload
2. 上传至 WordPress 插件目录 /wp-content/plugins/
3. 在后台「插件」页面启用插件
4. 进入「设置」→「音频上传」进行配置

使用方法

上传音频文件

1. 在文章编辑页面，点击富文本编辑器工具栏的 🎵 按钮
2. 选择「上传音频」标签页
3. 点击上传区域或直接拖拽音频文件
4. 上传完成后自动插入编辑器

插入外链音频

1. 点击工具栏的 🎵 按钮
2. 选择「外链音频」标签页
3. 输入音频文件的完整 URL
4. 点击「插入音频」

插入效果

配置选项

权限说明

• 具有 upload_files 权限（默认编辑者及以上）
• 具有 edit_posts 权限（作者及以上）
• 具有 edit_pages 权限

安全特性

技术特性

• 多种编辑器兼容：自动适配 .mce-toolbar、.tox-toolbar、[role="toolbar"] 等多种 DOM 结构
• 智能重试机制：未检测到编辑器时自动重试（最多20次，间隔200ms）
• 定时备用检查：每秒检查一次编辑器加载状态，持续60秒
• MutationObserver 监听：实时监听 DOM 变化，自动为新编辑器添加按钮

常见问题

Q: 上传失败，提示”安全验证失败”

Q: 提示”文件大小超过限制”

Q: 按钮没有显示

1. 确认插件已启用
2. 确认已开启”启用音频上传”选项
3. 确认使用的是富文本编辑器模式
4. 刷新页面或重新加载编辑器

更新日志

15.1.0 (当前版本)

安全优化

• 新增 CSRF 安全防护（Nonce 验证）
• 优化权限检查逻辑
• 添加服务端文件扩展名校验
• 外链 URL 格式验证

用户体验优化

• 添加 Toast 提示反馈（成功/失败/信息）
• 显示上传进度百分比
• 支持拖拽时视觉反馈
• 文件名实时显示
• 渐变进度条效果

代码质量优化

• 提取音频格式为类常量
• 添加 'use strict' 严格模式
• 所有输出使用 esc_url()/esc_attr()/esc_html() 转义
• 详细的文件上传错误码映射

兼容性优化

• 多种选择器自动适配不同主题
• 智能重试机制（最多20次）
• MutationObserver 实时监听
• 定时备用检查（60秒）

15.0.0

• 初始版本
• 支持音频文件上传
• 支持外链音频插入

文件结构

作者信息

• 作者：小武
• 网址：https://1z345.cn
• 许可证：GPL-2.0-or-later

许可证