xiaodao-spreader 0.1.44 → 0.1.46

package/README.ZH.md

@@ -38,6 +38,7 @@
 - **行列分组与折叠**: 类 Excel 的行/列分组（Outline）。选中整行或整列后，工具栏「分组」下拉（位于排序与筛选之间）提供添加分组 / 取消分组 / 清除分组 / 全部展开 / 全部折叠，直接作用于选中轴；行/列右键菜单提供同构的「分组」子菜单。仅支持一层、互不相交的分组，嵌套或部分重叠会被校验拒绝并提示。分组区间在行号/列号带用交替背景色区分，± 折叠按钮浮动于表头带内，不占用独立 gutter。折叠的行/列不参与内容绘制；插入/删除行列时分组范围自动平移、被清空的分组自动删除。分组状态按工作表持久化（`rowOutlines` / `columnOutlines`），增删与折叠均接入撤销/重做。*见 [行列分组与折叠](#行列分组与折叠)*
 - **单元格批注**: 类 Excel 的单元格批注（Note/Comment）。右键菜单新建 / 编辑 / 删除；单元格右上角红色三角指示器标识含批注；hover 悬停查看、点按编辑；批注独立于单元格值与样式，采用 Note Pool 存储（Sheet 级 notes 池 + cell.noteId 引用），便于排序 / 插入删除时随 cell 一起移动。批注支持多行文本、可选作者、创建 / 修改时间。可通过 `noteAuthor` prop 设置当前作者名。*见 [单元格批注](#单元格批注)*
 - **自动填充（填充柄）**: 类 Excel 的活动选区右下角填充柄，按住向上/下/左/右拖拽即可填充单元格：单值复制、数字/日期/文本数字自动续序列（如 `1,2 → 3,4,5`）、公式引用按相对/绝对/混合规则平移（如 `=A1*2 → =A2*2`）、源 `styleId` 经样式池复用。拖拽期间实时预览、边缘自动滚动、动态扩展工作表、冻结窗格兼容、单次拖拽仅产生一个撤销步骤，*见 [自动填充](#自动填充)*
+- **只读模式**: `editable` prop（默认 `true`）一键切换：`false` 时禁止一切数据/格式修改（编辑、粘贴剪切、删除、填充、行列增删调整、排序筛选、CF/DV/批注、合并边框、冻结、格式刷、替换等），只读下编辑类控件（toolbar、右键菜单、对话框确认/插入按钮、公式栏、查找替换栏）真实禁用，保留选中、滚动、复制、查找定位与查看能力。分层守卫纵深防御（UI disabled → 事件闸门 → handler → 底层 mutation），运行时切换立即生效且不污染 undo 历史，*见 [只读模式](#只读模式read-only)*
 
 ### 交互体验
 
@@ -145,9 +146,38 @@ const myData = ref<SheetModelData[]>([
 | `theme` | `'light' \| 'dark'` | `'light'` | 主题模式 |
 | `locale` | `string` | `'zh-CN'` | 语言: `'zh-CN'` \| `'en-US'` |
 | `noteAuthor` | `string` | `''`（空串，显示时回退为 i18n 占位符「未命名」） | 当前批注作者名；为空时存入批注的 author 字段为空字符串，显示时回退为 i18n 占位符 |
+| `editable` | `boolean` | `true` | 是否允许编辑；`false` 进入只读模式（详见 [只读模式](#只读模式read-only)） |
 
 ---
 
+## 只读模式（Read-only）
+
+通过 `editable` prop 可将组件切换为只读展示（默认 `true`，即完全可编辑）。`editable={false}` 时：
+
+- **禁止一切修改**：单元格编辑与直接输入、粘贴 / 剪切 / 删除、填充柄、行 / 列增删与宽高调整、排序与筛选、条件格式、数据验证、批注增删改、合并单元格、边框、字体 / 对齐 / 背景 / 文字颜色、数字格式、格式刷、冻结窗格、查找替换、撤销 / 重做均被拦截。
+- **保留查看能力**：选中与多选区、滚动、冻结查看、复制、单元格内容 / 格式 / 批注查看、查找定位（上一条 / 下一条）不受影响。
+- **UI 与逻辑一致**：所有编辑类控件（toolbar 按钮与下拉、右键菜单项、对话框确认 / 插入按钮、公式栏按钮、查找替换栏按钮与「替换为」输入框）在只读下真实禁用或只读；切到只读的瞬间，已打开的编辑浮层与对话框自动关闭，不会出现「按钮看起来能点、点了没反应」。
+- **纵深防御**：守卫分四层——① UI `:disabled` / readonly（体验层）→ ② toolbar emit 闸门与事件拦截 → ③ 处理函数首行守卫 → ④ 底层 mutation 守卫（终极防线）。仅靠 DevTools 删除 HTML 的 `disabled` 属性无法绕过，数据不可能被改写；只读下不产生任何 undo 快照，undo 历史不被污染。
+- **运行时切换即时生效**，无需重挂组件；`v-model` 数据与格式不被改动，切回可编辑后一切如常。
+
+```vue
+<template>
+  <button @click="editable = !editable">
+    {{ editable ? '切换为只读' : '切换为可编辑' }}
+  </button>
+  <Spreader v-model:data="myData" :editable="editable" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import Spreader from 'xiaodao-spreader';
+import type { SheetModelData } from 'xiaodao-spreader';
+
+const myData = ref<SheetModelData[]>([]);
+const editable = ref(true);
+</script>
+```
+
 ## 数据模型
 
 ### `SheetModelData`
@@ -220,6 +250,7 @@ src/
 └── components/
     └── spreader/
         ├── index.ts                  # 统一导出口: 组件 + 类型（barrel）
+        ├── theme.css                 # 全局主题样式表：--sp-* 变量（.spreadsheet-outer / .sp-spreader-overlay 作用域，light + dark 两套）
         ├── components/
         │   ├── spreader.vue         # 入口组件：模板 + 样式 + 组合
         │   ├── toolbar.vue          # 工具栏（带溢出下拉）
@@ -251,7 +282,7 @@ src/
         │   ├── core-state.ts          # Props、cells/merges/selection、字体度量、导航、行列分组状态
         │   ├── find-replace.ts        # 查找/替换状态与交互（依赖 Vue）
         │   ├── interactions.ts        # 渲染器、公式栏、标签栏、右键菜单、滚动条、事件
-        │   ├── sheets-ops.ts          # 行列操作、多 Sheet、v-model emit、主题、refs
+        │   ├── sheets-ops.ts          # 行列操作、多 Sheet、v-model emit、refs
         │   ├── undo-styles.ts         # 撤销/重做、格式刷、字体/对齐/颜色
         │   └── float-menu-position.ts # 工具栏下拉菜单共享定位（右锚 + 上下翻向夹紧）
         └── core/
@@ -274,7 +305,7 @@ src/
             ├── sort-core.ts              # 排序纯算法（零 Vue 依赖，可单测）
             ├── sort-icon.ts              # 排序图标单一数据源（toolbar + picker）
             ├── style-pool.ts             # 样式池：去重、注册、解析、迁移、GC
-            ├── theme.ts                  # 主题 CSS 变量构建
+            ├── theme.ts                  # 主题类型与 light/dark 配色（canvas 用）；buildOuterStyle 仅剩尺寸
             ├── types.ts                  # 全部类型定义
             └── utils.ts                  # 纯工具函数（列标转换、命中测试等）
 ```
@@ -701,30 +732,51 @@ const lightTheme: ThemeColors = { /* 50+ 颜色字段 */ };
 const darkTheme: ThemeColors = { /* 50+ 颜色字段 */ };
 ```
 
-### CSS 变量注入
+### 主题变量（`--sp-*`）与作用域
 
-主题颜色通过 CSS 自定义属性（`--sp-*`）注入：
+主题颜色通过 CSS 自定义属性（`--sp-*`）注入，集中声明在组件样式表 `theme.css`：
 
 ```css
 --sp-bg, --sp-gridBg, --sp-gridLine, --sp-selectionBg,
 --sp-headerBg, --sp-headerBorder, --sp-headerText,
 --sp-formulaBarBg, --sp-formulaBarInputBorder,
 --sp-wrapperBg, --sp-cellEditorBorder,
-/* ... 以及更多 */
+/* ... 以及更多（新增变量须同时提供 light 与 dark 两套取值） */
+```
+
+变量作用域收敛在组件子树内，不污染宿主页面：
+
+- **light**：定义于 `.spreadsheet-outer, .sp-spreader-overlay`
+- **dark**：定义于 `.spreadsheet-outer.dark, .sp-spreader-overlay.dark`，`theme="dark"` 时组件根与各 Teleport 浮层根自动挂 `.dark` 类，绝不读写 `<html>` 的全局类
+
+由于下拉 / 对话框 / 右键菜单等浮层经 Teleport 挂到 `<body>` 下（脱离组件 DOM 树，无法从组件祖先继承变量），样式表将同一套变量同时声明在 `.spreadsheet-outer`（组件主体）与 `.sp-spreader-overlay`（浮层根）两个作用域。**消费方必须引入样式表**，否则所有组件样式（含浮层）都取不到主题变量：
+
+```ts
+import 'xiaodao-spreader/style.css';
 ```
 
+另注：Canvas 内部绘制的网格 / 表头 / 选区配色不依赖 CSS 变量，而是由 `ThemeColors`（`lightTheme` / `darkTheme`）按 `theme` prop 直接选取。
+
 ### 自定义主题
 
-传入 `theme="dark"` 启用暗色模式，或通过包装组件覆盖 CSS 变量实现完全自定义：
+传入 `theme="dark"` 启用暗色模式，或覆盖 `--sp-*` 变量实现完全自定义。变量挂在 `.spreadsheet-outer` 作用域上，覆盖主体时可用包装组件（后代级联），但要连同浮层一起覆盖则需同时写 `.sp-spreader-overlay`（浮层脱离组件树、不从包装组件继承），也可直接用 `theme.css` 同优先级规则覆盖：
 
 ```vue
 <template>
   <div style="--sp-bg: #1a1a2e; --sp-cellText: #e0e0e0;">
-    <Spreader v-model:data="myData" theme="dark" />
+    <Spreader v-model:data="myData" />
   </div>
 </template>
 ```
 
+```css
+/* 覆盖 Teleport 浮层（下拉/对话框/右键菜单）时须用该选择器，仅覆盖组件根不够 */
+.sp-spreader-overlay {
+  --sp-bg: #1a1a2e;
+  --sp-cellText: #e0e0e0;
+}
+```
+
 ### 国际化
 
 内置语言：`'zh-CN'`、`'en-US'`。通过 `locale` 属性传入。右键菜单和工具栏标签自动本地化。
@@ -809,6 +861,7 @@ x-spreader 以触屏为第一交互：每个鼠标操作都有对称的触屏路
 - [x] 自动筛选（AutoFilter）：工具栏「筛选」/`Ctrl+Shift+L` 启用，表头下箭头、智能向下探测数据区、值/文本/数值/日期多类型筛选、清除单列与整体移除分离；见 [自动筛选（AutoFilter）](#自动筛选autofilter)
 - [x] 触屏与移动端交互：选择 / 右键菜单 / 筛选 / 列宽行高 / 框选 / 格式刷 / tab 菜单均补齐对称触屏路径，浮层支持点外部关闭；见 [触屏与移动端交互](#触屏与移动端交互)
 - [x] 单元格批注：Note Pool 存储、右键菜单 CRUD、hover 查看、编辑浮层、持久化与撤销；见 [单元格批注](#单元格批注)
+- [x] 只读模式：`editable` prop 分层守卫，UI 与逻辑双重收口；见 [只读模式](#只读模式read-only)
 - [ ] 打印布局
 
 ### 远期

package/README.md

@@ -37,6 +37,7 @@ A high-performance, canvas-based spreadsheet component for Vue 3: bringing an Ex
 - **Cell Notes**: Excel-style cell notes (comments). Right-click menu to create / edit / delete; red triangle indicator at cell corner marks cells with notes; hover to preview, click to edit. Notes are independent from cell values and styles, stored via a Note Pool (Sheet-level notes pool + cell.noteId reference), so sort / insert-delete moves cells together with their notes. Notes support multi-line text, optional author, and create/update timestamps. Author name can be set via the noteAuthor prop. *see [Cell Notes](#cell-notes)*
 - **Auto Fill (Fill Handle)**: Excel-style fill handle at the bottom-right corner of the active selection. Drag it up/down/left/right to fill cells: single values copy, number/date/text-number sequences auto-continue (e.g. `1,2 → 3,4,5`), formula references adjust per relative/absolute/mixed rules (e.g. `=A1*2` → `=A2*2`), and source `styleId` is reused via the style pool. Live preview during drag, edge auto-scroll, dynamic sheet expansion, freeze-pane compatibility, and a single undo step per operation: *see [Auto Fill](#auto-fill)*
 - **Row / Column Grouping & Collapsing**: Excel-style row/column outlines. Select whole rows or columns, then the toolbar "Group" dropdown (between Sort and Filter) offers Add Group / Ungroup / Clear Outline / Expand All / Collapse All, applied directly to the selected axis; row/column context menus expose a matching "Group" submenu. Only one level of non-overlapping groups is supported - nesting and partial overlap are rejected with a message. Group ranges get alternating background colors in the row/column header band; ± collapse buttons float inside the header band without reserving a separate gutter. Collapsed rows/columns are skipped during content rendering; inserting/deleting rows or columns shifts group ranges and auto-removes emptied groups. Groups persist per-sheet (`rowOutlines` / `columnOutlines`) through v-model, and every mutation integrates with undo/redo. *see [Row / Column Grouping & Collapsing](#row--column-grouping--collapsing)*
+- **Read-only Mode**: the `editable` prop (default `true`) toggles between full editing and a read-only view. With `editable={false}` every data / format mutation is blocked (editing, paste/cut/delete, fill, row/column insert & resize, sort/filter, CF/DV/notes, merge/borders, freeze panes, format painter, find & replace), all editing controls (toolbar, context menus, dialog confirm/insert buttons, formula bar, find & replace bar) are truly disabled, while selection, scrolling, copying, find-locate and viewing stay available. Guarding is layered (UI disabled → event gate → handler guard → underlying mutation guard) as defense in depth, runtime toggling takes effect immediately and never pollutes the undo history: *see [Read-only Mode](#read-only-mode)*
 
 ### Interaction
 - **Smart Selection**: Click, drag, Shift+Click, row/column header select, corner-cell select-all
@@ -142,9 +143,38 @@ const myData = ref<SheetModelData[]>([
 | `theme` | `'light' \| 'dark'` | `'light'` | Theme mode |
 | `locale` | `string` | `'zh-CN'` | Language: `'zh-CN'` \| `'en-US'` |
 | `noteAuthor` | `string` | `''` | Current note author name; when empty, saved notes have empty author field that renders as i18n placeholder |
+| `editable` | `boolean` | `true` | Whether editing is allowed; `false` enters read-only mode (see [Read-only Mode](#read-only-mode)) |
 
 ---
 
+## Read-only Mode
+
+Pass the `editable` prop to switch the component into a read-only view (default `true`, i.e. fully editable). With `editable={false}`:
+
+- **Every mutation is blocked**: cell editing and direct typing, paste / cut / delete, the fill handle, row / column insert & resize, sorting & filtering, conditional formatting, data validation, note add/edit/delete, merge cells, borders, font / alignment / fill / text color, number format, format painter, freeze panes, find & replace, and undo / redo.
+- **Viewing stays available**: selection & multi-range selection, scrolling, frozen-pane viewing, copying, inspecting cell content / format / notes, and find navigation (previous / next) are unaffected.
+- **UI stays consistent with logic**: every editing control (toolbar buttons & dropdowns, context-menu items, dialog confirm / insert buttons, formula-bar buttons, find & replace buttons and the "replace with" input) is truly disabled or read-only; the moment read-only is switched on, any open editing overlay or dialog closes automatically - no more "buttons look clickable but do nothing".
+- **Defense in depth**: four guard layers - ① UI `:disabled` / readonly (UX) → ② toolbar emit gate & event interception → ③ guard at the top of each handler → ④ underlying mutation guards (last line of defense). Removing the HTML `disabled` attribute via DevTools cannot bypass the guards, so the data can never be rewritten; read-only never pushes undo snapshots, so the undo history stays unpolluted.
+- **Runtime toggling takes effect immediately** without remounting; the `v-model` data and formatting are untouched and editing works as usual after switching back.
+
+```vue
+<template>
+  <button @click="editable = !editable">
+    {{ editable ? 'Switch to read-only' : 'Switch to editable' }}
+  </button>
+  <Spreader v-model:data="myData" :editable="editable" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import Spreader from 'xiaodao-spreader';
+import type { SheetModelData } from 'xiaodao-spreader';
+
+const myData = ref<SheetModelData[]>([]);
+const editable = ref(true);
+</script>
+```
+
 ## Data Model
 
 ### `SheetModelData`
@@ -218,6 +248,7 @@ src/
 └── components/
     └── spreader/
         ├── index.ts                  # Unified export: component + types (barrel)
+        ├── theme.css                 # Global theme stylesheet: --sp-* variables (.spreadsheet-outer / .sp-spreader-overlay scope, light + dark pairs)
         ├── components/
         │   ├── spreader.vue         # Entry component: template + style + composition
         │   ├── toolbar.vue          # Toolbar with overflow dropdown
@@ -249,7 +280,7 @@ src/
         │   ├── core-state.ts          # Props, cells/merges/selection, font metrics, navigation, outline state
         │   ├── find-replace.ts        # Find/replace state & interaction (Vue-dependent)
         │   ├── interactions.ts        # Renderer, formula bar, tab bar, context menu, scrollbar, events
-        │   ├── sheets-ops.ts          # Row/col ops, multi-sheet, v-model emit, theme, refs
+        │   ├── sheets-ops.ts          # Row/col ops, multi-sheet, v-model emit, refs
         │   ├── undo-styles.ts         # Undo/redo, format painter, font/alignment/color
         │   └── float-menu-position.ts # Shared toolbar dropdown positioning (right-anchor + flip/clamp)
         └── core/
@@ -272,7 +303,7 @@ src/
             ├── sort-core.ts              # Sort pure algorithms (zero Vue deps, unit-testable)
             ├── sort-icon.ts              # Sort icon single source (toolbar + picker)
             ├── style-pool.ts             # Style pool: dedup, registration, resolve, migration, GC
-            ├── theme.ts                  # Theme CSS variable construction
+            ├── theme.ts                  # Theme types + light/dark palettes (for Canvas); buildOuterStyle now returns size only
             ├── types.ts                  # All type definitions
             └── utils.ts                  # Pure utilities (column label, hit test, resolve size)
 ```
@@ -697,30 +728,51 @@ const lightTheme: ThemeColors = { /* 50+ color fields */ };
 const darkTheme: ThemeColors = { /* 50+ color fields */ };
 ```
 
-### CSS Variable Injection
+### Theme Variables (`--sp-*`) and Scope
 
-Theme colors are injected via CSS custom properties (`--sp-*`):
+Theme colors are injected via CSS custom properties (`--sp-*`), declared centrally in the component stylesheet `theme.css`:
 
 ```css
 --sp-bg, --sp-gridBg, --sp-gridLine, --sp-selectionBg,
 --sp-headerBg, --sp-headerBorder, --sp-headerText,
 --sp-formulaBarBg, --sp-formulaBarInputBorder,
 --sp-wrapperBg, --sp-cellEditorBorder,
-/* ... and many more */
+/* ... and many more (new variables must ship both light and dark values) */
+```
+
+Variable scope is confined to the component subtree so the host page is never polluted:
+
+- **light**: declared on `.spreadsheet-outer, .sp-spreader-overlay`
+- **dark**: declared on `.spreadsheet-outer.dark, .sp-spreader-overlay.dark`; when `theme="dark"` the component root and every teleported overlay root get a `.dark` class automatically - `<html>` globals are never touched
+
+Because dropdowns / dialogs / context menus are teleported to `<body>` (outside the component DOM tree, so they cannot inherit variables from component ancestors), the stylesheet declares the same variable set on both `.spreadsheet-outer` (component body) and `.sp-spreader-overlay` (overlay roots). **Consumers must import the stylesheet**, otherwise every component style (including overlays) loses its theme variables:
+
+```ts
+import 'xiaodao-spreader/style.css';
 ```
 
+Note: colors painted on the Canvas (grid, headers, selection) do not depend on CSS variables; they come from `ThemeColors` (`lightTheme` / `darkTheme`) picked by the `theme` prop.
+
 ### Custom Theme
 
-Pass `theme="dark"` for dark mode, or create a wrapper component that overrides CSS variables for full customization:
+Pass `theme="dark"` for dark mode, or override `--sp-*` variables for full customization. The variables live on the `.spreadsheet-outer` scope, so a wrapper component can override the component body via descendant inheritance, but to cover teleported overlays as well you must also target `.sp-spreader-overlay` (overlays leave the component tree and do not inherit from the wrapper):
 
 ```vue
 <template>
   <div style="--sp-bg: #1a1a2e; --sp-cellText: #e0e0e0;">
-    <Spreader v-model:data="myData" theme="dark" />
+    <Spreader v-model:data="myData" />
   </div>
 </template>
 ```
 
+```css
+/* Needed to restyle teleported overlays (dropdowns/dialogs/context menus); overriding only the component root is not enough */
+.sp-spreader-overlay {
+  --sp-bg: #1a1a2e;
+  --sp-cellText: #e0e0e0;
+}
+```
+
 ### Internationalization
 
 Built-in languages: `'zh-CN'`, `'en-US'`. Pass via `locale` prop. Right-click menus and toolbar labels are automatically localized.
@@ -805,6 +857,7 @@ x-spreader is touch-first: every mouse interaction has a symmetric touch path, v
 - [x] Auto Filter (AutoFilter): toolbar "Filter" / `Ctrl+Shift+L` to enable, header drop-down arrows, intelligent downward data probing, value/text/number/date multi-type filters, separate clear-column vs remove-all; see [Auto Filter (AutoFilter)](#auto-filter-autofilter)
 - [x] Touch & mobile interaction: symmetric touch paths for select / context menu / filter / resize / range select / format brush / tab menu; popups close on outside tap; see [Touch & Mobile Interaction](#touch--mobile-interaction)
 - [x] Cell comments / notes: Note Pool storage, context-menu CRUD, hover preview, edit overlay, persistence & undo; see [Cell Notes](#cell-notes)
+- [x] Read-only Mode: `editable` prop with layered guards, UI and logic both covered; see [Read-only Mode](#read-only-mode)
 - [ ] Print layout
 
 ### Long-term