wajxy_avatar 插件介绍
基本信息
插件名称：注册选择头像
插件目录：
wajxy_avatar当前版本：
1.0.3XIUNOX 兼容分支：
1.1作者：金小颖论坛
类型：Plugin
功能简介
wajxy_avatar 为 XIUNOX 注册页面增加预设头像选择功能。头像区域与邀请码插件使用同一个注册字段 Hook，并以较低权重执行，因此会自然显示在邀请码输入框下方。
插件默认附带 50 张 512×512 PNG 头像，注册页一次随机展示 5 张。用户可以点击“换一换”重新随机显示一组头像，也可以直接选择头像后完成注册。
主要功能
注册页显示预设头像。
默认提供 50 张头像，名称为“头像 1”至“头像 50”。
一次默认展示 5 张；设为 0 时可展示全部头像。
支持随机“换一换”。
支持默认选中当前展示的第一张头像。
支持将头像设置为注册必选项。
注册提交前在服务端重新验证头像 ID 和启用状态。
注册成功后保存用户与预设头像的映射。
通过用户格式化 Hook 统一输出所选头像，兼容头像组件和站内用户展示。
用户在个人中心上传自定义头像后，自动解除预设头像映射。
提供简体中文、繁体中文和英文语言文本。
后台管理
设置页遵循 WAJXY 后台 UI 规范，包含：
Hero 插件头部、运行状态和版本徽章。
PHP、上传限制、WebP、启用头像数量环境卡。
基础设置、展示设置、头像库三个 Pills Tab。
左文右开关行、胶囊数值输入和下拉框。
原生 JavaScript 异步保存、按钮 Loading 和 Toast 提示。
粘性保存栏与居中渐变版权栏。
头像库支持：
新增头像。
替换已有头像图片。
修改头像名称和排序。
启用或停用头像。
删除头像并解除相关用户映射。
上传 JPG、PNG、WebP；最大 2MB，最小 48×48。
默认设置
设置 | 默认值 |
|---|---|
启用插件 | 是 |
注册必须选择 | 是 |
默认选择首个 | 是 |
允许换一换 | 是 |
一次显示 | 5 个 |
头像尺寸 | 56 px |
选中强调色 | 主题色 |
数据表
wajxy_avatar_item
保存头像名称、文件路径、启用状态、显示顺序和创建时间。
wajxy_avatar_user
保存用户 UID 与预设头像 ID 的映射。UID 为主键，确保每个用户只有一个生效的预设头像。
数据库表均使用 InnoDB 和 utf8mb4。
Hook 说明
Hook | 用途 |
|---|---|
| 在注册密码及邀请码区域之后显示头像选择 |
| 注册提交前校验必选头像 |
| 注册成功后绑定头像 |
| 将预设头像 URL 写入格式化用户数据 |
| 用户上传自定义头像后解除预设映射 |
| 加载前台头像样式 |
| 加载选择和随机刷新脚本 |
| 注册 |
头像 Hook 权重为 40；邀请码插件对应 Hook 权重为 50，因此邀请码区域先输出，头像区域随后输出。
安装与升级
新安装
在 XIUNOX 后台上传
wajxy_avatar_v1.0.3.zip。安装并启用插件。
进入插件设置页确认头像库和注册规则。
清理
tmp/编译缓存。
新安装会创建两张数据表，并导入 50 张默认头像。
从旧版升级
升级脚本会幂等执行：
使用
SHOW COLUMNS检查必要字段，缺失时才执行ALTER TABLE。移除早期版本的 6 张 JPG 默认头像记录。
导入或维护 50 张 PNG 默认头像。
将默认头像名称统一为“头像 N”。
将“一次显示”同步为 5。
保留管理员自行上传的其他头像。
文件结构
wajxy_avatar/
├── conf.json
├── icon.png
├── logo.png
├── install.php
├── upgrade.php
├── uninstall.php
├── setting.php
├── SELF_CHECK.md
├── PLUGIN_INTRO.md
├── hook/
├── model/WajxyAvatarService.php
├── view/htm/setting.htm
├── static/css/
├── static/js/
├── static/img/presets/
└── upload/
view/htm/setting.htm 是插件自有设置页面，不是对核心模板的覆盖；插件没有使用 overwrite/。
注意事项
安装或升级后必须清理 XIUNOX
tmp/编译缓存，否则旧 Hook 编译结果可能继续生效。若服务器禁止插件目录写入，后台上传头像会失败，需要为
plugin/wajxy_avatar/upload/配置适当写权限。删除头像会解除所有使用该头像的用户映射，这些用户将恢复为核心默认头像。
