DooTask 项目列表视图(表格视图)使用指南:分组分段、周口径与底层实现解析

原创2026-10-15 12:29:391,972 阅读
文章标签:后端前端桌面应用协同办公

DooTask 项目列表视图(表格视图)使用指南:分组分段、周口径与底层实现解析

DooTask 的项目详情页除了默认的看板视图,还提供按「行」组织的列表视图(表格视图):任务以「我的任务 / 协助的任务 / 未完成任务 / 已完成任务」等分段展示,并可叠加「本周到期 / 下周排期 / 已逾期 / 未排期」等周口径分组,适合按时间维度批量审视任务排期与逾期情况。本文以 列表视图使用说明 为骨架,完整讲解入口、分组规则、列结构、行内操作与能力边界,并结合前端源码(projectTableGroups.js、ProjectPanel.vue 等)与 单元测试 解析其背后的分组计算、周区间与持久化机制,让读者既会操作、也看得懂实现。

入口:如何切换到列表视图

在桌面端 Web 上:

  1. 进入项目详情页;
  2. 找到右上角的视图切换条(看板 / 列表 / 甘特图三个图标排成一行,从左到右依次对应 column / table / gantt);
  3. 点击第二个图标(横线列表样式,即「表格」),数据立即以列表视图重排。

切换过程不重新向后端请求任务数据(任务数据已在前端),只改变排版方式。视图选择按「项目 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 以单元测试形式锁定,可作为理解与回归验证的权威依据。

登录后查看全文
dootask