@taocompany/magic-grid 0.4.8 → 0.5.2

package/README.md

@@ -21,6 +21,8 @@
 - [Expose](#expose)
 - [Slots](#slots)
 - [单元格编辑](#单元格编辑)
+  - [呈现模式：overlay 与 inline](#呈现模式overlay-与-inline)
+  - [内置编辑器](#内置编辑器)
 - [数据校验](#数据校验)
 - [键盘导航与快捷键](#键盘导航与快捷键)
 - [辅助组件](#辅助组件)
@@ -31,7 +33,6 @@
 - [包入口与导出](#包入口与导出)
 - [TypeScript 集成](#typescript-集成)
 - [类型与校验子路径](#类型与校验子路径)
-- [本地开发与 Playground](#本地开发与-playground)
 
 ---
 
@@ -43,11 +44,11 @@
 |------|------|
 | **性能** | 行/列双轴虚拟化、DOM 池复用、RAF 帧预算分片、Cell Renderer 滚动调度（idle flush · 按行合并 · placeholder-then-vue）、增量数据管线 |
 | **数据** | 排序、列筛选、Quick Filter、事务增量更新（`applyTransaction`）、行 CRUD |
-| **交互** | 单元格/行编辑、校验、行选择、索引列定位、框选与剪贴板 |
+| **交互** | 单元格/行编辑（内置 text/number/checkbox/switch · overlay/inline）、校验、行选择、索引列定位、框选与剪贴板 |
 | **布局** | 固定列、列拖拽/调整宽度、列有效性与显隐（`available` / `hidden`）、合并单元格、动态行高、主从展开行 |
 | **结构** | 行分组、树形表格（含懒加载）、表尾汇总 |
 | **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
-| **扩展** | 列设置面板、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |
+| **扩展** | 列设置面板、内置编辑器（text/number/checkbox/switch）、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |
 
 当前版本：**0.3.0**（`@taocompany/magic-grid`）。
 
@@ -192,7 +193,7 @@ const columns: ColumnDef[] = [
 - 避免在 `cellRenderer` / `formatter` / `valueGetter` 中创建重量级对象或触发外部副作用；这些函数在滚动时会高频调用。
 - 多列使用 `#cell-{colId}` Vue 插槽时，滚停后可能出现 renderer 列空白拖尾；见下方 [Cell Renderer 滚动渲染](#cell-renderer-滚动渲染) 与 [docs/41-cell-renderer-scroll-performance.md](docs/41-cell-renderer-scroll-performance.md)。
 - 合并单元格（`enableCellSpan`）会启用 `style.top` 行定位并增加 span cache 开销，仅在确有需求时开启。
-- Playground 内置 `getMetrics()` 可观察 `activeDomRowCount`、`lastSetDataMs` 等指标；`/phase41` 另提供 `getPendingFrameTaskCount()` / `getPendingRendererTaskCount()`；生产环境可通过 `scroll` / `data-rendered` 事件订阅。
+- 生产环境可通过 `scroll` / `data-rendered` 事件订阅渲染完成时机；开发调试时可关注 DOM 行池规模与 `setData` 耗时。
 
 ### Cell Renderer 滚动渲染
 
@@ -225,7 +226,7 @@ const columns: ColumnDef[] = [
 />
 ```
 
-`placeholder-then-vue` 模式下，slot 列需配置可读 `prop` 或 `formatter`，滚动态才有文字兜底。Playground 验收：**`/phase41`**。完整方案见 [docs/41-cell-renderer-scroll-performance.md](docs/41-cell-renderer-scroll-performance.md)。
+`placeholder-then-vue` 模式下，slot 列需配置可读 `prop` 或 `formatter`，滚动态才有文字兜底。完整方案见 [docs/41-cell-renderer-scroll-performance.md](docs/41-cell-renderer-scroll-performance.md)。
 
 ---
 
@@ -649,6 +650,8 @@ interface RowSelectionConfig {
 | `groupFooterLabel` | `string` | — | groupFooter 首列展示标签 |
 | `groupCellRenderer` | `GroupCellRendererFn` | — | 自定义分组单元格渲染器 |
 
+> **编辑**：启用单元格编辑时，仅 **leaf 数据行**可进入编辑态；`groupHeader` / `groupFooter` **不渲染** inline 或 overlay 编辑器（由 `isCellEditable` + `cellCtrl` 共同保证）。
+
 #### 树形表格
 
 | Prop | 类型 | 默认值 | 说明 |
@@ -837,8 +840,6 @@ api.getColumns().some((c) => c.colId === 'internalCode') // false
 
 修改 `columns` 中某列的 `available` 或 `hidden` 后，Grid 会走 `setColumns` 重解析。`hidden` 在 `columnDefs` 未改 `hidden` 声明时，会保留运行时 API/菜单设置的值（与 Phase 22 列显隐语义一致）。
 
-Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列可切换 `available`）。
-
 #### 尺寸
 
 | 字段 | 类型 | 说明 |
@@ -895,7 +896,9 @@ Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列
 | `formatter` | `(row, value) => string` | 展示格式化 |
 | `cellRenderer` | `CellRendererFn` | 自定义单元格渲染器（函数；Vue 组件通过 `#cell-{colId}` 插槽） |
 | `cellRendererMount` | `'vue' \| 'sync'` | 列级 renderer 挂载类型；配合 `cellRendererDefer: 'sync-only'` 使用 |
-| `cellEditor` | `CellEditorDef` | 自定义单元格编辑器（函数、内置 `text`/`number`/`checkbox`、或命名引用） |
+| `cellEditor` | `CellEditorDef` | 自定义单元格编辑器（函数、内置 `text`/`number`/`checkbox`/`switch`、或命名引用） |
+| `checkboxEditorParams` | `CheckboxEditorParams` | 内置 checkbox：自定义选中/未选中写回值（默认 `true`/`false`） |
+| `switchEditorParams` | `SwitchEditorParams` | 内置 switch：自定义开启/未开启写回值（默认 `true`/`false`） |
 | `cellEditorMode` | `'overlay' \| 'inline'` | 编辑器呈现方式；默认 `overlay` |
 | `valueParser` | `(value, params) => unknown` | 提交前解析编辑值 |
 | `valueSetter` | `(params) => boolean \| Promise<boolean>` | 自定义写回逻辑；返回 `false` 拒绝提交 |
@@ -1342,7 +1345,52 @@ api.clearAllFilters()
 
 ## Events
 
-MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 **kebab-case**。除 Vue 事件外，也可通过 `gridRef.api.on(...)` 订阅 camelCase 内核事件（见 [Expose](#expose)）。
+MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 **kebab-case**。除 Vue 事件外，也可通过 `gridRef.value?.api.on(...)` 订阅 camelCase 内核事件（见 [Expose](#expose)）。
+
+### 生命周期
+
+| Vue 事件 | 内核事件 | 频率 | 说明 |
+|----------|----------|------|------|
+| `@grid-ready` | `gridReady` | 每次 Grid 实例创建 | `initGrid` 完成、`setData` 已调用；`event.api` 可立即使用 |
+| `@grid-destroyed` | `gridDestroyed` | 每次 Grid 实例销毁 | reinit 或组件卸载前；`event.reason` 为 `'reinit'` \| `'unmount'` |
+| `@first-rendered` | `firstRendered` | 每个实例一次 | 该实例首次 RAF 渲染完成；payload 含 `api` 与 `metrics` |
+
+`@data-rendered` 仍表示**每一轮**数据渲染完成（见下节），与 `@first-rendered` 语义分离。
+
+```vue
+<script setup lang="ts">
+import { useGridLifecycle } from '@taocompany/magic-grid'
+
+const lifecycle = useGridLifecycle({
+  onReady: ({ api }) => {
+    api.setSortModel([{ colId: 'name', sort: 'asc' }])
+  },
+  onDestroyed: ({ reason }) => {
+    if (reason === 'reinit') {
+      // 清理旧 api 订阅
+    }
+  },
+  onFirstRendered: ({ api }) => {
+    api.ensureIndexVisible(0, 'top')
+  },
+})
+</script>
+
+<template>
+  <MagicGrid :columns="columns" :data="rows" v-on="lifecycle" />
+</template>
+```
+
+也可直接在模板绑定 `@grid-ready` / `@grid-destroyed` / `@first-rendered`。
+
+内核订阅（payload 与 Vue 事件相同）：
+
+```ts
+function onGridReady({ api }: GridReadyEvent) {
+  const off = api.on('selectionChanged', handler)
+  // 在 @grid-destroyed 或 api.on('gridDestroyed') 里 off()
+}
+```
 
 ### 渲染与滚动
 
@@ -1735,7 +1783,7 @@ payload 为 `RowExpansionChangedEvent`：
 
 | 成员 | 类型 | 说明 |
 |------|------|------|
-| `api` | `Ref<GridApi \| undefined>` | GridApi 实例；挂载完成后可用 |
+| `api` | `GridApi \| undefined` | GridApi 实例；挂载完成后可用 |
 | `getMetrics()` | `() => GridMetrics \| undefined` | 读取渲染与滚动指标（同 `scroll` / `data-rendered` 事件 payload） |
 | `scrollTo(scrollTop, scrollLeft?)` | `(number, number?) => void` | 编程式滚动；scrollLeft 省略时保持当前值 |
 | `setSortModel(model)` | `(SortModelItem[]) => void` | 设置排序模型并重算 display 行 |
@@ -1754,7 +1802,7 @@ payload 为 `RowExpansionChangedEvent`：
 
 ```ts
 interface MagicGridExpose {
-  api: Ref<GridApi | undefined>
+  api: GridApi | undefined
   getMetrics: () => GridMetrics | undefined
   scrollTo: (scrollTop: number, scrollLeft?: number) => void
   setSortModel: (model: SortModelItem[]) => void
@@ -1776,31 +1824,31 @@ interface MagicGridExpose {
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import type { MagicGridExpose } from '@taocompany/magic-grid/types/core'
+import type { GridReadyEvent, MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
 
+function onGridReady({ api }: GridReadyEvent) {
+  api.setSortModel([{ colId: 'name', sort: 'asc' }])
+}
+
 async function addRow() {
   await gridRef.value?.applyTransaction({
     add: [{ id: Date.now(), name: '新行' }],
   })
 }
-
-function exportData() {
-  return gridRef.value?.getData({ sourceOrder: true })
-}
-
-function scrollToRow(index: number) {
-  gridRef.value?.ensureIndexVisible(index, 'middle')
-}
 </script>
 
 <template>
-  <MagicGrid ref="gridRef" ... />
+  <MagicGrid ref="gridRef" @grid-ready="onGridReady" ... />
 </template>
 ```
 
-### GridApi（`gridRef.api`）
+获取 api 的推荐方式见 [Events · 生命周期](#生命周期)。ref 亦可直接调用：`gridRef.value?.api?.getData()`。
+
+在 `computed` / 模板中追踪 api 时，可用 `useGridApi(gridRef)`（等价于 `computed(() => gridRef.value?.api)`）。
+
+### GridApi（`gridRef.value?.api`）
 
 `api` 是完整的命令式 API 面。以下按职责分组列出全部公开方法；入参 rowId 均接受 `string | number`，出参 rowId 恒为 `string`。
 
@@ -1945,6 +1993,9 @@ GridApi 支持 `on(eventType, handler)` 订阅内核事件（camelCase），返
 
 | 内核事件名 | 对应 Vue 事件 |
 |------------|---------------|
+| `gridReady` | `grid-ready` |
+| `gridDestroyed` | `grid-destroyed` |
+| `firstRendered` | `first-rendered` |
 | `selectionChanged` | `selection-changed` |
 | `cellValueChanged` | `cell-value-changed` |
 | `sortChanged` | `sort-changed` |
@@ -2167,17 +2218,18 @@ Magic Grid 支持 **overlay**（点击/Enter 进入编辑浮层）与 **inline**
 | 模式 | 配置 | 行为 |
 |------|------|------|
 | **overlay**（默认） | `cellEditorMode: 'overlay'` 或省略 | 非编辑态展示 formatter / cellRenderer；进入编辑态后在单元格上方挂载编辑器 |
-| **inline** | `cellEditorMode: 'inline'` + 必须配置 `cellEditor` | 编辑器始终渲染在格内；空格切换 checkbox；适合布尔列、简单输入 |
+| **inline** | `cellEditorMode: 'inline'` + 必须配置 `cellEditor` | 编辑器始终渲染在格内；单击单元格或 Space 切换 checkbox/switch；适合布尔列、简单输入 |
 
 **inline 限制**（开发模式会 console.warn）：
 
 - 系统列（索引 / 行选择）不支持 inline。
-- 推荐搭配内置 `'text'` / `'number'` / `'checkbox'`；依赖 teleport/下拉的第三方组件（如 Select）应使用 overlay + `useCellEditor({ strategy: 'overlay' })`。
-- inline 列通过 `params.commit()` / 空格（checkbox）提交；不走 overlay 的 Enter 捕获逻辑。
+- 推荐搭配内置 `'text'` / `'number'` / `'checkbox'` / `'switch'`；依赖 teleport/下拉的第三方组件（如 Select）应使用 overlay + `useCellEditor({ strategy: 'overlay' })`。
+- inline 列通过 `params.commit()` / 单击单元格 / 空格（checkbox/switch）提交；不走 overlay 的 Enter 捕获逻辑。
 
 ```ts
 const columns: ColumnDef[] = [
   { prop: 'done', label: '完成', width: 80, cellEditorMode: 'inline', cellEditor: 'checkbox' },
+  { prop: 'enabled', label: '启用', width: 88, cellEditorMode: 'inline', cellEditor: 'switch' },
   { prop: 'qty', label: '数量', cellEditorMode: 'inline', cellEditor: 'number', editable: true },
 ]
 ```
@@ -2186,13 +2238,298 @@ Grid 级 `editBehavior: 'row'` 时整行同时进入编辑；Tab 在同行可编
 
 ### 内置编辑器
 
-| 名称 | 说明 |
-|------|------|
-| `'text'` | 单行文本 input |
-| `'number'` | `type="number"` input |
-| `'checkbox'` | 布尔 checkbox；inline 模式下空格切换 |
+Magic Grid 提供四种 **零注册** 内置编辑器，列定义中直接引用字符串即可：`cellEditor: 'text' | 'number' | 'checkbox' | 'switch'`。未配置 `cellEditor` 时，overlay 编辑 **默认回退为 `'text'`**。
+
+内置名 **不可** 用于 `registerCellEditor` 覆盖；命名注册表仅用于自定义编辑器。
+
+#### 总览
+
+| 名称 | 控件 | 典型场景 | 推荐 `cellEditorMode` | 默认写回类型 |
+|------|------|----------|----------------------|--------------|
+| `'text'` | `<input type="text">` | 单行文本 | `overlay` | `string` |
+| `'number'` | `<input type="number">` | 数值 | `overlay` 或 `inline` | `number`（空串拒绝提交） |
+| `'checkbox'` | `<input type="checkbox">` | 布尔 / 二元状态 | **`inline`**（也可 `overlay`） | `boolean`（可自定义） |
+| `'switch'` | `<input type="checkbox" role="switch">` | 开关态 | **`inline`**（也可 `overlay`） | `boolean`（可自定义） |
+
+#### 解析优先级
+
+列进入编辑（overlay）或 inline 常驻挂载时，`cellEditor: 'someName'` 按以下顺序解析：
+
+1. **内置名** `'text'` | `'number'` | `'checkbox'` | `'switch'`
+2. **列级函数** `(params, ctx) => HTMLElement`
+3. **Grid 实例级** `cellEditorRegistry` / `cellEditors.byName`
+4. **全局** `registerCellEditor(name)`
+5. 未找到 → `console.warn` + 回退 **`text`** 编辑器
+
+#### `'text'` — 单行文本
+
+| 项 | 说明 |
+|----|------|
+| DOM | `<input type="text" class="mg-cell-editor">` |
+| 初始值 | `params.formattedValue`（经 formatter 格式化后的字符串） |
+| 默认 `valueParser` | 原样返回 raw 字符串 |
+| overlay 提交 | Enter / blur / Tab（Tab 可链式下一 editable 格） |
+| inline | 支持；`change` 或 `params.commit()` 提交；不走 Enter 捕获 |
+
+```ts
+{ prop: 'name', label: '姓名', editable: true, cellEditor: 'text' }
+// 省略 cellEditor 时 overlay 编辑同样使用 text 编辑器
+```
+
+#### `'number'` — 数字输入
+
+| 项 | 说明 |
+|----|------|
+| DOM | `<input type="number" class="mg-cell-editor">` |
+| 初始值 | 单元格值为 `null` / `''` 时显示空串，否则 `String(value)` |
+| 默认 `valueParser` | 去空白后 `Number()`；空串或非有限数 → **拒绝提交** |
+| 自定义解析 | 推荐显式配置 `valueParser`，例如 `(v) => (v === '' ? null : Number(v))` |
+
+```ts
+{
+  prop: 'qty',
+  label: '数量',
+  editable: true,
+  cellEditor: 'number',
+  valueParser: (raw) => {
+    const n = Number(raw)
+    if (!Number.isFinite(n)) throw new Error('请输入有效数字')
+    return n
+  },
+}
+```
+
+#### `'checkbox'` — 复选框
+
+checkbox 适用于二元字段。支持 **overlay**（进入编辑态后显示控件）与 **inline**（控件常驻格内，改值即提交）两种呈现；布尔列 **强烈推荐 inline**。
+
+| 项 | 说明 |
+|----|------|
+| DOM | `<input type="checkbox" class="mg-cell-editor [mg-inline-checkbox]">` |
+| 初始 checked | `coerceCheckboxEditorValue(value, checkboxEditorParams)` |
+| 读值 | `readCheckboxControlValue` → JSON 序列化 raw（默认 `'true'` / `'false'`） |
+| 默认 `valueParser` | `parseCheckboxEditorRawValue` |
+| inline 提交 | 控件 `@change` 即 commit；**单击单元格空白** 同样 toggle + commit |
+| overlay 提交 | 进入编辑态后 change / Enter / blur 走常规 overlay 管线 |
+| 键盘 | 焦点在 inline checkbox 格时 **Space** toggle + commit（不触发行选择） |
+| disabled | `editable: false` 或 `editable(row) => false` → `.mg-cell--inline-disabled` |
+
+**自定义写回值**（`checkboxEditorParams`）：
+
+```ts
+interface CheckboxEditorParams {
+  /** 选中态写回值；默认 `true` */
+  checkedValue?: unknown
+  /** 未选中态写回值；默认 `false` */
+  uncheckedValue?: unknown
+}
+```
+
+| 示例配置 | 写回值 |
+|----------|--------|
+| 默认（省略 params） | `true` / `false` |
+| `{ checkedValue: 1, uncheckedValue: 0 }` | `1` / `0` |
+| `{ checkedValue: 'Y', uncheckedValue: 'N' }` | `'Y'` / `'N'` |
+
+**值 → checked 态映射规则**：
+
+- 单元格值 **严格等于** `checkedValue` → checked
+- 单元格值 **严格等于** `uncheckedValue` → unchecked
+- **未配置自定义值** 时，额外兼容常见 falsy/truthy：`null` / `''` / `false` / `'false'` / `0` / `'0'` → unchecked；`true` / `'true'` / `1` / `'1'` → checked；其余走 `Boolean(value)`
+- **已配置自定义值** 时，仅精确匹配 on/off 值；不匹配则默认为 unchecked
+
+```ts
+const columns: ColumnDef[] = [
+  // inline · 默认 boolean
+  { prop: 'active', label: '启用', width: 72, cellEditorMode: 'inline', cellEditor: 'checkbox' },
+  // inline · 写回 1/0
+  {
+    prop: 'activeFlag',
+    label: '激活',
+    width: 72,
+    cellEditorMode: 'inline',
+    cellEditor: 'checkbox',
+    checkboxEditorParams: { checkedValue: 1, uncheckedValue: 0 },
+  },
+  // overlay · 写回 Y/N
+  {
+    prop: 'confirmed',
+    label: '已确认',
+    width: 88,
+    editable: true,
+    cellEditor: 'checkbox',
+    checkboxEditorParams: { checkedValue: 'Y', uncheckedValue: 'N' },
+  },
+]
+```
+
+#### `'switch'` — 开关
+
+switch 在语义与管线上与 checkbox **共用 toggle 值引擎**，UI 为 pill 形开关（`role="switch"`）。交互、inline/overlay 行为、键盘与 disabled 规则与 checkbox 一致。
+
+| 项 | 说明 |
+|----|------|
+| DOM | `<input type="checkbox" role="switch" class="mg-cell-editor mg-switch-editor [mg-inline-switch]">` |
+| 初始 checked | `coerceSwitchEditorValue(value, switchEditorParams)` |
+| 读值 | `readSwitchControlValue` |
+| 默认 `valueParser` | `parseSwitchEditorRawValue` |
+| 样式类 | `.mg-switch-editor` · `.mg-inline-switch`；尺寸随 `--mg-checkbox-size` token |
+
+**自定义写回值**（`switchEditorParams`）：
+
+```ts
+interface SwitchEditorParams {
+  /** 开启态写回值；默认 `true` */
+  onValue?: unknown
+  /** 未开启态写回值；默认 `false` */
+  offValue?: unknown
+}
+```
+
+```ts
+const columns: ColumnDef[] = [
+  // inline · 默认 boolean
+  { prop: 'enabled', label: '启用', width: 88, cellEditorMode: 'inline', cellEditor: 'switch' },
+  // overlay · 写回 ON/OFF 字符串
+  {
+    prop: 'mode',
+    label: '模式',
+    width: 100,
+    editable: true,
+    cellEditor: 'switch',
+    switchEditorParams: { onValue: 'ON', offValue: 'OFF' },
+  },
+]
+```
+
+#### overlay 与 inline 行为对照
+
+| 维度 | overlay | inline |
+|------|---------|--------|
+| 挂载时机 | 进入编辑会话（单击/双击/Enter/API） | `CellCtrl.refreshCell` 常驻 |
+| DOM 容器 | `.mg-cell-editor-host` | `.mg-cell__inline-editor` |
+| 非编辑态展示 | formatter / cellRenderer | **忽略** cellRenderer，始终显示编辑器 |
+| 编辑会话 | 有（pin 行 · `cellEditingStarted/Stopped`） | **无** |
+| 提交触发 | Enter / blur / Tab / 控件 change | `@change` / 单击单元格 / Space（checkbox/switch） |
+| Tab | 提交并链式下一 editable 格 | 仅移动焦点 |
+| Esc | 取消 draft | 无 draft；committing 期间 Esc 可 abort |
+| 行编辑 `editBehavior: 'row'` | 参与整行编辑 | **排除**（不参与整行编辑器挂载） |
+| 适用编辑器 | 全部内置 + Vue 第三方 | 推荐 `text` / `number` / `checkbox` / `switch` |
+
+> **注意**：inline 模式搭配依赖 teleport/下拉的第三方组件（如 Select、DatePicker）时，开发环境会 `console.warn`；此类列应使用 overlay + `useCellEditor({ strategy: 'overlay' })`。
+
+#### 与行选择列的区别
+
+行选择列（`rowSelection`）与 inline checkbox **UI 相似但职责完全不同**：
+
+| 维度 | 行选择列 `__select__` | inline checkbox / switch 列 |
+|------|----------------------|----------------------------|
+| 状态源 | `SelectionService` | `row.data[prop]` |
+| 事件 | `selectionChanged` | `cellValueChanged` |
+| 管线 | 无 valueParser / valueSetter | 完整编辑管线（校验 · async 写回） |
+| DOM 类名 | `mg-selection-checkbox` | `mg-inline-checkbox` / `mg-inline-switch` |
+| 表头 | 多选时全选 checkbox | 用户自定义 label |
+
+#### 样式与 CSS 变量
+
+内置 checkbox / switch 尺寸与主题色可通过 CSS 变量覆盖（需已引入 `style.css`）：
+
+| Token | 默认值 | 作用 |
+|-------|--------|------|
+| `--mg-checkbox-size` | `14px` | checkbox 边长；switch 宽高按比例推导 |
+| `--mg-color-primary` | 主题主色 | checkbox `accent-color` · switch 开启态背景 |
+| `--mg-color-border` | 边框色 | switch 关闭态背景 |
+
+相关类名：`.mg-cell--inline-editor` · `.mg-cell--inline-disabled` · `.mg-cell--committing`（async 提交中）。
+
+#### 完整示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { MagicGrid } from '@taocompany/magic-grid'
+import type { ColumnDef, RowData } from '@taocompany/magic-grid/types/core'
+import '@taocompany/magic-grid/style.css'
+
+interface ProductRow extends RowData {
+  name: string
+  qty: number | null
+  active: boolean
+  activeFlag: number
+  confirmed: string
+  enabled: boolean
+  mode: string
+}
+
+const data = ref<ProductRow[]>([
+  { id: 1, name: '商品 A', qty: 10, active: true, activeFlag: 1, confirmed: 'Y', enabled: true, mode: 'ON' },
+  { id: 2, name: '商品 B', qty: null, active: false, activeFlag: 0, confirmed: 'N', enabled: false, mode: 'OFF' },
+])
+
+const columns: ColumnDef[] = [
+  { prop: 'name', label: '名称', width: 140, editable: true, cellEditor: 'text' },
+  { prop: 'qty', label: '库存', width: 88, cellEditorMode: 'inline', cellEditor: 'number', editable: true },
+  { prop: 'active', label: '上架', width: 72, cellEditorMode: 'inline', cellEditor: 'checkbox' },
+  {
+    prop: 'activeFlag',
+    label: '标记',
+    width: 72,
+    cellEditorMode: 'inline',
+    cellEditor: 'checkbox',
+    checkboxEditorParams: { checkedValue: 1, uncheckedValue: 0 },
+  },
+  {
+    prop: 'confirmed',
+    label: '确认',
+    width: 80,
+    editable: true,
+    cellEditor: 'checkbox',
+    checkboxEditorParams: { checkedValue: 'Y', uncheckedValue: 'N' },
+  },
+  { prop: 'enabled', label: '启用', width: 88, cellEditorMode: 'inline', cellEditor: 'switch' },
+  {
+    prop: 'mode',
+    label: '模式',
+    width: 100,
+    editable: true,
+    cellEditor: 'switch',
+    switchEditorParams: { onValue: 'ON', offValue: 'OFF' },
+  },
+]
 
-列定义引用：`cellEditor: 'text'`。内置名不可用于 `registerCellEditor` 覆盖。
+function onCellValueChanged(event: { colId: string; rowId: string | number; oldValue: unknown; newValue: unknown }) {
+  console.log(`${event.colId}: ${String(event.oldValue)} → ${String(event.newValue)}`)
+}
+</script>
+
+<template>
+  <MagicGrid
+    :columns="columns"
+    :data="data"
+    row-key="id"
+    height="360"
+    @cell-value-changed="onCellValueChanged"
+  />
+</template>
+```
+
+#### 提交管线（内置编辑器共用）
+
+无论 overlay 还是 inline，提交均走统一管线：
+
+```
+控件读值 (getValue / readCheckboxControlValue / readSwitchControlValue)
+  → valueParser（列级优先；内置编辑器有默认 parser）
+  → cellValidator / validationRules
+  → valueSetter（支持 async · signal · cancelCommit）
+  → applyTransaction 写回 row.data
+  → cellValueChanged
+```
+
+- **校验失败** 或 **valueSetter 返回 false**：按 `invalidEditValueMode`（`keep` / `revert` / `block`）处理；inline checkbox/switch 会 **revert 控件 checked 态**。
+- **async valueSetter**：提交期间单元格加 `.mg-cell--committing`，控件 disabled；Esc 可 `cancelCommit()` abort。
+
+更深入的 inline 架构说明见 [docs/24-phase13-inline-cell-editor.md](docs/24-phase13-inline-cell-editor.md)。
 
 ### Vue 自定义编辑器
 
@@ -2247,7 +2584,9 @@ const columns: ColumnDef[] = [
 ]
 ```
 
-`CellEditorParams` 主要字段：`value`、`data`、`stopEditing(commit?)`、`validate()`、`cancelCommit()`、`setGetValue`、`setKeyboardPolicy`、`inline`、`commit`（inline 模式）。
+`CellEditorParams` 主要字段：`value`、`data`、`size`（Grid 尺寸 preset）、`stopEditing(commit?)`、`validate()`、`cancelCommit()`、`setGetValue`、`setKeyboardPolicy`、`inline`、`commit`（inline 模式）。
+
+第三方 UI 库的控件尺寸由消费端自行映射 `params.size` 或使用 Grid CSS 变量（如 `--mg-row-height`、`--mg-font-size`），框架不提供映射 helper。
 
 ### 命名编辑器注册表
 
@@ -2347,7 +2686,7 @@ api.clearValidation()
 | `Ctrl/Cmd` + 方向键 | 跳转到首/末行或导航序首/末列 |
 | `Tab` / `Shift+Tab` | 下一 / 上一可聚焦格（表头 ↔ 表体可衔接，`navigateHeader` / `navigateFooter` 控制） |
 | `Enter` | 表头：排序 / 全选；索引列：定位；树/分组：展开折叠；数据格：进入编辑 |
-| `Space` | 行选择 checkbox；inline checkbox 切换；表头/索引/树/分组同 Enter 的切换逻辑 |
+| `Space` | 行选择 checkbox；inline checkbox/switch 切换；表头/索引/树/分组同 Enter 的切换逻辑 |
 | `F2` | 进入编辑（若列可编辑） |
 | `Shift+F2` | 新建/打开单元格批注（批注功能启用时） |
 
@@ -2715,7 +3054,7 @@ import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid/types/co
 **单元格编辑器**
 
 - `useCellEditor`、`VueCellEditorHost`、`createVueCellEditor`、`createSlotCellEditor`
-- `textCellEditor`、`numberCellEditor`、`checkboxCellEditor`（内置实现，高级场景）
+- `textCellEditor`、`numberCellEditor`、`checkboxCellEditor`、`switchCellEditor`（内置实现，高级场景）
 - `registerCellEditor` / `unregisterCellEditor` / `getCellEditor` / `hasCellEditor` / `getRegisteredCellEditorNames`
 - `BUILTIN_CELL_EDITOR_NAMES`、`isBuiltInCellEditor`
 - `DEFAULT_CELL_EDITOR_MODE`、`resolveCellEditorMode`、`isInlineEditorColumn`
@@ -2761,15 +3100,16 @@ import type { MagicGridProps } from '@taocompany/magic-grid/types/core'
 ### 组件 ref 类型
 
 ```ts
-import type { MagicGridExpose, GridApi } from '@taocompany/magic-grid/types/core'
+import type { MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
-const api = computed(() => gridRef.value?.api) // Ref<GridApi | undefined>
+// 命令式：gridRef.value?.api?.getData()
+// 初始化：@grid-ready="({ api }) => ..."
 ```
 
 ### 事件 payload
 
-事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出，例如 `CellValueChangedEvent`、`SelectionChangedEvent`、`FilterModel`、`SortModelItem`。
+事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出，例如 `GridReadyEvent`、`CellValueChangedEvent`、`FilterModel`。
 
 ### 严格模式建议
 
@@ -2861,48 +3201,6 @@ import {
 
 ---
 
-
-## 本地开发与 Playground
-
-### 环境
-
-```bash
-pnpm install
-pnpm dev          # 启动 Playground（默认 Vite dev server）
-pnpm build        # 构建 npm 包至 dist/
-pnpm test:run     # 单元测试
-pnpm typecheck    # Vue + TS 类型检查
-```
-
-要求 Node.js >= 20.19，包管理器推荐 pnpm 11.x。
-
-### Playground 路由
-
-开发服务器按 Phase 组织演示页，便于逐项验收能力：
-
-| 路由 | 主题 |
-|------|------|
-| `/phase2` – `/phase27` | 各 Phase 功能演示与验收用例 |
-| `/phase41` | Cell Renderer 滚动性能（5000 行 × 多 `#cell-xxx` · pending 指标 · 调参） |
-| `/glossary` | 术语表 |
-
-典型入口：`pnpm dev` 后访问控制台输出的本地 URL，从侧边栏切换 Phase。例如列显隐验收 **`/phase22`**（T14–T15 · `available` 列切换）；多 Vue slot 列滚停拖尾验收 **`/phase41`**。
-
-Playground 源码位于仓库 `playground/` 目录；自定义 Vue 编辑器示例见 `playground/components/editors/`（Element Plus 集成参考）。
-
-### 构建产物
-
-`pnpm build` 输出：
-
-- `dist/index.es.js` / `dist/index.cjs.js` — 主包
-- `dist/types/*.js` — 类型子路径运行时垫片
-- `dist/style.css` — 样式
-- `dist/*.d.ts` — 类型声明（api-extractor rollup）
-
-发布前会自动执行 `prepublishOnly` → `pnpm run build`。
-
----
-
 ## License
 
 MIT © [songjiuzhang](mailto:jiuzhang.song@taoandcompany02.com)