fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 85 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/ux/bitable-grid-guidelines.md

8.0 KiB
Raw Blame History

Bitable 多维表格 UI/UX 规范

适用范围：所有基于 vxe-table 的 bitable 视图（BitableGrid.vue 及其变体）。 目标：对齐 Twenty / Notion / Airtable 风格，消除「不像表格」「没有分隔线」「标题与数据对不齐」等基础 UI/UX 问题。

1. 布局原则

1.1 表格高度必须随内容（height: auto）

  • 禁止强制 height: 100% 或 flex: 1 撑满父容器。
  • 少量数据时，表格底部应紧贴最后一行，而不是拉伸出巨大空白。
  • 滚动条应出现在表格内容真正超出视口时，而不是因为容器被强制撑高。
/* Good */
.bitable-grid-scope { height: auto; }

/* Bad — causes the gap between header and data rows */
.bitable-grid-scope { height: 100%; }

1.2 父容器不得挤压表格

表格父容器应使用 flex: 0 0 auto 或 height: auto，避免剩余空间被表格占据。

/* Good */
.bitable-file-detail-view__grid-container { flex: 0 0 auto; overflow: visible; }

/* Bad — stretches the grid body */
.bitable-file-detail-view__grid-container { flex: 1; overflow: hidden; }

2. 边框与分隔

2.1 必须提供列分隔线

所有数据单元格和列头单元格必须有右侧竖线（border-right）。

.vxe-body--column,
.vxe-header--column { border-right: 1px solid var(--bitable-color-border); }
  • 最右侧一列不显示右边界（last-child { border-right: 0 }），避免边界悬空。
  • 行分隔线使用更浅的 --bitable-color-border（1px）。
  • 列头下边界使用更深的 --bitable-color-border-hover（2px），与行分隔形成层次。

2.2 禁止无意义的双重/三重分隔线

  • 标题区、视图切换区、列头区只能有一条主分隔线。
  • 如果父容器已经画了分隔线，子容器不要再重复画。

3. 对齐与间距

3.1 标题与数据单元格必须对齐

  • 列头单元格 padding 与数据单元格 padding 必须一致。
  • 所有单元格使用相同的垂直对齐方式（默认居中或居顶，但不能混用）。
.vxe-header--column,
.vxe-body--column { padding: var(--bitable-spacing-sm) var(--bitable-spacing-md); }

3.2 字号规范

元素 Token 说明
列头文字 --bitable-font-sm (13px) 略小于正文，表达层级
数据单元格 --bitable-font-md (14px) 与 antd Table 正文一致
空状态/提示 --bitable-font-sm (13px) 占位提示

3.3 行高（Twenty 风格）

元素 高度 说明
数据行 44px 比传统表格更舒展，便于放置 chip/头像
列头行 40px 略低于数据行，表达层级
行选择列 44px 与数据行对齐
  • 禁止 36px 以下行高，避免 chip/多选标签被截断。
  • 列头与数据行高度不同是刻意设计，但差距必须 ≤ 4px。

4. 视觉层次

4.1 列头必须可识别（Twenty 风格）

  • 背景色使用 --bitable-color-bg-secondary。
  • 列头下边界 1px var(--bitable-color-border-hover)，比行分隔略重即可，禁止 2px 粗线。
  • 列头文字 font-weight: 500，颜色 --bitable-color-text-secondary，表达 muted 层级。
  • 列头必须显示字段类型图标（如文本用 FileText、日期用 Calendar、多选用 Tags），图标颜色 --bitable-color-text-tertiary。
  • 禁止把字段类型图标做成「编辑」样式，避免用户误以为点击图标就是编辑。

4.2 标题区、视图区、表格区的层次（Twenty 风格）

从上到下：

  1. 顶部文件标题栏 — 文件名称 + 返回按钮（最轻）
  2. 对象/视图工具栏 — 左侧「对象图标 + 当前视图下拉 · 记录数徽章」，右侧「+ 新建记录 / 筛选 / 排序 / 选项」
  3. 列头 — 1px 下边界 + 背景色区分
  4. 数据行 — 1px 行分隔 + 1px 列分隔 + hover 高亮
  5. 占位行 — 虚线底边 + hover 高亮

「选项」下拉收纳低频操作（字段管理、刷新、视图配置、删除视图）；「新建视图」统一放在当前视图下拉菜单底部。

