u

code/g3soft-libs/packages/ui/e2e/table.spec.ts

@@ -337,6 +337,40 @@ test.describe('G3Table 行内编辑：无外间距、无常驻边框', () => {
 
     expect(await rowHeights(page, '[data-testid="table-wrap"]')).toEqual(before)
   })
+
+  /**
+   * select 的编辑格底色。
+   *
+   * 回归的 bug：编辑格的白底判据曾经是 `td:focus-within`，而 **G3Select 展开时会把 DOM
+   * 焦点移进 Teleport 到 body 的下拉浮层** —— 那一刻 td 的 `:focus-within` 立刻失效，
+   * 底色退回库的选区色（`--cs-bgc`，浅蓝）。表现是「select 编辑格时白时不白」，
+   * 而 input 没有浮层、永远正常。
+   *
+   * 所以这里必须在**浮层已夺焦**的状态下断言，用别的方式（例如只看点击后一瞬间）
+   * 是测不出来的。判据改为编辑器上的 `is-cell-editing` 类（见 editable.ts）。
+   */
+  test('select 展开（焦点被浮层拿走）后，编辑格仍是基色而不是选区色', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    const cell = await cellByTitle(page, '[data-testid="table-wrap"]', '状态')
+    await cell.click()
+
+    // 前置条件：浮层确实拿到了焦点，且焦点已不在表格里（这正是修前的失效条件）
+    await expect(page.locator('.g3-select__dropdown')).toBeVisible()
+    expect(await page.evaluate(() => !document.activeElement?.closest('.stk-table'))).toBe(true)
+
+    const measured = await cell.evaluate((el) => ({
+      bg: getComputedStyle(el).backgroundColor,
+      marked: !!el.querySelector('.is-cell-editing'),
+    }))
+
+    // 机制在：编辑器带着「当前编辑格」标记（td 侧靠 :has(> …) 命中）
+    expect(measured.marked).toBe(true)
+    // 底色是基色（亮色主题下即 #fff），不是库的选区色 #d3eafd
+    expect(measured.bg).toBe('rgb(255, 255, 255)')
+  })
 })
 
 /**
@@ -349,6 +383,71 @@ test.describe('G3Table 行内编辑：无外间距、无常驻边框', () => {
  *   - table-wrap 绑了 v-model:columns（列宽拖拽的前提，缺了拖不动）
  */
 test.describe('G3Table 校验态 / 列宽拖拽 / 行高亮', () => {
+  test('不可改的格子灰底常驻：整列只读 / 按行禁用，都不需要先点开某行', async ({ page }) => {
+    /**
+     * 判据是「**这一格现在改不了**」，不再是「编辑行里没有编辑器的格子」——
+     * 后者只在被点过的那一行可见，用户仍要一行行点过去才发现某格点不动。
+     *
+     * 两种来源分别锁：整列只读（列上没有 editor，走 td 类名）与按行禁用
+     * （`disabled` 是函数，走内容节点标记）；顺带反向断言可编辑列**不**灰。
+     */
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+    const rows = wrap.locator('.stk-tbody-main tr')
+    const bgOf = (selector: string, rowIndex: number) =>
+      rows.nth(rowIndex).locator(selector).evaluate((el) => getComputedStyle(el).backgroundColor)
+
+    // 「名称」列没有 editor（整列只读）→ 进页面就是灰的
+    expect(await bgOf('td[data-col-key="name"]', 0)).not.toBe('rgba(0, 0, 0, 0)')
+    // 「金额」列有 editor → 不灰
+    expect(await bgOf('td[data-col-key="amount"]', 0)).toBe('rgba(0, 0, 0, 0)')
+
+    // 按行禁用：第 2 行 enabled=0 → 状态列灰；第 1 行不灰
+    expect(await bgOf('td[data-col-key="status"]', 1)).not.toBe('rgba(0, 0, 0, 0)')
+    expect(await bgOf('td[data-col-key="status"]', 0)).toBe('rgba(0, 0, 0, 0)')
+  })
+
+  /**
+   * 灰底的门控：**这张表里得先有人能编辑**，灰底才是信息。
+   *
+   * 灰底的语义是「这一格现在改不了」，它靠「旁边有可改的格子」传达意义。
+   * 一张纯展示表（列上都没有 `editor`）里每格都改不了，若照旧逐格铺灰，
+   * 整张表看上去就是「禁用状态」—— 文档 7 张 demo 里有 6 张是这种纯展示表，
+   * 用户看到的就是「demo 一片灰、像是被禁用了」。
+   *
+   * 两个反例都锁上：
+   *   · `table-plain-wrap`：列上根本没有 `editor`；
+   *   · `table-noedit-wrap`：列上有 `editor`，但 `editable: false` 把编辑整个关掉。
+   * 正向（可编辑表里的只读列**仍然**常驻灰底）由上面那条用例守着，两条一起构成门控。
+   */
+  test('纯展示表 / editable: false：不铺「不可改」灰底', async ({ page }) => {
+    await page.goto('/')
+
+    const greyCount = async (wrapTestId: string) =>
+      page
+        .locator(`[data-testid="${wrapTestId}"]`)
+        .locator('.stk-tbody-main td')
+        .evaluateAll(
+          (tds) =>
+            tds.filter(
+              (td) =>
+                // 整列只读：类名落在 td 上
+                td.classList.contains('g3-table__cell-readonly') ||
+                // 按行禁用：标记落在内容节点上
+                !!td.querySelector('.g3-table__cell-readonly'),
+            ).length,
+        )
+
+    // 纯展示表：一个灰格都不该有
+    expect(await greyCount('table-plain-wrap')).toBe(0)
+    // editable: false：同理（列上声明了 editor 也不算「有人能编辑」）
+    expect(await greyCount('table-noedit-wrap')).toBe(0)
+
+    // 对照：可编辑的 table-wrap 里，没有 editor 的「名称」列仍然有灰底（门控不能把这条改坏）
+    expect(await greyCount('table-wrap')).toBeGreaterThan(0)
+  })
+
   test('校验态全表可见：不点任何行就能看到 error 与 warning', async ({ page }) => {
     await page.goto('/')
     const wrap = page.locator('[data-testid="table-wrap"]')
@@ -381,6 +480,59 @@ test.describe('G3Table 校验态 / 列宽拖拽 / 行高亮', () => {
     await expect(row.locator('td').nth(remarkIdx).locator('.is-editor-warning')).toHaveCount(1)
   })
 
+  /**
+   * 编辑态让位：正在编辑的校验格**不铺校验底色**，底色回到基色。
+   *
+   * 原因（实际录入反馈）：铺着底色时输入区被染色、对比度下降，录入时「看不清」。
+   * 编辑时的校验信号改由**语义色焦点环 + 红字**承载；离开该格后底色回来。
+   *
+   * 判据是编辑器上的 `is-cell-editing` 标记，不是 `:focus-within`：
+   * select 展开时焦点被移进 Teleport 到 body 的浮层，`:focus-within` 会时有时无。
+   *
+   * 顺带锁住「校验格与普通格内边距一致」：右上角的 `!` 角标已**整体去掉**，
+   * 为它让位的 `padding-right: 14px` 也一并删除 —— 录入区不该被缩窄。
+   */
+  test('编辑校验格：底色回到基色；换格后恢复；不再为角标留右边距', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 宿主第 2 行「金额」= 0 → validate 不通过，是这张表里的 error 格
+    const errCell = wrap.locator('.stk-tbody-main tr').nth(1).locator('td[data-col-key="amount"]')
+    const read = () =>
+      errCell.evaluate((el) => ({
+        bg: getComputedStyle(el).backgroundColor,
+        badge: getComputedStyle(el, '::after').content,
+        shadow: getComputedStyle(el).boxShadow,
+      }))
+
+    // ① 未编辑：铺校验底色；角标已去掉（::after 无内容）
+    const idle = await read()
+    expect(idle.bg).not.toBe('rgb(255, 255, 255)')
+    expect(idle.badge).toBe('none')
+
+    // 内边距与同列的普通格一致（没有为角标让位的 14px）
+    const displayPad = (rowIndex: number) =>
+      wrap
+        .locator('.stk-tbody-main tr')
+        .nth(rowIndex)
+        .locator('td[data-col-key="amount"] .g3-table__cell-display')
+        .evaluate((el) => getComputedStyle(el).paddingRight)
+    expect(await displayPad(1)).toBe(await displayPad(0))
+
+    // ② 进入编辑：底色 = 基色（亮色主题即 #fff），只剩语义色焦点环
+    await errCell.click()
+    await expect(wrap.locator('.is-cell-editing')).toHaveCount(1)
+    const editing = await read()
+    expect(editing.bg).toBe('rgb(255, 255, 255)')
+    expect(editing.badge).toBe('none')
+    expect(editing.shadow).toContain('2px')
+
+    // ③ 换到别的格 → 它不再是编辑格，底色回来
+    await wrap.locator('.stk-tbody-main tr').first().locator('td[data-col-key="amount"]').click()
+    await expect.poll(async () => (await read()).bg).not.toBe('rgb(255, 255, 255)')
+  })
+
   test('列宽拖拽：绑定 v-model:columns 后可拖动，宽度真实变化', async ({ page }) => {
     await page.goto('/')
     const wrap = page.locator('[data-testid="table-wrap"]')
@@ -533,3 +685,513 @@ test.describe('G3Table RTL 镜像', () => {
     expect(tableBox!.width).toBeGreaterThan(wrapBox!.width * 0.9)
   })
 })
+
+/**
+ * 固定列 + 校验态的几何契约。
+ *
+ * 历史 bug（值得留在这里，因为它是这类问题的模板）：校验态样式曾给 td 写
+ * `position: relative`（为了让绝对定位的角标有个基准），而固定列的 td 上
+ * `position` 是库在用的 —— 被遮挡时是 `sticky`，且吸附位移以**内联** `left` / `right`
+ * 写在 td 上。改成 relative 之后那条内联 `left` 就变成普通相对位移，整个格子被推开
+ * 「前面所有左固定列宽度之和」：表现是「错误底色跑到了隔壁两列中间」，
+ * 看着完全不像定位问题。
+ *
+ * 角标现在整体去掉了（见 docs 的 errorStyle），那两条 `position` 规则也随之删除 ——
+ * 这个坑从机制上消失。本组用例继续守着「固定列 + 校验底色」的几何：
+ * 校验格必须与它所属列对齐、滚完仍吸附在原位。
+ *
+ * 只能在这里量：happy-dom 没有布局引擎，`:has()` 命中与 sticky 都不成立。
+ * 宿主数据在 playground/main.ts（`table-fixed-wrap`）：左固定两列 + 一行空名称。
+ */
+test.describe('G3Table 固定列 + 校验态', () => {
+  const WRAP = '[data-testid="table-fixed-wrap"]'
+
+  /** 按列标题取表头单元格的几何（固定列的表头与数据格走同一套 sticky） */
+  async function thBox(page: import('@playwright/test').Page, title: string) {
+    const th = page.locator(WRAP).locator('thead th', { hasText: title })
+    await expect(th).toBeVisible()
+    const box = await th.boundingBox()
+    if (!box) throw new Error(`表头「${title}」没有几何信息`)
+    return box
+  }
+
+  /** 按列标题取「第一行」的单元格：列序由调用方决定，不写死 nth-child */
+  async function cellByTitleIn(
+    page: import('@playwright/test').Page,
+    wrapSelector: string,
+    title: string,
+  ) {
+    const wrap = page.locator(wrapSelector)
+    const index = await wrap
+      .locator('thead th')
+      .evaluateAll((ths, t) => ths.findIndex((th) => (th.textContent || '').trim() === t), title)
+    if (index < 0) throw new Error(`找不到列标题「${title}」`)
+    return wrap.locator('.stk-tbody-main tr').first().locator('td').nth(index)
+  }
+
+  /** 滚动到最右，返回实际 scrollLeft（为 0 说明这张表根本没横向溢出，用例失去意义） */
+  async function scrollToEnd(page: import('@playwright/test').Page) {
+    return page.locator(`${WRAP} .stk-table`).evaluate((el) => {
+      el.scrollLeft = el.scrollWidth
+      return el.scrollLeft
+    })
+  }
+
+  test('校验未通过的格子留在本列内，不被固定列偏移推开', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+    await page.locator(`${WRAP} .stk-table`).evaluate((el) => {
+      el.scrollLeft = 0
+    })
+
+    const nameTh = await thBox(page, '名称（校验列）')
+
+    // 第 2 行名称为空 → 固定列上必然有一个 error 格（同页其它表格的校验格不在这个 wrap 内）
+    const errorCell = wrap.locator('td:has(> .is-editor-error)')
+    await expect(errorCell).toHaveCount(1)
+    const cell = await errorCell.boundingBox()
+    expect(cell).not.toBeNull()
+
+    // 起点不许被推右：错误格与它所属列的表头左边缘对齐（1px 容差给亚像素）
+    expect(Math.abs(cell!.x - nameTh.x)).toBeLessThanOrEqual(1)
+    expect(Math.abs(cell!.width - nameTh.width)).toBeLessThanOrEqual(1)
+
+    // 而且必须真的在「前一列」的右边 —— 挡住「整格被推走但恰好没超出容差」的漏网
+    const codeTh = await thBox(page, '编号（左固定）')
+    expect(cell!.x).toBeGreaterThanOrEqual(codeTh.x + codeTh.width - 1)
+  })
+
+  test('受控 activeRowKey：点可编辑格进入编辑，当前行照样高亮', async ({ page }) => {
+    /**
+     * 回归的 bug：受控调用方（fms 那套 `:active-row-key` + `@row-click`）
+     * 点**可编辑格**进编辑时整行不高亮，点只读格却正常。
+     *
+     * 根因在浏览器：点可编辑格会挂载编辑器，把 mousedown 命中的 `.cell-display`
+     * span 换掉，Chromium 因此**不派发 click**，库的 `row-click` 不触发，
+     * 调用方那个唯一写入者永远收不到消息。
+     * 组件侧改为在「激活编辑」这条路径上无条件同步当前行（见 G3Table 注释）。
+     */
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    const rows = wrap.locator('.stk-tbody-main tr')
+    const firstRow = rows.first()
+    await expect(firstRow).not.toHaveClass(/active/)
+
+    // 「名称（校验列）」是这张表里的可编辑列（带 editor），点它进入编辑
+    const editableCell = await cellByTitleIn(page, WRAP, '名称（校验列）')
+    await editableCell.click()
+    await expect(wrap.locator('.g3-table__cell-editor-root.g3-input').first()).toBeVisible()
+
+    // 当前行必须高亮 —— 这正是调用方靠 row-click 拿不到的那次点击
+    await expect(firstRow).toHaveClass(/active/)
+
+    // 只读格那条路径也不能坏（第二行的「编号」列没有 editor）
+    await rows.nth(1).locator('td[data-col-key="code"]').click()
+    await expect(rows.nth(1)).toHaveClass(/active/)
+  })
+
+  test('横向滚动后：左固定列与其中的错误格一起吸附在原位', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    const beforeCode = await thBox(page, '编号（左固定）')
+    const beforeError = await wrap.locator('td:has(> .is-editor-error)').boundingBox()
+    expect(beforeError).not.toBeNull()
+
+    // 前提校验：这张表确实溢出（否则固定列无从谈起，断言会变成「什么都没测」）
+    expect(await scrollToEnd(page)).toBeGreaterThan(100)
+    await page.waitForTimeout(150)
+
+    const afterCode = await thBox(page, '编号（左固定）')
+    const afterError = await wrap.locator('td:has(> .is-editor-error)').boundingBox()
+    expect(afterError).not.toBeNull()
+
+    // 左固定列滚完仍在视口的同一横坐标上（吸附生效）
+    expect(Math.abs(afterCode.x - beforeCode.x)).toBeLessThanOrEqual(1)
+    // 带校验态的那一格同理：校验态样式不许把吸附定位打断
+    expect(Math.abs(afterError!.x - beforeError!.x)).toBeLessThanOrEqual(1)
+  })
+
+  /**
+   * 冻结列的选中态与行状态叠色的关系。
+   *
+   * 回归的 bug：新加的「冻结列行状态叠色」用的是 `box-shadow`，而库的选区描边
+   * （`td[data-cs-s]` 的 4 个方向 inset）**也在 box-shadow 上** —— 单值属性，
+   * 只写叠色那一条就会把选中框整体替换掉。表现是「冻结列上的选中格没有蓝色选中边」，
+   * 非冻结列没有这条规则所以只有冻结列会缺，很容易被当成「选中态没生效」。
+   *
+   * 另一半：编辑格**不参与**行状态叠色（普通列的编辑格是纯基色 + 焦点环），
+   * 否则同一行里冻结列的编辑格会带行色、普通列的却是纯色。
+   */
+  test('冻结列：选中格保留选中描边，编辑格与普通列一样只有焦点环', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    const firstRow = wrap.locator('.stk-tbody-main tr').first()
+    const nameCell = await cellByTitleIn(page, WRAP, '名称（校验列）')
+    await nameCell.click()
+
+    /**
+     * 编辑格：应当只有「一圈 2px 内描边」（焦点环），**不带**行状态的大范围叠色。
+     * 叠色的计算值是 `0px 0px 0px <视口宽>px inset`，形状完全不同 —— 用形状区分，
+     * 不去比颜色（颜色随主题变）。
+     */
+    const editingShadow = await nameCell.evaluate((el) => getComputedStyle(el).boxShadow)
+    expect(editingShadow).toMatch(/0px 0px 0px 2px inset/)
+
+    // 再 Shift+点前面那个只读的左固定格：选区扩成两格，它就是「选中但不在编辑」的格子
+    const codeCell = firstRow.locator('td[data-col-key="code"]')
+    await codeCell.click({ modifiers: ['Shift'] })
+    await page.waitForTimeout(150)
+
+    const measured = await codeCell.evaluate((el) => {
+      // 把 --cs-bc（选区描边色）解析成 rgb：getPropertyValue 给的是原样字符串，比不了
+      const probe = document.createElement('span')
+      probe.style.color = 'var(--cs-bc)'
+      el.appendChild(probe)
+      const borderColor = getComputedStyle(probe).color
+      probe.remove()
+      return {
+        isFixed: el.classList.contains('fixed-cell'),
+        isSelected: el.hasAttribute('data-cs-s'),
+        shadow: getComputedStyle(el).boxShadow,
+        borderColor,
+      }
+    })
+
+    expect(measured.isFixed).toBe(true)
+    expect(measured.isSelected).toBe(true)
+    // 叠色规则里必须连同选区描边一起写，否则这一格上的选中框会被替换掉
+    expect(measured.shadow).toContain(measured.borderColor)
+  })
+})
+
+/**
+ * Tab / Shift+Tab 跳格。
+ *
+ * 只能在这里测：事件源可能是 Teleport 到 body 的 select 浮层（真实 DOM 概念），
+ * happy-dom 既没有 Teleport 的真实 DOM，也没有焦点语义。
+ *
+ * 宿主是 playground 的 `table-wrap` 表（可编辑），列序为
+ * 名称(只读) / 金额(number) / 状态(select，enabled=0 的行禁用) / 启用(checkbox) / 备注(text) / 操作(只读)，
+ * 数据 3 行（第 2 行 enabled=0）。这一组合同时覆盖三条规则：
+ * 跳过只读列、跳过「按行禁用」的列、行尾回绕到下一行。
+ */
+test.describe('G3Table 键盘跳格：Tab / Shift+Tab', () => {
+  const WRAP = '[data-testid="table-wrap"]'
+
+  /**
+   * 焦点当前所在的那一格。
+   *
+   * 不能只读 `document.activeElement.closest('td')`：select 展开时焦点被移进 Teleport 出去的
+   * 浮层里，浮层不属于任何 td。此时用 ARIA 关联（浮层 id ↔ 触发器 aria-controls）把焦点
+   * 还原成「它逻辑上所在的格」——与组件内部判定用的是同一套口径。
+   * 焦点完全不在表格里（例如跑到了页面其它元素上）时返回 null —— 这正是修前会出现的状态。
+   */
+  async function focusedCell(page: import('@playwright/test').Page) {
+    return page.evaluate(() => {
+      const active = document.activeElement as HTMLElement | null
+      if (!active) return null
+      let td = active.closest('td[data-col-key]') as HTMLElement | null
+      if (!td) {
+        const overlay = active.closest('.g3-select__dropdown') as HTMLElement | null
+        const trigger = overlay?.id
+          ? document.querySelector(`[aria-controls="${overlay.id}"]`)
+          : null
+        td = trigger?.closest('td[data-col-key]') ?? null
+      }
+      if (!td) return null
+      return {
+        colKey: td.getAttribute('data-col-key'),
+        // 库给 tr 写了绝对行索引（不受虚拟窗口影响）
+        rowIndex: td.closest('tr')?.getAttribute('data-row-i') ?? null,
+      }
+    })
+  }
+
+  test('焦点在 select 的浮层里按 Tab：落到下一个可编辑格，而不是页面其它元素', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 进入第一行「金额」格编辑（number 编辑器，焦点在原生 input 上）
+    await wrap.locator('td[data-col-key="amount"]').first().click()
+    await expect(wrap.locator('.g3-table__cell-editor-root.g3-input').first()).toBeVisible()
+    expect(await focusedCell(page)).toEqual({ colKey: 'amount', rowIndex: '0' })
+
+    // ① input → Tab：落到相邻的 select 列；G3Select 展开后把焦点移进 Teleport 到 body 的浮层
+    await page.keyboard.press('Tab')
+    await expect(page.locator('.g3-select__dropdown')).toBeVisible()
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'status', rowIndex: '0' })
+
+    /**
+     * ② 关键回归：焦点在浮层里（DOM 上已经不在 `.stk-table` 内）时按 Tab。
+     *
+     * 修前：浮层的 keydown 到不了底座的 Tab 导航（监听器挂在表格容器上），
+     * 浏览器按文档顺序把焦点移出表格 —— 实测落到文档开头的第一个可聚焦元素，
+     * 用户看到的就是「按 Tab 没有选中下一个」。
+     */
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'enabled', rowIndex: '0' })
+
+    // ③ 只读的「操作」列被跳过，行尾回绕到下一行的第一个可编辑格
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '0' })
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'amount', rowIndex: '1' })
+
+    // ④ 第二行 status 是「按行禁用」的（enabled=0）：它连同只读列一起被跳过
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'enabled', rowIndex: '1' })
+  })
+
+  test('Shift+Tab 反向跳格，并在两端循环', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 从第二行「金额」往回：先跨过只读的「操作」列落到上一行「备注」
+    await wrap.locator('td[data-col-key="amount"]').nth(1).click()
+    await expect(wrap.locator('.g3-table__cell-editor-root.g3-input').first()).toBeVisible()
+    expect(await focusedCell(page)).toEqual({ colKey: 'amount', rowIndex: '1' })
+
+    await page.keyboard.press('Shift+Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '0' })
+
+    // 全表第一个可编辑格：「金额」再往回 → 循环到全表最后一格（第三行「备注」）
+    await page.keyboard.press('Shift+Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'enabled', rowIndex: '0' })
+    await page.keyboard.press('Shift+Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'status', rowIndex: '0' })
+    await page.keyboard.press('Shift+Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'amount', rowIndex: '0' })
+    await page.keyboard.press('Shift+Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '2' })
+  })
+
+  /**
+   * 连按 Tab（间隔压在底座的连按防抖窗口内）。
+   *
+   * 回归的 bug：跳格是「改选区 → 激活编辑 → 重挂编辑器 → 新编辑器聚焦」的异步链路，
+   * 其中 100ms 防抖 + 一帧渲染期间焦点没有任何落点（`document.activeElement` 是 body）。
+   * 此时再按 Tab，事件源既不在编辑器也不在浮层 —— 若就此放行，浏览器会把焦点按文档
+   * 顺序送出表格，表现就是「按快一点还是掉出表格」。
+   * 另一半成因是起点取错：编辑态的 `focusCol` 被防抖推迟，连按时会算回同一格（原地不动）。
+   */
+  test('连按 Tab（40ms 间隔）：每下一次前进一格，且不跳出表格', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    await wrap.locator('td[data-col-key="amount"]').first().click()
+    await expect(wrap.locator('.g3-table__cell-editor-root.g3-input').first()).toBeVisible()
+    expect(await focusedCell(page)).toEqual({ colKey: 'amount', rowIndex: '0' })
+
+    for (let i = 0; i < 3; i += 1) {
+      await page.keyboard.press('Tab')
+      await page.waitForTimeout(40)
+    }
+
+    // 三下 = 前进三格：amount → status → enabled → remark（防抖只延后编辑器的重挂，不吞按键）
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '0' })
+    // 焦点仍在表格里（修前会掉到页面其它元素上）
+    expect(
+      await page.evaluate(() => !!document.activeElement?.closest('[data-testid="table-wrap"]')),
+    ).toBe(true)
+  })
+
+  /**
+   * 编辑行被**虚拟滚动**滚出渲染窗口后按 Tab。
+   *
+   * 这条路径与按键速度无关（实测慢速必现），是「Tab 逃出表格」的另一个入口：
+   * 编辑行滚出渲染窗口 → 编辑器被卸载 → 焦点掉到 `body`；此时按 Tab，事件源既不在
+   * 编辑器也不在浮层 → 若判定「不是给我的」放行，浏览器就按文档顺序把焦点送出表格
+   * （实测落到侧边栏菜单上）。而编辑态与选区其实都还在 —— 滚回来就恢复。
+   *
+   * 宿主是 playground 的 `table-big-wrap`（5000 行，纵向虚拟开启，后两列带 editor）。
+   */
+  test('编辑行被虚拟滚动滚出窗口后按 Tab：拉回编辑行并前进一格，而不是逃到页面元素上', async ({
+    page,
+  }) => {
+    const BIG = '[data-testid="table-big-wrap"]'
+    await page.goto('/')
+    const big = page.locator(BIG)
+    await big.scrollIntoViewIfNeeded()
+
+    await big.locator('.stk-tbody-main tr[data-row-i="0"] td[data-col-key="name"]').click()
+    await expect(big.locator('.g3-table__cell-editor-root.g3-input').first()).toBeVisible()
+    expect(await focusedCell(page)).toEqual({ colKey: 'name', rowIndex: '0' })
+
+    // 纵向滚走：编辑行离开渲染窗口 → 编辑器卸载、焦点回到 body
+    await big.locator('.stk-table').evaluate((el) => {
+      el.scrollTop = 3000
+    })
+    await page.waitForTimeout(300)
+    expect(await page.evaluate(() => document.activeElement === document.body)).toBe(true)
+    expect(
+      await page.evaluate(() => !document.querySelector('[data-testid="table-big-wrap"] .is-cell-editing')),
+    ).toBe(true)
+
+    // Tab：必须被接管（修前这里会 preventDefault=false，焦点落到页面其它元素上）
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'value', rowIndex: '0' })
+  })
+
+  /**
+   * 按住 Tab 连续走（keydown autoRepeat），且从**只读列**起步。
+   *
+   * 用户实测 100% 复现的手势：在 ERP 里点「订舱号」（只读、没有编辑器）那一格，
+   * 然后一直按着 Tab 往右走，走到「起运港」时就掉出表格了。
+   *
+   * 成因是两条叠加出来的同一个状态 ——「编辑会话在，但 DOM 里一个编辑器都没有」：
+   *   · 只读列起步：编辑态是 `editing=true` 而 `focusCol=null`，没有任何编辑器被挂载；
+   *   · 底座的**连按 / 长按优化**：处理 repeat 事件时会 `clearActiveEditing()`（把
+   *     `editing` 也置 false），长按期间刻意保持 0 编辑器，等松手再挂回来。
+   * 旧判据只认 `editing === true`，于是从第 3 下起就认为「不是给表格的 Tab」而放行，
+   * 浏览器按文档顺序把焦点送出表格。
+   */
+  test('按住 Tab（autoRepeat）从只读列起步：一格一格前进，不掉出表格', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 「名称」列没有 editor（对应 ERP 的「订舱号」），点它建立编辑会话
+    await wrap.locator('.stk-tbody-main tr').first().locator('td[data-col-key="name"]').click()
+    await expect(wrap.locator('.is-cell-editing')).toHaveCount(0)
+
+    // 按住不放：Playwright 对**已按下**的键会把后续 keydown 标成 autoRepeat，与真实长按一致
+    await page.keyboard.down('Tab')
+    for (let i = 0; i < 3; i += 1) {
+      await page.keyboard.down('Tab')
+      await page.waitForTimeout(250)
+    }
+    // 长按期间底座刻意保持 0 编辑器 —— 这正是「会话在但没编辑器」那个状态
+    expect(await wrap.locator('.is-cell-editing').count()).toBe(0)
+    await page.keyboard.up('Tab')
+
+    // 四下 = 名称(只读) → 金额 → 状态 → 启用 → 备注；松手后编辑器落到最后一格
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '0' })
+    expect(
+      await page.evaluate(() => !!document.activeElement?.closest('[data-testid="table-wrap"]')),
+    ).toBe(true)
+  })
+
+  /**
+   * 复选框与其它单元格**行为一致**：点一下就切换（不需要先激活整行），
+   * 并且这一格随之成为当前格（行高亮 + 选中框 + 编辑会话），键盘也能从这里继续走。
+   *
+   * 回归的 bug：为了「一次点击就切换」，createCheckbox 把 mousedown 停掉了（浏览器在
+   * 节点被替换时不派发 click，不停就会变成「第一次点击只进编辑、第二次才切换」）。
+   * 但停了之后底座收不到 mousedown，也就不会像点击其它格那样设选区、激活该行编辑、
+   * 置当前行 —— 实测后果是：值改了、`change` 也抛了，可整行不高亮、格子没有选中框，
+   * 而且表格里**没有任何选区**，接着按 Tab 会从 (0,0) 起步、焦点掉到 `body`。
+   */
+  test('点复选框：一次点击即切换，且该格成为当前格（键盘可继续走）', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator(WRAP)
+    await wrap.scrollIntoViewIfNeeded()
+    const firstRow = wrap.locator('.stk-tbody-main tr').first()
+    const cell = firstRow.locator('td[data-col-key="enabled"]')
+
+    const before = await cell.locator('input').isChecked()
+    // 点可见的复选框（原生 input 藏在 label 里，由 label 承担命中）
+    await cell.locator('label').click()
+
+    // ① 一次点击就切换（这条是原本就正确的行为，别改坏）
+    expect(await cell.locator('input').isChecked()).toBe(!before)
+
+    // ② 这一格成为当前格：行高亮 + 选中框 + 编辑格标记
+    await expect(firstRow).toHaveClass(/active/)
+    await expect(cell).toHaveAttribute('data-cs-s')
+    expect(await cell.evaluate((el) => !!el.querySelector('.is-cell-editing'))).toBe(true)
+
+    // ③ 于是键盘可以从这里继续走：启用 → 备注（同行下一个可编辑列）
+    await page.keyboard.press('Tab')
+    await expect.poll(() => focusedCell(page)).toEqual({ colKey: 'remark', rowIndex: '0' })
+  })
+})
+
+/**
+ * 斑马纹（`stripe`）与固定列。
+ *
+ * 库把条纹画在 `tr` 上，而冻结列的单元格底色**必须不透明**（否则横向滚动时被压住的
+ * 列会透上来），这层不透明底色会把 `tr` 上的条纹盖住 —— 于是「整表隔行灰、只有序号列没有」。
+ * 组件的做法是在冻结列上补一层**同色内阴影**把条纹接上（见 style/_overrides.scss 的 stripe 段）。
+ *
+ * 所以这里量的是「冻结列单元格上到底有没有那层叠色」，而不是它的 background-color：
+ * 底色必须一直是不透明的 `--td-bgc`（那是冻结列的硬约束），条纹只能是叠上去的。
+ *
+ * 两个宿主覆盖两条 CSS 分支：`table-stripe-wrap`（2 行，纵向虚拟关闭 → `nth-child(even)`）
+ * 与 `table-big-wrap`（5000 行 → `vt-on`，库改取 `nth-child(odd)`）。
+ */
+test.describe('G3Table 斑马纹与固定列', () => {
+  /**
+   * 取某一行**第一个单元格**（固定列/序号列）的底色与叠色情况。
+   *
+   * `boxShadow` 里除了叠色还有库的选区描边（`--cs-bc` 未设时是 transparent），
+   * 所以按「有没有非零 alpha 的颜色」判断，而不是比对整串字符串。
+   */
+  async function fixedCellPaint(
+    page: import('@playwright/test').Page,
+    wrapTestId: string,
+    rowIndex: number,
+  ) {
+    return page
+      .locator(`[data-testid="${wrapTestId}"] .stk-tbody-main tr`)
+      .nth(rowIndex)
+      .locator('td')
+      .first()
+      .evaluate((td) => {
+        const cs = getComputedStyle(td)
+        const alphas = [...cs.boxShadow.matchAll(/rgba?\(([^)]+)\)/g)].map((m) => {
+          const parts = m[1].split(',').map((s) => s.trim())
+          return parts.length === 4 ? Number(parts[3]) : 1
+        })
+        const bg = cs.backgroundColor
+        const bgParts = bg.match(/rgba?\(([^)]+)\)/)
+        const bgAlpha = bgParts
+          ? (() => {
+              const parts = bgParts[1].split(',').map((s) => s.trim())
+              return parts.length === 4 ? Number(parts[3]) : 1
+            })()
+          : 1
+        return { bg, bgAlpha, maxShadowAlpha: Math.max(0, ...alphas), isFixed: td.classList.contains('fixed-cell') }
+      })
+  }
+
+  test('纵向虚拟关闭时（nth-child(even)）：序号列跟着上条纹，底色仍不透明', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-stripe-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+    await expect(wrap.locator('.stk-table')).toHaveClass(/stripe/)
+
+    // 第 2 行是条纹行
+    const striped = await fixedCellPaint(page, 'table-stripe-wrap', 1)
+    // 前提：这真的是固定列（序号列注入时就是 fixed: 'left'）
+    expect(striped.isFixed).toBe(true)
+    // 关键断言：条纹叠色在（修前这里是 0 —— 条纹被不透明底色盖掉了）
+    expect(striped.maxShadowAlpha).toBeGreaterThan(0)
+    // 且底色仍然不透明：横滚不许透字，这是冻结列的硬约束，不能被条纹改掉
+    expect(striped.bgAlpha).toBe(1)
+
+    // 第 1 行不是条纹行：不应有叠色（叠色只在条纹行上出现）
+    expect((await fixedCellPaint(page, 'table-stripe-wrap', 0)).maxShadowAlpha).toBe(0)
+  })
+
+  test('纵向虚拟开启时（vt-on，库改取 nth-child(odd)）：同一条规则要跟着换', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-big-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+    await expect(wrap.locator('.stk-table')).toHaveClass(/vt-on/)
+    await expect(wrap.locator('.stk-table')).toHaveClass(/stripe/)
+
+    // vt-on 下 DOM 首行是 striped（odd）
+    expect((await fixedCellPaint(page, 'table-big-wrap', 0)).maxShadowAlpha).toBeGreaterThan(0)
+    expect((await fixedCellPaint(page, 'table-big-wrap', 1)).maxShadowAlpha).toBe(0)
+  })
+})