add_role( string $role, string $display_name, bool[] $capabilities = array() )

使用示例

• 示例1

  请确保在触发挂钩或条件块中仅使用此函数（以及类似的角色函数）。无需每次加载页面时都执行此操作，每次调用时都会不断更新数据库。

  例如，这将存储跟踪自定义角色版本的选项，并且只更新数据库一次：

  function xx__update_custom_roles() {
      if ( get_option( 'custom_roles_version' ) < 1 ) {
          add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
          update_option( 'custom_roles_version', 1 );
      }
  }
  add_action( 'init', 'xx__update_custom_roles' );
  

• 示例2

  您还可以基于现有用户角色轻松创建新用户角色。
  （相当于WP CLI:wp role create <role-key> <role-name> --clone=<role>）

  示例：创建一个与管理员具有相同能力的角色

  add_role( 'superintendent', 'Superintendent', get_role( 'administrator' )->capabilities );
  

• 示例3

  在激活插件时创建新角色
  请参见register_activation_hook。

  function add_roles_on_plugin_activation() {
         add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
     }
  register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );

• 示例4

  示例
  创建一个新的“Guest Author”角色。

  $result = add_role(
  	'guest_author',
  	__( 'Guest Author', 'testdomain' ),
      array(
  		'read'         => true,  // true allows this capability
  		'edit_posts'   => true,
  		'delete_posts' => false, // Use false to explicitly deny
      )
  );
  
  if ( null !== $result ) {
      echo "Success: {$result->name} user role created.";
  }
  else {
      echo 'Failure: user role already exists.';
  }

• 示例5

  注意：删除现有角色
  不能使用add_role()更改现有角色的能力。如果指定的角色名称已存在，此函数将停止执行并返回null。

  您可以使用remove_role()，然后使用add_role()，来更改用户角色的能力（或显示名称）。

  这仅用于开发。一旦确定了能力列表，就无需保留remove_role()代码。

• 示例6

  每个用户角色的所有可能能力列表：
  https://wordpress.org/support/article/roles-and-capabilities/#capability-vs-role-table

  Super Admin
  =========================
  create_sites
  delete_sites
  manage_network
  manage_sites
  manage_network_users
  manage_network_plugins
  manage_network_themes
  manage_network_options
  upload_plugins
  upload_themes
  upgrade_network
  setup_network

  Super Admin + Administrator
  ==========================================
  activate_plugins (single site or enabled by network setting)
  create_users (single site)
  delete_plugins (single site)
  delete_themes (single site)
  delete_users (single site)
  edit_files (single site)
  edit_plugins (single site)
  edit_theme_options
  edit_themes (single site)
  edit_users (single site)
  export
  import

  Super Admin + Administrator
  =============================================
  install_plugins (single site)
  install_themes (single site)
  list_users
  manage_options
  promote_users
  remove_users
  switch_themes
  update_core (single site)
  update_plugins (single site)
  update_themes (single site)
  edit_dashboard
  customize
  delete_site

  Super Admin + Administrator + Editor
  ====================================================
  moderate_comments
  manage_categories
  manage_links
  edit_others_posts
  edit_pages
  edit_others_pages
  edit_published_pages
  publish_pages
  delete_pages
  delete_others_pages
  delete_published_pages
  delete_others_posts
  delete_private_posts
  edit_private_posts
  read_private_posts
  delete_private_pages
  edit_private_pages
  read_private_pages
  unfiltered_html (single site)
  unfiltered_html

  Super Admin + Administrator + Editor + Author
  ==========================================================
  edit_published_posts
  upload_files
  publish_posts
  delete_published_posts

  Super Admin + Administrator + Editor + Author + Contributor
  ========================================================================
  edit_posts
  delete_posts

  Super Admin + Administrator + Editor + Author + Contributor + Subscriber
  ======================================================================================
  read

• 示例7

  注意：当调用时
  在尝试添加或修改角色之前，请确保全局$wp_roles可用。最佳实践是使用插件（或主题）激活挂钩对角色进行更改（因为您只想做一次！）。

  mu-plugins加载太早，因此如果您在mu-plugin的上下文中执行此操作，请使用动作钩子（如'init'）来包装add_role()调用。

• 示例8

  用法

  <?php add_role( $role, $display_name, $capabilities ); ?>