内置头像账号

一、插件简介

内置头像（avatars）面向社区站点，在账号设置「上传头像」页提供预设头像网格，用户点击即可使用，无需上传。支持后台维护头像列表、新用户注册时随机分配头像。

适合统一社区视觉风格、降低用户设置门槛。

• 前台入口：会员中心 → 账号设置 → 上传头像页内置头像区（member_avatar_panel 插槽）
• 后台入口：应用中心 → 内置头像 → 配置
• 主要接口（伪静态后缀下同）：
• POST /avatars/pick — 选择内置头像

二、核心能力

三、依赖与安装

建议环境：

• 已安装并启用 社区（community） 插件（会员中心、头像上传页）
• public/static/plugins/avatars/ 目录可写（安装时同步资源）

安装步骤：

1. 应用中心安装并启用 内置头像
2. 打开「启用内置头像」
3. 在配置中维护头像列表（默认 10 张内置图）
4. （可选）开启「新用户随机头像」
5. 访问账号设置页验证选择与随机注册

卸载说明： 卸载不删除已发布的静态资源，避免已使用内置头像的用户头像失效。

四、应用中心基础配置

路径：应用中心 → 内置头像 → 配置

默认头像路径： /static/plugins/avatars/1.webp … 10.webp

列表为空时： 回退到 defaultAvatarUrls() 内置 10 张。

五、头像列表维护（重点）

5.1 添加方式

• 上传添加：配置页「添加并上传头像」，支持 jpg/png/gif/webp
• 粘贴地址：每行一个站内图片 URL

5.2 URL 规则

• 支持相对路径（自动补 / 前缀）
• 支持 http(s):// 绝对地址与 data: URI
• isAllowedUrl 仅允许列表内地址被 pick 接口接受

5.3 静态资源同步

install() 与 ensureAssets() 会将 plugins/avatars/static/ 复制到 public/static/plugins/avatars/。

六、前台用户流程

1. 用户进入会员中心 → 账号设置 → 上传头像
2. 页面上方为本地上传，下方为「选择内置头像」网格（若启用）
3. 点击某张内置头像，请求 POST /avatars/pick 提交 url
4. 成功后即时更新预览与导航栏头像
5. 新用户注册时若开启随机头像，系统自动从列表抽取（resolveRegisterAvatar）

七、后台审核与运维

无独立后台菜单，运维在应用中心：

八、特殊说明

插件钩子：

• member_avatar_panel — 渲染内置头像 HTML+CSS+JS（内联）

注册钩子： 社区注册流程调用 AvatarsPlugin::resolveRegisterAvatar() 获取随机 URL。

随机逻辑： randomAvatarUrl() 从 avatarList() 中 array_rand；列表空则回退 /static/admin/images/users/avatar.jpg。

安全： pick 接口校验 URL 必须在允许列表内。

九、推荐上线清单

1. 启用插件，确认静态资源已同步到 public
2. 检查默认 10 张头像是否正常显示
3. 按需上传品牌风格头像替换默认图
4. 开启新用户随机头像
5. 测试：点击选择 → 刷新页面头像一致
6. 测试：新注册账号是否获得随机头像

十、常见问题

Q：上传头像页看不到内置区？ 检查「启用内置头像」、头像列表是否非空。

Q：点击头像提示设置失败？ 可能 URL 不在允许列表；或用户未登录。

Q：图片 404？ 确认 public/static/plugins/avatars/ 下有对应文件；可重装插件触发 syncAssets。

Q：随机头像不生效？ 确认「新用户随机头像」开启；社区注册流程需调用 resolveRegisterAvatar。

Q：卸载后头像还能用吗？ 已选 URL 仍指向 public 静态文件，一般不受影响。

Q：能否只用外链头像？ 可以，在列表中粘贴完整 https 地址即可（须通过 isAllowedUrl 校验）。