5. 新增记录交互

5.1 新增记录入口（Twenty 风格）

  • 主要入口：工具栏右侧放置显眼的「+ 新建记录」主按钮（Twenty 的 + New）。
  • 次要入口：始终在数据列表末尾渲染一行占位行（pseudo-row），点击任意单元格也触发新增。
  • 占位行样式：
    • 虚线底边（border-bottom: 1px dashed）
    • pointer 光标
    • hover 时背景变为 --bitable-color-bg-tertiary

5.2 代码实现要点

  • 占位行的 _rowId 使用固定哨兵值（如 __placeholder__），_recordId 为空字符串。
  • 在 cell-click 事件中优先检测占位行，再处理普通行的其他交互。
  • 只要表格非分组模式，就追加占位行，保证空表也有可点击目标。

6. 暗色/浅色主题

  • 所有颜色必须使用 --bitable-* token，禁止硬编码 hex。
  • 边框颜色在暗色模式下应自动跟随全局 --border-color。
  • 避免使用 box-shadow 创造分隔（在暗色主题下容易发灰、不自然）。

6.1 必须覆盖 vxe-table 默认 CSS 变量

vxe-table 的默认变量是亮色主题值（#fff、#e8eaec 等）。即使全局 data-theme="dark" 已设置，vxe-table 仍需要显式重映射变量，否则会出现白底、淡边框等「刷新后无变化」的现象。

.bitable-grid-scope :deep(.vxe-table) {
  --vxe-ui-layout-background-color: var(--bitable-color-bg);
  --vxe-ui-table-header-background-color: var(--bitable-color-bg-secondary);
  --vxe-ui-table-border-color: var(--bitable-color-border);
  --vxe-ui-font-color: var(--bitable-color-text);
  --vxe-ui-table-row-hover-background-color: var(--bitable-color-bg-tertiary);
  --vxe-ui-table-row-striped-background-color: var(--bitable-color-bg-secondary);
}
  • 在表格根节点 .vxe-table 上重映射，作用域最小。
  • 同时保持 data-vxe-ui-theme 与 data-theme 同步（全局兜底）。
  • 任何新增 vxe-table 实例都必须执行此重映射，禁止依赖 vxe-table 默认主题。

7. 单元格渲染

7.1 select / multiselect 必须渲染为 pill chip

.select-display__chip {
  border-radius: 999px;
  padding: 2px 10px;
  border: 1px solid;
}
  • 禁止使用直角或 4px 小圆角 chip，避免像 antd Tag 而非 CRM 风格。
  • 多选标签之间保留小间距，允许换行，但单元格内最多两行。

7.2 date 字段必须格式化显示

  • 后端存储 ISO-8601，前端显示 YYYY-MM-DD（中文 locale）。
  • 禁止在单元格中直接显示原始时间戳或带 T/Z 的字符串。

7.3 行选择与行打开方式

  • 必须提供 type: 'checkbox' 列作为首列。
  • 行选择不影响单元格编辑或打开详情抽屉；点击复选框只切换选中态。
  • 不再使用单独的行号列（#）；Twenty 风格下首列即复选框，第一数据列是主字段列。
  • 点击主字段列单元格打开记录详情抽屉；其他可编辑列保持单击进入单元格编辑。

8. 检查清单（Code Review 用）

提交/ review bitable grid 相关改动时，逐项确认：

  • 表格高度是否随内容，无强制撑高
  • 父容器是否未使用 flex: 1 拉伸表格
  • 列头与数据单元格是否有竖向分隔线
  • 列头下边界是否为 1px 且比行分隔略重
  • 列头 padding 是否与数据单元格一致
  • 列头是否显示字段类型图标
  • 数据行高是否为 44px、列头行高是否为 40px
  • 是否有行选择复选框列（无 # 行号列）
  • 主字段列点击是否打开记录详情抽屉
  • 最后一列是否无右侧悬浮边界线
  • 字号是否使用 --bitable-font-sm / --bitable-font-md
  • select 字段是否渲染为 pill chip
  • date 字段是否格式化显示
  • 新增记录是否通过末尾占位行实现
  • 颜色是否全部使用 --bitable-* token
  • 是否覆盖 vxe-table 默认 CSS 变量以适配暗色主题
  • 是否未引入无意义的双重/三重水平线