OpenProject 用户属性（User attributes）管理完全指南：扩展用户档案、自定义字段与映射配置

OpenProject 用户属性User attributes管理完全指南扩展用户档案、自定义字段与映射配置【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openprojectUser attributes用户属性是 OpenProject 提供的一项管理能力允许管理员在标准用户档案之外扩展额外的信息维度例如职位头衔Job title、技能、证书或使用语言。这些属性可以显示在用户档案、用户悬浮卡片hover card以及资源管理模块的用户卡片上。本文将以官方系统管理指南为主体结合仓库源码深入讲解如何查看、创建、分组、编辑与删除用户属性并详解 Mapped attributes映射属性的配置原理帮助管理员与二次开发者完整掌握这一功能模块。一、什么是用户属性内置属性与自定义属性在 OpenProject 中用户属性本质上是一种面向用户User实体、作用域为全局的自定义字段Custom Field。从源码结构看它的实现模型为UserCustomField该类继承自核心的CustomField并混入了CustomField::Sectionable分节能力模块同时通过belongs_to :user_custom_field_section与分节模型UserCustomFieldSection建立关联。内置属性OpenProject 提供以下不可删除的内置用户属性Username用户名First name名字Last name姓氏Email电子邮箱Language语言Department部门在源码中这些内置属性由UserCustomFieldSection::BUILT_IN_ATTRIBUTES常量直接定义%w[login firstname lastname mail language department]。内置属性只能调整其在列表中的顺序上移、下移、置顶、置底不能编辑或删除。自定义属性你还可以创建任意数量的自定义用户属性例如Job title职位头衔Spoken languages使用语言Key skills关键技能Job start date入职日期自定义属性除排序外还支持完整的编辑与删除操作。二、查看用户属性列表进入管理后台Administration settings管理设置→ Users and permissions用户与权限→ User attributes用户属性。在该页面可以创建与管理自定义用户属性将属性分组到不同的 Section分区中选择哪些属性显示在用户卡片上从源码角度看该页面由Admin::Settings::UserCustomFieldsController#index提供支撑其对应的系统测试位于 spec/features/admin/custom_fields/users/index_spec.rb测试中验证了非管理员无法访问该页面返回 You are not authorized to access this page.并校验了分区与属性的显示顺序。用户属性页面分为两个标签页Attributes属性列出所有已配置的用户属性属性被组织进各个 Section分区中Mapped attributes映射属性将特定的语义用途如 Job title绑定到某个自定义属性上三、Attributes 标签页属性与分区管理3.1 属性行的组成在Attributes标签页中每个属性行包含拖拽手柄Drag handle用户属性名称格式FormatMore…菜单图标3.2 创建与管理分区Sections分区用于将属性分组展示。添加分区的步骤点击右上角的 Add按钮选择Section随后为分区命名并保存。通过分区标题右侧的More菜单可以对分区执行重命名、删除或重新排序属性可以在分区之间拖拽移动整个分区也可以借助分区名左侧的拖拽手柄进行拖拽排序[!TIP] 分区只有在不包含任何属性时才能被删除。[!TIP] 属性在所有用户档案中始终显示在它被分配到的分区内。从源码层看分区的增删改排序分别由UserCustomFieldSectionsController的create、update、destroy、move、drop动作驱动底层调用UserCustomFieldSections目录下的CreateService、UpdateService、DeleteService等服务对象并通过 Turbo Stream 无刷新更新页面。其中DeleteService继承自::BaseServices::Deletedelete_service.rb而模型层has_many :custom_fields, dependent: :restrict_with_exceptionuser_custom_field_section.rb保证了非空分区禁止删除这一约束。功能测试 index_spec.rb 亦明确验证了分区下仍有属性时删除按钮被禁用aria-disabledtrue清空属性后才可以删除。3.3 用户属性格式User attribute formats创建用户属性时需要从以下格式中选择一种格式说明Boolean布尔值以复选框形式呈现勾选或不勾选Date日期通过日期选择器date picker选取Float有理数小数Hierarchy企业版附加组件层级结构选择可选择一个或多个层级列表项结构在属性创建后的Items标签页中维护Integer整数List平面列表选项Text文本格式可限制长度Long text长文本适用于需要输入较长内容的场景不同格式会提供不同的附加参数例如最小/最大宽度、默认值或用于校验的正则表达式。[!IMPORTANT] 用户属性一旦创建无法更改其格式。3.4 创建用户属性创建新属性的步骤点击右上角 Add按钮选择User attribute从可用格式列表中选择一种用户属性格式以下是一个List格式的用户属性创建示例表单中的关键配置项Name名称用户属性在用户档案及其他展示位置显示的名称Section分区如果已创建分区可选择该属性归属的分区Allow multi-select允许多选允许用户为该字段赋予多个值Required必填勾选后启用该属性并使其对所有用户为必填无法在单个用户层面取消激活。已有用户在进行更新时不会被强制要求补填该值Admin-only仅管理员可见启用后该属性仅对管理员可见其他用户看不到Editable可编辑允许用户自行编辑该属性Show on user card显示在用户卡片上在用户悬浮卡片悬停于用户名上时显示的信息中展示该属性[!IMPORTANT]Boolean类型的用户属性不能被设置为必填。属性创建完成后还可以继续为其定义帮助文本以及针对 List/Hierarchy 等格式维护选项列表。3.5 Hierarchy 层级用户属性企业版附加组件类型为Hierarchy的用户属性其行为与Hierarchy类型的工作包自定义字段完全一致。详细信息请参阅工作包自定义字段文档。该功能受特性开关custom_field_hierarchies控制对应企业版附加组件其选项结构由Admin::Settings::UserCustomFields::Hierarchy::ItemsController管理。3.6 编辑、排序与删除用户属性编辑自定义属性选择More…菜单选择Edit按需更新属性设置重新排序用户属性属性按照本页面配置的顺序显示。通过属性旁的More…菜单可以选择Move to top移至顶部Move up上移Move down下移Move to bottom移至底部源码层面排序动作由UserCustomFieldsController#move调用CustomFields::MoveService与#drop调用CustomFields::DropService支持跨分区拖放实现分区内的字段顺序由attribute_order与分区的position共同驱动参见UserCustomFieldSection.with_filled_fields_for中按attribute_order过滤排序的逻辑。删除用户属性只有自定义用户属性可以被删除。选择More…菜单选择Delete确认删除删除操作会将该属性从所有用户档案中永久移除。3.7 定义用户属性帮助文本点击某个用户属性进入Help text标签页可以为属性定义Caption标题一段短文本作为属性标题展示以提供上下文Help text帮助文本一段较长文本当用户悬停在属性名旁的问号图标上时显示用于提供更详细的解释。这是必填字段Attachments附件附加文件或图片以图解该用户属性[!IMPORTANT] 此处添加的任何文本与附件对所有已登录用户均可见。帮助文本与附件功能由AttributeHelpTextActions等共享 Concern 提供支撑对应控制器动作attribute_help_text/update_attribute_help_textuser_custom_fields_controller.rb并有专门的系统测试 spec/features/admin/settings/user_custom_fields/attribute_help_text_spec.rb 覆盖。四、Mapped attributes 标签页为属性赋予语义用途Mapped attributes映射属性标签页允许你将特定的语义用途Purpose指派给某个自定义用户属性。映射规则每个用途Purpose只能指派给一个用户属性每个用户属性只能映射到一个用途当前 OpenProject 支持的映射属性如下用途说明Job title职位头衔在多个位置如用户卡片将每个用户的职位头衔显示在其姓名旁映射操作步骤打开Mapped attributes标签页从Job title下拉列表中选择一个自定义用户属性点击Save[!NOTE] 只有自定义用户属性可以被映射内置属性不在可选范围内。映射机制的源码实现从源码结构看映射在数据层由UserCustomField模型上的semantic_key字段承载enum :semantic_key, { job_title: job_title }, prefix: true validates :semantic_key, uniqueness: { scope: :type }, allow_nil: true scope :with_semantic_key, -(semantic_key) { where(semantic_key:) } def self.for_semantic_key(semantic_key) with_semantic_key(semantic_key).first endsemantic_key是一个枚举字段目前仅定义了job_title一个值prefix: true会生成semantic_key_job_title形式的辅助方法uniqueness: { scope: :type }唯一性校验正是每个用途只能映射一个用户属性这一规则在数据库层面的保证管理端界面由UserCustomFieldsController#index在tab semantic_keys时加载if params[:tab] semantic_keys semantic_key_field_options UserCustomField.order(:position) semantic_key_assignments UserCustomField.where.not(semantic_key: nil).index_by(:semantic_key) end保存映射则走update_semantic_keys动作user_custom_fields_controller.rb其内部assign_semantic_keys在事务中先将原持有者清空、再写入新的映射以始终满足(type, semantic_key)的唯一索引约束。五、属性的显示与消费悬浮卡片与用户档案用户属性配置完成后会通过以下途径在系统中展示用户档案User profile属性按所属分区、分区内按顺序渲染用户悬浮卡片Hover card鼠标悬停用户名时弹出仅显示勾选了Show on user card且已有值的属性资源管理模块的用户卡片参考资源管理用户指南从源码看悬浮卡片的渲染由Users::HoverCardComponent完成其核心调用为def card_sections_with_fields card_sections_with_fields || UserCustomFieldSection.with_filled_fields_for(user, visible_on_user_card: true) end对应的模型查询方法UserCustomFieldSection.with_filled_fields_for做了三件关键事情仅取当前用户可见UserCustomField.visible(User.current)的属性可选地只保留visible_on_user_card: true即勾选了显示在用户卡片上的属性通过user.custom_values.where.not(value: [nil, ])过滤出已填写值的属性再按分区与attribute_order排序输出——因此悬浮卡片上不会出现空属性占位。多值字段在卡片上以 Primer Label 标签形式渲染超出上限时显示 and N more 溢出提示hover_card_component.rb。相关测试位于 spec/components/users/hover_card_component_spec.rb 与 spec/components/users/profile/attributes_section_component_spec.rb。六、常见问题与注意事项汇总格式不可变用户属性创建后无法修改格式创建前需确认所选格式。内置属性不可删除内置属性Username、First name、Last name、Email、Language、Department只能排序不能编辑或删除。非空分区不可删除删除分区前必须先将其中所有属性移走或删除dependent: :restrict_with_exception约束 前端禁用双重保障。Boolean 不可设为必填布尔型属性存在此限制。必填不追溯将属性设为 Required 后已有用户更新时不会被强制要求补填。映射互斥每个 Purpose 只能绑定一个自定义属性反之亦然映射仅针对自定义属性。可见性边界Admin-only 属性仅管理员可见帮助文本与附件对所有已登录用户可见发布前请注意内容敏感性。七、相关文档与代码入口官方文档用户属性本指南关联文档工作包自定义字段含 Hierarchy 类型模型实现app/models/user_custom_field.rb、app/models/user_custom_field_section.rb控制器实现app/controllers/admin/settings/user_custom_fields_controller.rb、app/controllers/admin/settings/user_custom_field_sections_controller.rb服务层app/services/user_custom_field_sections/组件层app/components/users/hover_card_component.rb测试用例spec/features/admin/custom_fields/users/index_spec.rb、spec/features/admin/settings/user_custom_fields/attribute_help_text_spec.rb、spec/components/users/hover_card_component_spec.rb通过本文管理员可以在 OpenProject 中为团队构建丰富且结构化的用户档案体系用分区组织属性、用多种格式适配数据、用帮助文本降低填写歧义并通过 Mapped attributes 让自定义属性承担系统级语义如 Job title从而在用户卡片与档案中呈现统一的个人信息视图。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考