DooTask 项目列表视图(表格视图)使用指南:分组分段、周口径与底层实现解析
DooTask 项目列表视图(表格视图)使用指南:分组分段、周口径与底层实现解析
DooTask 的项目详情页除了默认的看板视图,还提供按「行」组织的列表视图(表格视图):任务以「我的任务 / 协助的任务 / 未完成任务 / 已完成任务」等分段展示,并可叠加「本周到期 / 下周排期 / 已逾期 / 未排期」等周口径分组,适合按时间维度批量审视任务排期与逾期情况。本文以 列表视图使用说明 为骨架,完整讲解入口、分组规则、列结构、行内操作与能力边界,并结合前端源码(projectTableGroups.js、ProjectPanel.vue 等)与 单元测试 解析其背后的分组计算、周区间与持久化机制,让读者既会操作、也看得懂实现。
入口:如何切换到列表视图
在桌面端 Web 上:
- 进入项目详情页;
- 找到右上角的视图切换条(看板 / 列表 / 甘特图三个图标排成一行,从左到右依次对应
column/table/gantt); - 点击第二个图标(横线列表样式,即「表格」),数据立即以列表视图重排。
切换过程不重新向后端请求任务数据(任务数据已在前端),只改变排版方式。视图选择按「项目 ID × 当前用户」维度记录在本地缓存 cacheParameter.menuType='table',下次进入同一项目仍保持列表视图;切换项目的视图不会自动跟随。默认视图为 column(看板),相关说明可参考 切换看板 / 列表 / 甘特图视图 与 项目视图概览。
在移动端 / 触屏设备上,视图切换条位于项目详情页顶部同一位置(图标更小);列表图标同样只负责切换视图,不会触发分组菜单。
列表分段:10 个可复选分组
列表视图的核心组织方式是「分段」(分组)。切换到表格模式后,鼠标悬停视图切换组前的设置齿轮图标,会弹出分组复选下拉菜单;触屏设备需先切换表格,再点击齿轮打开选择。菜单与项目筛选弹层采用一致的外观(无箭头、无标题栏),勾选后保持打开,可连续复选;切走表格视图(如切到看板或甘特图)时齿轮隐藏、菜单关闭。
全部可选分组及默认显示情况如下:
| 分组 | 默认显示 | 范围 |
|---|---|---|
| 我的任务 | 是 | 当前用户负责的任务 |
| 协助的任务 | 是 | 当前用户协助的主任务 |
| 未完成任务 | 是 | 项目内未完成主任务,包含本人任务 |
| 已完成任务 | 否 | 项目内已完成主任务 |
| 本周到期 / 下周到期 | 否 | 到期时间落在对应周的主任务 |
| 本周排期 / 下周排期 | 否 | 计划开始、结束时间完整且与对应周相交的主任务 |
| 已逾期 | 否 | 未完成,且到期时间早于当前时间的主任务 |
| 未排期 | 否 | 未完成,且缺少计划开始时间或结束时间的主任务 |
这 10 个分组在源码中是一份静态配置表,位于 projectTableGroups.js,每个分组声明了 key(内部标识)、title(显示名)、expandedKey(对应的折叠状态缓存键)、defaultVisible(是否默认勾选)以及可选的 week(0 = 本周、1 = 下周)与 kind(due / planned / overdue / unscheduled):
export const projectTableGroups = [
{key: 'my', title: '我的任务', expandedKey: 'showMy', defaultVisible: true},
{key: 'help', title: '协助的任务', expandedKey: 'showHelp', defaultVisible: true},
{key: 'undone', title: '未完成任务', expandedKey: 'showUndone', defaultVisible: true},
{key: 'completed', title: '已完成任务', expandedKey: 'showCompleted'},
{key: 'dueThisWeek', title: '本周到期', expandedKey: 'showDueThisWeek', week: 0, kind: 'due'},
{key: 'dueNextWeek', title: '下周到期', expandedKey: 'showDueNextWeek', week: 1, kind: 'due'},
{key: 'plannedThisWeek', title: '本周排期', expandedKey: 'showPlannedThisWeek', week: 0, kind: 'planned'},
{key: 'plannedNextWeek', title: '下周排期', expandedKey: 'showPlannedNextWeek', week: 1, kind: 'planned'},
{key: 'overdue', title: '已逾期', expandedKey: 'showOverdue', kind: 'overdue'},
{key: 'unscheduled', title: '未排期', expandedKey: 'showUnscheduled', kind: 'unscheduled'},
];
默认只勾选「我的任务 / 协助的任务 / 未完成任务」三项。分组下拉组件 ProjectTableGroupDropdown.vue 用 Checkbox 渲染每一项,并在只剩最后一项勾选时将该复选框置为禁用(disabled + title 提示「至少保留一项」),从交互层面保证所有分组均可取消,但至少保留一项。
周口径:周一零点到下周一零点(不含)
「本周 / 下周」的时间边界统一为:每周从周一零点到下周一零点(不含),使用系统现有时区口径。计算逻辑见 projectTableGroups.js 的 projectWeekRanges:
export function projectWeekRanges(now) {
// Do not depend on the current translation locale's first day of the week.
const monday = now.startOf('day').subtract((now.day() + 6) % 7, 'day');
return [0, 1].map(week => ({
start: monday.add(week * 7, 'day').valueOf(),
end: monday.add((week + 1) * 7, 'day').valueOf(),
}));
}
- 本周区间 = 本周一 00:00 → 下周一 00:00(不含);下周区间紧接其后,
ranges[0].end与ranges[1].start相等; - 计算刻意不依赖当前翻译 locale 的「每周起始日」,统一按周一;
- 边界条件在 测试用例 中有明确覆盖:周日、跨年(如 2027-01-01 的「本周」从 2026-12-28 开始)均按周一口径计算。
按此口径,到期时间落在对应周的主任务进入「本周到期 / 下周到期」分组(kind: 'due',要求 end_at 落在 [周一00:00, 下周一00:00),测试用例 L66-L73 验证了含周一零点、不含下周一零点);计划开始、结束时间完整且与对应周相交的主任务进入「本周排期 / 下周排期」分组(kind: 'planned',要求 start_at、end_at 都存在且时间区间与目标周相交)。因此:
- 跨周计划的任务可同时出现在两周分组;
- 同一任务也可出现在多个分组(如同时是「我的任务」与「本周到期」);
- 缺少开始或结束时间、时间字段非法、开始晚于结束的排期任务,不会进入排期分组(见 测试用例)。
子任务沿用行内展开,不单独成段。分组匹配与归属判断实现在 taskMatchesProjectWeek 与 taskMatchesProjectGroup(projectTableGroups.js),其中「已逾期」要求任务未完成且 end_at 严格早于当前时间(等于当前时间不算逾期,见 测试用例),「未排期」要求任务未完成且 start_at 或 end_at 至少缺一个(见 测试用例)。
折叠、空状态与勾选行为
- 每个分组标题左侧的箭头可独立控制折叠;折叠状态分别记录在对应分组的
expandedKey(如showMy、showDueThisWeek)缓存中,勾选分组不会覆盖原有折叠状态。 - 勾选后即使数量为 0 也显示分组标题和空状态(「暂无任务」),不再按是否有任务自动隐藏。这一行为与历史版本不同:测试用例 L314-L322 专门断言模板中已不再使用
v-if="projectData.task_num > 0"或按列表长度判断隐藏,而是统一以visibleTableGroups.includes('key')决定是否渲染分段(见 ProjectPanel.vue)。 - 新勾选的分组自动展开,并在表格内滚动定位到该分组标题;若目标靠近表格底部,则以最大可滚动位置为限。取消勾选不会触发定位,横向滚动位置与顶部设置入口保持不变,菜单保持打开,可继续复选。
滚动定位的稳定性算法
「勾选后滚动到分组标题」并非简单的一次性 scrollTo,因为列表行是懒渲染的,滚动过程中新行渲染会把目标顶走。前端为此实现了「稳定目标滚动」算法,见 scrollToStableTarget.js:
- 先发起一次平滑滚动(
behavior: 'smooth')到目标位置; - 之后每 80ms 重新渲染并测量目标位置,若目标因高度变化发生偏移,初次滚动后(约 600ms 起)改用瞬时滚动(
instant)校正,且不重复启动新的平滑动画; - 当位置连续约 240ms 稳定时结束,整体最长持续 2.5 秒(
deadline超时即取消,不再持续追踪后续高度变化); - 手动滚轮、触屏、拖动滚动条、滚动按键(方向键、PageUp/PageDown、Home/End、空格),以及更改分组选择、切换项目或视图,都会中断旧定位。
对应的调用链在 ProjectPanel.vue 的 scrollToTableGroup:先取消旧请求,再在 $nextTick 后从 projectTableScroll 滚动容器中查询 <a href="https://link.gitcode.com/i/382df0bccaf961f97091f6d55eae3d90" target="_blank">data-table-group="${key}"] 目标节点,把渲染与测距交给 scrollToStableTarget;切换项目或切出表格视图时通过 watch 与 cancelTableGroupScroll 及时取消(L1269-L1293)。多组勾选、重复触发、失效请求被替换等场景均有测试覆盖([tests/project-table-groups.test.mjs)。
持久化与缓存:分组选择、折叠、视图三者独立
- 分组显示选择存于项目本地缓存
cacheParameter.tableGroups,与视图选择(menuType)走同一套缓存机制(cacheProjectParameter),按项目维度隔离,不跨设备同步。 - 缓存写入由 Vuex action toggleProjectParameter 完成:先按
project_id定位(不存在则用projectParameterTemplate初始化),再通过project/parameter/splice把新的参数对象合并进该项目的缓存条目。测试用例 L120-L162 验证了「勾选分组写入tableGroups+ 对应expandedKey,且不覆盖原有showMy/menuType」,不同项目的缓存互不影响。 - 三个状态维度相互独立:勾选哪些分组(
tableGroups)、各分组是否折叠(各expandedKey)、处于哪种视图(menuType)。调整其中一个不会覆盖另外两个。 - 若本地缓存缺失、损坏或只含未知分组 key,会回退到默认三项(
normalizeProjectTableGroups,见 projectTableGroups.js),测试用例 L40-L53 覆盖了undefined / null / {} / [] / ['unknown']等异常输入。
「本周排期 / 下周排期」的更名历史
「本周排期 / 下周排期」原名为「本周任务 / 下周任务」。改名仅修改显示名称,原有选择和折叠缓存保留(plannedThisWeek / plannedNextWeek 及 showPlannedThisWeek / showPlannedNextWeek 这些 key 未变),因此老用户的勾选状态不会因升级而丢失。测试用例 L47-L48 同时断言了新旧标题映射关系。
列结构:固定五列
列表视图列结构固定,不可自定义增删:
| 列 | 说明 | 是否可表头排序 |
|---|---|---|
| 任务名称 | 含 # 编号 | 否 |
| 列表 | 任务所在的 column(看板列) | 否 |
| 优先级 | 任务优先级 | 是(点击表头) |
| 负责人 | 任务负责人 | 否 |
| 到期时间 | 任务到期时间 | 是(点击表头) |
表头模板见 ProjectPanel.vue:优先级与到期时间两列的表头带有升/降序箭头,点击后通过 onSort('level') / onSort('end_at') 切换排序方向,其余列表头无排序交互。分组内任务会跟随全局排序(如周分组内按到期时间或优先级升/降序排列,见 additionalTableGroups 与 测试用例)。
行内操作
- 点击任务行 → 打开任务详情;
- 行右侧 「+」 → 在该分段下快速添加任务(
fast-add-task); - 行右侧 「···」 → 单行任务操作菜单(
TaskMenu)。
列表行的渲染组件为 TaskRow,复用看板视图同一套任务行组件与权限控制(readonly 在部门只读模式下生效,只读时仍可查看与切换视图,但不能编辑任务)。
与搜索、筛选、「显示已完成」的关系
- 搜索和顶部筛选仍生效:列表视图的分组计算建立在「经过搜索与顶部 Cascader 筛选后的任务集」之上。测试用例 L229-L250 验证了周分组会复用完成状态、搜索关键字、负责人 / 标签 / 工作流筛选结果——例如搜索
'alpha'时各分组只保留匹配任务,按user:/tag:筛选时分组随之收窄。 - 「显示已完成」 影响「我的任务 / 协助的任务 / 本周到期 / 下周到期 / 本周排期 / 下周排期」这些分组(开启后已完成任务也会计入),但不影响独立的「已完成任务」分组(它本身只展示已完成任务,与开关无关)。
- 「已逾期」「未排期」始终只含未完成任务,即使开启「显示已完成」也不会混入已完成任务(见 测试用例);「已逾期」分组会随当前时间推移自动更新(时间过了到期的任务自动进入该分组)。
能力边界:列表视图不支持什么
- 不能自定义列:列结构固定为任务名 / 列表 / 优先级 / 负责人 / 到期时间,不能增删列、改顺序或改宽度;
- 不支持双击编辑:点击任务行打开的是任务详情,不是行内编辑;
- 没有 Excel 式选区批量操作:不能多选行批量改字段(如批量改负责人);
- 行内排序仅「优先级 / 到期时间」两列可点,其余表头无排序;
- 没有独立的筛选器:任务筛选依赖顶部 Cascader(搜索框 + 工作流 / 负责人 / 标签筛选);
- 至少保留一个分组:分组不能全部取消;
- 移动端 / 触屏端同样支持分组选择与折叠,但列表视图无拖拽排序能力(拖拽在 touch 设备被禁用,这是全部视图的通用限制)。
小结:从使用到实现的完整链路
列表视图的完整数据流可以概括为:toggleProjectParameter(Vuex action,actions.js)把勾选结果写入 cacheProjectParameter → ProjectPanel.vue 的 visibleTableGroups 计算属性经 normalizeProjectTableGroups 归一化 → additionalTableGroups 用 projectTableGroups.js 的分组定义与周区间函数对任务集做归属计算 → 模板按 data-table-group 分段渲染 → 勾选新分组时由 scrollToStableTarget 完成稳定滚动定位。整条链路的边界行为(周一口径、默认分组、至少保留一项、逾期边界、空分组常驻、滚动中断条件、缓存隔离)都由 tests/project-table-groups.test.mjs 以单元测试形式锁定,可作为理解与回归验证的权威依据。