---

自定义角色

Blue中的自定义角色允许您定义精确的权限集，以满足团队的需求。除了标准访问级别（OWNER、ADMIN、MEMBER等）之外，自定义角色还提供对用户在项目中可以看到和执行的操作的细粒度控制。

基本示例 - 列出自定义角色

检索项目的所有自定义角色：

query GetProjectRoles {
  projectUserRoles(filter: { projectId: "web-redesign" }) {
    id
    name
    description
    allowInviteOthers
    canDeleteRecords
  }
}

高级示例 - 创建自定义角色

创建具有特定权限的承包商角色：

mutation CreateContractorRole {
  createProjectUserRole(
    input: {
      projectId: "web-redesign"
      name: "External Contractor"
      description: "Limited access for external contractors"
      allowInviteOthers: false
      allowMarkRecordsAsDone: true
      canDeleteRecords: false
      showOnlyAssignedTodos: true
      isActivityEnabled: true
      isFormsEnabled: false
      isWikiEnabled: true
      isChatEnabled: false
      isDocsEnabled: true
      isFilesEnabled: true
      isRecordsEnabled: true
      isPeopleEnabled: false
    }
  ) {
    id
    name
  }
}

可用操作

查询：projectUserRoles

检索项目的所有自定义角色。

输入参数

参数	类型	必需	描述
filter.projectId	String	否	项目ID或别名（如果未提供，则返回所有可访问项目的角色）

变更：createProjectUserRole

创建具有特定权限的新自定义角色。

输入参数

参数	类型	必需	描述
projectId	String!	✅ 是	项目ID或别名
name	String!	✅ 是	角色名称
description	String	否	角色描述
Permission Flags
allowInviteOthers	Boolean	否	可以邀请新用户（默认：false）
allowMarkRecordsAsDone	Boolean	否	可以完成任务（默认：false）
canDeleteRecords	Boolean	否	可以删除记录（默认：true）
Feature Access
isActivityEnabled	Boolean	否	访问活动部分（默认：true）
isChatEnabled	Boolean	否	访问聊天（默认：true）
isDocsEnabled	Boolean	否	访问文档（默认：true）
isFilesEnabled	Boolean	否	访问文件（默认：true）
isFormsEnabled	Boolean	否	访问表单（默认：true）
isWikiEnabled	Boolean	否	访问维基（默认：true）
isRecordsEnabled	Boolean	否	访问记录（默认：true）
isPeopleEnabled	Boolean	否	访问人员部分（默认：true）
Visibility Settings
showOnlyAssignedTodos	Boolean	否	仅查看分配的任务（默认：false）
showOnlyMentionedComments	Boolean	否	仅查看提到的评论（默认：false）

变更：updateProjectUserRole

更新现有的自定义角色。

输入参数

与 createProjectUserRole 相同，另外：

参数	类型	必需	描述
roleId	String!	✅ 是	要更新的角色ID

变更：deleteProjectUserRole

删除自定义角色。

输入参数

参数	类型	必需	描述
roleId	String!	✅ 是	要删除的角色ID
projectId	String!	✅ 是	项目ID或别名

响应字段

ProjectUserRole 对象

字段	类型	描述
id	String!	唯一角色标识符
name	String!	角色名称
description	String	角色描述
createdAt	DateTime!	创建时间戳
updatedAt	DateTime!	最后更新时间戳
Permissions
allowInviteOthers	Boolean!	可以邀请用户
allowMarkRecordsAsDone	Boolean!	可以完成任务
canDeleteRecords	Boolean!	可以删除记录
Feature Flags
isActivityEnabled	Boolean!	活动部分访问
isChatEnabled	Boolean!	聊天访问
isDocsEnabled	Boolean!	文档访问
isFilesEnabled	Boolean!	文件访问
isFormsEnabled	Boolean!	表单访问
isWikiEnabled	Boolean!	维基访问
isRecordsEnabled	Boolean!	记录访问
isPeopleEnabled	Boolean!	人员部分访问
Visibility
showOnlyAssignedTodos	Boolean!	任务可见性过滤器
showOnlyMentionedComments	Boolean!	评论可见性过滤器

所需权限

操作	所需权限
projectUserRoles	Any project member
createProjectUserRole	Project OWNER or ADMIN
updateProjectUserRole	Project OWNER or ADMIN
deleteProjectUserRole	Project OWNER or ADMIN

错误响应

权限不足

{
  "errors": [{
    "message": "You don't have permission to manage custom roles",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

找不到角色

{
  "errors": [{
    "message": "Custom role not found",
    "extensions": {
      "code": "PROJECT_USER_ROLE_NOT_FOUND"
    }
  }]
}

达到角色限制

{
  "errors": [{
    "message": "Project user role limit reached.",
    "extensions": {
      "code": "PROJECT_USER_ROLE_LIMIT"
    }
  }]
}

重要说明

• 默认权限：创建角色时，未指定的布尔权限默认为false，除了 canDeleteRecords，其默认为true
• 角色分配：通过设置 accessLevel: MEMBER 并在 inviteUser 变更中提供 roleId 来分配自定义角色
• 层级：出于层级目的，自定义角色被视为MEMBER级别
• 角色限制：每个项目最多可以有20个自定义角色
• 功能访问：功能标志控制对应用程序整个部分的访问

用例

承包商角色

{
  name: "Contractor",
  allowInviteOthers: false,
  canDeleteRecords: false,
  showOnlyAssignedTodos: true,
  isActivityEnabled: true,
  isChatEnabled: false,
  isPeopleEnabled: false
}

部门负责人

{
  name: "Department Lead",
  allowInviteOthers: true,
  allowMarkRecordsAsDone: true,
  canDeleteRecords: true,
  isActivityEnabled: true,
  isWikiEnabled: true,
  isPeopleEnabled: true
}

只读观察者

{
  name: "Observer",
  allowMarkRecordsAsDone: false,
  canDeleteRecords: false,
  allowInviteOthers: false,
  showOnlyMentionedComments: true,
  isFormsEnabled: false
}

相关操作

• 邀请用户 - 将自定义角色分配给用户
• 列出用户 - 查看用户及其角色
• 移除用户 - 从项目中移除用户