OAK-Roles

📖 插件说明

OAK-Roles 是一个功能强大的 WordPress 插件，允许用户拥有多个角色。与 WordPress 默认的单一角色系统不同，本插件让用户能够同时拥有多个角色的权限，提供更灵活的权限管理。

✨ 主要功能

• 多角色支持：用户可以同时拥有多个角色
• 友好的复选框界面：在用户编辑页面使用复选框替代默认下拉框
• 用户列表显示：在用户列表中直接显示用户的所有角色
• 权限验证：完整的权限检查机制，确保只有有权限的管理员能修改角色
• 多站点支持：完全支持 WordPress 多站点（Multisite）功能
• 安全防护：集成 nonce 验证和数据清理

🔧 插件架构

插件采用 MVC 模式设计，分为三个核心类：

1. MRC_Model - 数据模型层

处理角色数据的核心逻辑：

• get_roles() - 获取所有可用角色
• get_editable_roles() - 获取当前用户可编辑的角色
• get_user_roles() - 获取指定用户的角色
• update_roles() - 更新用户角色
• can_update_roles() - 检查是否有权限更新角色

2. MRC_Checklist_Controller - 复选框控制器

处理用户界面和角色选择：

• 隐藏默认的角色下拉框
• 输出角色复选框界面
• 处理表单提交
• 支持多站点用户注册流程

3. MRC_Column_Controller - 列表控制器

管理用户列表显示：

• 修改用户列表的角色列
• 以链接形式显示用户的多个角色

📦 安装

1. 将插件文件夹上传到 /wp-content/plugins/ 目录
2. 在 WordPress 后台插件页面激活 OAK-Roles 插件
3. 进入用户编辑页面，您将看到新的角色复选框界面

🚀 使用方法

编辑用户角色

1. 进入 WordPress 后台 用户 > 所有用户
2. 点击需要编辑的用户
3. 在"用户角色"部分选中需要的角色（可多选）
4. 点击"更新个人资料"保存

创建新用户

1. 进入 用户 > 新增用户
2. 填写用户基本信息
3. 在"用户角色"部分选中所需角色
4. 点击"新增用户"完成创建

用户列表查看

在用户列表页面，"角色"列显示用户拥有的所有角色，可直接点击角色进行筛选。

🔒 权限说明

以下条件下用户无法修改角色：

• 网络管理员（Multisite 环境）
• 无 promote_users 权限的用户
• 在个人资料页面修改自己角色且非网站管理员

🌐 多站点支持

插件完全支持 WordPress 多站点环境：

• 在多站点用户注册时保存角色选择
• 激活用户时自动应用预设角色
• 保留各个站点独立的角色管理

🔍 钩子和过滤器

动作钩子 (Action Hooks)

// 更新角色前
do_action('mrc_before_update_roles', $user_id, $roles);

// 更新角色后
do_action('mrc_after_update_roles', $user_id, $roles, $user->roles);

过滤钩子 (Filter Hooks)

// 获取所有角色
apply_filters('mrc_get_roles', $roles);

// 获取可编辑角色
apply_filters('mrc_get_editable_roles', $roles);

// 获取用户角色
apply_filters('mrc_get_user_roles', $roles);

// 检查是否可编辑角色
apply_filters('mrc_can_update_roles', true);

📋 代码示例

获取用户的所有角色

$model = new MRC_Model();
$user_roles = $model->get_user_roles($user_id);
foreach ($user_roles as $slug => $name) {
    echo $name . ', ';
}

检查用户是否拥有特定角色

$model = new MRC_Model();
$user_roles = $model->get_user_roles($user_id);
if (array_key_exists('editor', $user_roles)) {
    echo '用户是编辑';
}

更新用户角色

$model = new MRC_Model();
$roles = ['editor', 'author', 'contributor'];
$model->update_roles($user_id, $roles);

🔐 安全特性

• ✅ Nonce 验证：所有表单提交都进行 nonce 验证
• ✅ 权限检查：调用 current_user_can() 验证用户权限
• ✅ 数据清理：使用 sanitize_key() 清理角色数据
• ✅ 有效性验证：仅接受系统中存在的角色

📝 翻译支持

插件支持国际化（i18n），所有文本字符串均可翻译：

• 文本域：multiple-roles-single
• 语言文件位置：/languages/

💡 自定义开发

自定义允许编辑的角色

add_filter('mrc_get_editable_roles', function($roles) {
    // 只允许编辑编辑和作者角色
    return array_intersect_key($roles, ['editor' => 1, 'author' => 1]);
});

在角色更新时执行自定义操作

add_action('mrc_after_update_roles', function($user_id, $roles) {
    // 发送邮件通知或执行其他操作
    wp_mail(get_user_by('id', $user_id)->user_email, '角色已更新', '...');
}, 10, 2);

🐛 故障排除

Q: 复选框没有显示

A: 确认：

• 插件已激活
• 当前用户有 promote_users 权限
• 不在网络管理员账户上进行操作

Q: 修改角色后不生效

A: 检查：

• 浏览器缓存是否已清除
• 用户权限是否足够
• 日志中是否有错误信息

📞 技术支持

• 插件首页：https://www.lilianhua.com/
• 作者：OAK
• 作者网站：https://www.lilianhua.com/

📄 许可证

本插件遵循 WordPress 插件许可证规范。

🙏 致谢

感谢您使用 OAK-Roles 插件！如有任何建议或反馈，欢迎联系我们。

---

版本：1.0
最后更新：2026 年 7 月