告别千篇一律：Wekan自定义字段完全指南，3步打造专属看板系统
项目地址: https://gitcode.com/GitHub_Trending/we/wekan 你是否还在为通用看板无法匹配业务流程而烦恼？项目管理中需要追踪"优先级""负责人""截止日期"等信息时，却只能用标签勉强替代？Wekan的自定义字段功能彻底解决了这个痛点。本文将通过3个实战步骤，带你从零开始配置符合团队需求的业务看板，读完你将掌握：8种字段类型的精准应用场景、批量数据处理技巧、以及API集成高级玩法。
一、自定义字段核心价值与应用场景
Wekan作为开源看板系统（LICENSE），其自定义字段功能允许用户突破固定模板限制，根据实际业务需求设计数据结构。典型应用场景包括：
- 项目管理：添加"负责人""优先级""风险等级"等字段
- 销售跟踪：创建"客户等级""成交概率""合同金额"字段
- Bug跟踪：设计"严重程度""复现步骤""测试状态"字段
根据CHANGELOG.md记录，该功能已支持从Trello导入自定义字段，并实现CSV/TSV格式的导入导出，确保数据迁移无缝衔接。
二、8种字段类型与配置指南
Wekan提供8种自定义字段类型（定义于models/customFields.js第27-35行），每种类型都有其独特应用场景：
2.1 基础数据类型
| 字段类型 | 应用场景 | 关键配置项 |
|---|---|---|
| 文本（text） | 简短描述、备注信息 | showOnCard控制卡片显示 |
| 数字（number） | 数量、评分、版本号 | showSumAtTopOfList开启列表汇总 |
| 日期（date） | 截止日期、创建时间 | 自动提供日期选择器 |
| 复选框（checkbox） | 完成状态、是否验证 | 布尔值存储 |
2.2 高级业务类型
下拉菜单（dropdown）：适用于有固定选项集的场景，如优先级（高/中/低）。配置时需通过settings.dropdownItems定义选项：
{
"settings": {
"dropdownItems": [
{"_id": "rnd123", "name": "高"},
{"_id": "rnd456", "name": "中"},
{"_id": "rnd789", "name": "低"}
]
}
}
货币（currency）：用于财务数据跟踪，需指定settings.currencyCode（如"USD"或"CNY"）。
字符串模板（stringtemplate）：通过自定义格式组合多个字段值，需设置stringtemplateFormat和stringtemplateSeparator。
2.3 配置示例：创建"任务优先级"字段
- 以管理员身份登录，进入目标看板设置
- 选择"添加自定义字段"，类型选择"dropdown"
- 在设置中添加选项：
{
"name": "任务优先级",
"type": "dropdown",
"settings": {
"dropdownItems": [
{"_id": "p1", "name": "紧急"},
{"_id": "p2", "name": "高"},
{"_id": "p3", "name": "中"},
{"_id": "p4", "name": "低"}
]
},
"showOnCard": true,
"showLabelOnMiniCard": true
}
三、通过API管理自定义字段
对于高级用户，Wekan提供完整的REST API用于自定义字段管理（文档见docs/API/Custom-Fields.md）。基本操作流程如下：
3.1 获取认证令牌
首先通过管理员账号登录获取Bearer令牌：
curl -X POST https://your-wekan-instance/api/users/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"your-password"}'
3.2 创建自定义字段
使用POST请求创建字段（需替换boardId和字段参数）：
curl -X POST https://your-wekan-instance/api/boards/{boardId}/custom-fields \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "合同金额",
"type": "currency",
"settings": {"currencyCode": "CNY"},
"showSumAtTopOfList": true
}'
3.3 更新卡片字段值
给指定卡片设置自定义字段值时，需使用数组格式传递数据：
curl -X PUT https://your-wekan-instance/api/boards/{boardId}/lists/{listId}/cards/{cardId} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customFields": [{"_id": "fieldId", "value": 5000}]
}'
三、高级技巧与最佳实践
3.1 批量操作与数据管理
Wekan支持通过CSV导入导出自定义字段数据（CHANGELOG.md第8331行），对于大批量数据处理特别有用。导入时需注意：
- 字段名称需与看板中定义完全一致
- 日期格式使用ISO标准（YYYY-MM-DD）
- 下拉框值需与预设选项完全匹配
3.2 性能优化建议
当自定义字段数量较多时，可通过以下方式提升性能：
- 仅对必要字段设置
showOnCard: true（models/customFields.js第82行） - 禁用不需要的汇总计算（showSumAtTopOfList）
- 定期清理不再使用的自定义字段
3.3 常见问题排查
若遇到自定义字段不显示的问题，可按以下步骤排查：
- 检查字段
showOnCard属性是否设为true - 确认用户有足够权限（docs/Login/Adding-users.md）
- 验证字段是否已添加到目标看板
四、总结与展望
自定义字段是Wekan最强大的功能之一，通过本文介绍的方法，你可以：
- 根据业务需求选择合适的字段类型
- 通过API实现自动化数据管理
- 遵循最佳实践确保系统性能
随着Wekan的持续发展（FUTURE.md），自定义字段功能将支持更多高级特性，如跨看板字段同步和条件格式设置。立即尝试配置你的第一个自定义字段，打造真正属于团队的看板系统！
点赞收藏本文，关注项目README.md获取最新功能更新，下期将带来"自定义字段与自动化规则结合"的高级教程。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
