# Bitable 多维表格 UI/UX 规范

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

## 1. 布局原则

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

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

```css
/* 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`，避免剩余空间被表格占据。

```css
/* 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`）。

```css
.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` 必须一致。
- 所有单元格使用相同的垂直对齐方式（默认居中或居顶，但不能混用）。

```css
.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 仍需要显式重映射变量，否则会出现白底、淡边框等「刷新后无变化」的现象。

```css
.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

```css
.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 变量以适配暗色主题
- [ ] 是否未引入无意义的双重/三重水平线