xiaodao-spreader 0.1.28 → 0.1.29

package/README.ZH.md

@@ -32,6 +32,7 @@
 - **智能数据识别** — 输入 `100%`、`1,234`、`¥1,234.56` 等带符号数字文本时自动识别为数值并套用对应格式；常见日期时间文本自动识别为日期，与 Excel 输入语义一致
 - **排序与排序提醒** — 工具栏与右键菜单按单元格**展示内容**对所有类型（数值 / 日期 / 文本）排序；排序只移动数据、不搬运样式；含合并单元格或公式的区域自动禁用排序；当选区外存在相邻数据时，弹出类 Excel 的「排序提醒」对话框，可选择「扩展选定区域」或「仅对选定区域排序」
 - **查找与替换** — 工具栏查找按钮或 `Ctrl/Cmd+F`（含 `Ctrl/Cmd+H`）打开；支持「当前工作表 / 整个工作簿 / 当前选区」三种范围，区分大小写、匹配整个单元格；高亮全部匹配并定位当前项、循环查找；单次与全部替换均接入撤销/重做，仅修改单元格原始 `value`（始终保持字符串），不改动格式 / 边框 / 合并
+- **自动填充（填充柄）** — 类 Excel 的活动选区右下角填充柄，按住向上/下/左/右拖拽即可填充单元格：单值复制、数字/日期/文本数字自动续序列（如 `1,2 → 3,4,5`）、公式引用按相对/绝对/混合规则平移（如 `=A1*2 → =A2*2`）、源 `styleId` 经样式池复用。拖拽期间实时预览、边缘自动滚动、动态扩展工作表、冻结窗格兼容、单次拖拽仅产生一个撤销步骤——*见 [自动填充](#自动填充)*
 
 ### 交互体验
 
@@ -236,6 +237,7 @@ src/
             ├── border-resolve.ts    # 公共边冲突解析（resolveSharedBorder）
             ├── formula.ts           # 公式引擎（解析、计算、依赖、缓存）
             ├── find-replace-core.ts # 查找替换纯算法（零 Vue 依赖，可单测）
+            ├── autofill.ts          # 自动填充纯引擎（模式推断、填充柄逻辑，零 Vue 依赖）
             ├── number-format.ts     # 数字格式引擎（Excel 风格显示格式化）
             ├── theme.ts             # 主题 CSS 变量构建
             └── utils.ts             # 纯工具函数（列标签、命中测试、尺寸解析）
@@ -361,6 +363,75 @@ src/
 
 ---
 
+## 自动填充
+
+一套类 Excel 的填充柄机制（`spreader/core/autofill.ts` 纯引擎 + `composables/interactions.ts` 画布/交互层）。拖动活动选区右下角的小方块即可填充单元格——无 DOM 句柄，全部在 Canvas 上绘制。
+
+### 填充模式
+
+| 源值 | 填充行为 | 示例 |
+|------|----------|------|
+| 单个数字 | 复制 | `42 → 42, 42, 42` |
+| 单个文本 | 复制 | `foo → foo, foo, foo` |
+| 单个日期 | +1 天 | `2026-01-01 → 2026-01-02, 2026-01-03` |
+| 两个及以上数字，等差 | 线性序列 | `1,2 → 3,4,5` · `2,4 → 6,8,10` |
+| 两个及以上日期，等差 | 日期序列 | `2026-01-01, 2026-01-03 → 2026-01-05, 2026-01-07` |
+| 文本 + 数字，prefix 相同 | 文本数字序列 | `Item1,Item2 → Item3,Item4` |
+| 两个单字母 | 字母序列 | `A,B → C,D,E` |
+| 公式 | 引用平移 | `=A1*2 → =A2*2, =A3*2` |
+| 多列 / 多行整块 | 按列独立推断模式 | `A1:B2=[[1,10],[2,20]] → [[3,30],[4,40]]` |
+
+### 公式引用规则
+
+填充柄平移复用既有 `shiftFormulaRefs()`——未新建第二套公式引擎：
+
+| 引用类型 | 语法 | 填充行为 |
+|----------|------|----------|
+| 相对引用 | `=A1` | 行列随目标单元格偏移 |
+| 绝对引用 | `=$A$1` | 保持不变 |
+| 混合引用（列绝对） | `=$A1` | 行调整，列锁定 |
+| 混合引用（行绝对） | `=A$1` | 列调整，行锁定 |
+| 复合引用 | `=B1*$F$1` | `B1` 调整，`$F$1` 锁定 |
+
+### 交互
+
+- **填充柄**：活动选区右下角 6px 方块，主题主色；当选区与合并单元格部分相交时变灰（禁用填充）。
+- **命中测试**：独立 `isFillHandleHit()` 在 resize 句柄之后、单元格点击之前判断；悬停显示 `crosshair` 光标。
+- **状态机**：独立 `autofilling` 状态阻止选区拖拽 / 编辑器 / resize 启动；ESC 中途取消。
+- **实时预览**：拖拽期间目标区域以半透明虚线矩形显示；源选区保持不变；`mouseup` 前不修改任何单元格数据。
+- **边缘自动滚动**：拖到距视口边缘 30px 内时启动单一 `requestAnimationFrame` 循环滚动并更新目标区域；`mouseup` / ESC / pointercancel 即停止。
+- **动态扩展**：填充超出当前 `rowCount`/`colCount` 时先触发 `ensureCapacity()`，折叠进同一撤销步骤。
+- **填充后选区**：选区更新为源 + 目标的并集。
+- **冻结窗格**：所有坐标统一走 `cellToScreenRect` / `screenToCell`，填充柄、命中测试、预览、最终填充在冻结与主体区域均正确。
+- **合并兼容**：部分相交的合并禁用填充柄（第一版保守策略）；整块合并可正确填充。
+- **触摸**：与鼠标共用同一 `autoFillState` 与 `applyAutoFill` 路径——无独立实现。
+
+### 架构
+
+```
+填充柄 UI (drawFillHandle)
+       ↓
+统一命中测试 (isFillHandleHit)
+       ↓
+AutoFill 拖拽状态 (autoFillState)
+       ↓
+目标区域计算 (computeTargetRange)
+       ↓
+纯 AutoFill 模式引擎 (core/autofill.ts)
+       ↓
+公式平移 (shiftFormulaRefs)
+       ↓
+样式 / 边框 / 单元格写入 (applyAutoFill)
+       ↓
+撤销快照 (saveUndo，每次拖拽仅一步)
+       ↓
+scheduleRender()
+```
+
+纯引擎（`core/autofill.ts`）零 Vue/Canvas 依赖，`test/autofill.test.ts` 中有 54 个用例完整单测覆盖，便于复用到 `Ctrl+D`/`Ctrl+R`、粘贴填充、右键填充、API 自动填充等场景。
+
+---
+
 ## 边框系统
 
 一套独立的边框存储与渲染机制（`spreader/core/border-pool.ts` + `border-resolve.ts`）。
@@ -463,10 +534,10 @@ pnpm build:demo
 ### 近期
 
 - [x] 更多公式：`COUNT`、`IF`、`VLOOKUP`、`CONCATENATE`
-- [ ] 单元格背景颜色选择器
+- [x] 单元格背景颜色选择器
 - [x] 数字格式（货币、百分比、日期、小数位数）—— *见 [数字格式](#数字格式)*
 - [ ] 条件格式规则
-- [ ] 自动填充拖拽手柄
+- [x] 自动填充拖拽手柄 —— *见 [自动填充](#自动填充)*
 - [x] 查找与替换 —— *见 [查找与替换](#查找与替换)*
 
 ### 中期

package/README.md

@@ -31,6 +31,7 @@ A high-performance, canvas-based spreadsheet component for Vue 3 — bringing an
 - **Smart Data Recognition** — Typing `100%`, `1,234`, `¥1,234.56` auto-converts the text to a number and applies the matching format; common date/time text auto-converts to dates — matching Excel input behavior
 - **Sorting & Sort Warning** — Sort any column by its **displayed content** (numbers / dates / text); sorting moves data only, never cell styles; ranges containing merged cells or formulas are auto-disabled; when adjacent data sits outside the selection, an Excel-style **Sort Warning** dialog lets you choose "Expand the selection" or "Sort the current selection only"
 - **Find & Replace** — Open via the toolbar find button or `Ctrl/Cmd+F` (also `Ctrl/Cmd+H`); three scopes — current sheet / entire workbook / current selection; match case and match entire cell; highlights all matches and locates the active one with wrap-around navigation; single and replace-all both integrate with undo/redo, mutating only the raw `value` (always kept a string), never format / border / merge
+- **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)*
 
 ### Interaction
 - **Smart Selection** — Click, drag, Shift+Click, row/column header select, corner-cell select-all
@@ -233,6 +234,7 @@ src/
             ├── border-resolve.ts    # Shared-border conflict resolution (resolveSharedBorder)
             ├── formula.ts           # Formula engine (parse, evaluate, deps, cache)
             ├── find-replace-core.ts # Find/replace pure algorithms (zero Vue deps, unit-testable)
+            ├── autofill.ts          # Auto-fill pure engine (pattern inference, fill handle logic, zero Vue deps)
             ├── number-format.ts     # Number format engine (Excel-style display formatting)
             ├── theme.ts             # Theme CSS variable construction
             └── utils.ts             # Pure utilities (col label, hit test, resolve size)
@@ -358,6 +360,75 @@ An Excel-style number formatting engine (`spreader/core/number-format.ts`) that
 
 ---
 
+## Auto Fill
+
+An Excel-style fill-handle mechanism (`spreader/core/autofill.ts` pure engine + `composables/interactions.ts` canvas/interaction layer). Drag the small square at the bottom-right corner of the active selection to fill cells — no DOM handles, all drawn on Canvas.
+
+### Fill Patterns
+
+| Source values | Fill behavior | Example |
+|---------------|---------------|---------|
+| Single number | Copy | `42 → 42, 42, 42` |
+| Single text | Copy | `foo → foo, foo, foo` |
+| Single date | +1 day | `2026-01-01 → 2026-01-02, 2026-01-03` |
+| Two+ numbers, constant diff | Linear series | `1,2 → 3,4,5` · `2,4 → 6,8,10` |
+| Two+ dates, constant diff | Date series | `2026-01-01, 2026-01-03 → 2026-01-05, 2026-01-07` |
+| Text + number, same prefix | Text-number series | `Item1,Item2 → Item3,Item4` |
+| Two single letters | Alpha series | `A,B → C,D,E` |
+| Formula | Reference translation | `=A1*2` → `=A2*2, =A3*2` |
+| Multi-column / multi-row block | Per-column pattern inference | `A1:B2=[[1,10],[2,20]] → [[3,30],[4,40]]` |
+
+### Formula Reference Rules
+
+Fill-handle translation reuses the existing `shiftFormulaRefs()` — no second formula engine:
+
+| Reference type | Syntax | Fill behavior |
+|----------------|--------|---------------|
+| Relative | `=A1` | Row/col offset with the target cell |
+| Absolute | `=$A$1` | Stays unchanged |
+| Mixed (col absolute) | `=$A1` | Row adjusts, column locked |
+| Mixed (row absolute) | `=A$1` | Column adjusts, row locked |
+| Composite | `=B1*$F$1` | `B1` adjusts, `$F$1` locked |
+
+### Interaction
+
+- **Fill handle**: 6px square at the selection's bottom-right corner, theme primary color; turns grey when the selection partially intersects a merge (fill disabled).
+- **Hit-test**: independent `isFillHandleHit()` runs after resize handles and before cell click; hover shows `crosshair` cursor.
+- **State machine**: a dedicated `autofilling` state prevents selection drag / editor / resize from starting; ESC cancels mid-drag.
+- **Live preview**: the target range renders as a semi-transparent dashed rectangle during drag; the source selection stays put; no cell data is mutated until `mouseup`.
+- **Edge auto-scroll**: dragging within 30px of the viewport edge starts a single `requestAnimationFrame` loop that scrolls and updates the target range; stopped on `mouseup` / ESC / pointercancel.
+- **Dynamic expansion**: fills beyond the current `rowCount`/`colCount` trigger `ensureCapacity()` first, folded into the same undo step.
+- **Selection after fill**: the selection updates to the union of source + target range.
+- **Freeze panes**: all coordinates flow through `cellToScreenRect` / `screenToCell`, so the handle, hit-test, preview, and final fill work across frozen and body regions alike.
+- **Merge compatibility**: partially intersecting merges disable the fill handle (conservative first version); whole-block merges fill correctly.
+- **Touch**: shares the same `autoFillState` and `applyAutoFill` path as mouse — no separate implementation.
+
+### Architecture
+
+```
+Fill Handle UI (drawFillHandle)
+       ↓
+Unified Hit-Test (isFillHandleHit)
+       ↓
+AutoFill Drag State (autoFillState)
+       ↓
+Target Range Calculation (computeTargetRange)
+       ↓
+Pure AutoFill Pattern Engine (core/autofill.ts)
+       ↓
+Formula Translation (shiftFormulaRefs)
+       ↓
+Style / Border / Cell Mutation (applyAutoFill)
+       ↓
+Undo Snapshot (saveUndo, one step per drag)
+       ↓
+scheduleRender()
+```
+
+The pure engine (`core/autofill.ts`) has zero Vue/Canvas dependencies and is fully unit-tested in `test/autofill.test.ts` (54 cases), making it reusable for `Ctrl+D`/`Ctrl+R`, paste-fill, right-click fill, and programmatic auto-fill.
+
+---
+
 ## Border System
 
 A dedicated border storage & rendering mechanism (`spreader/core/border-pool.ts` + `border-resolve.ts`).
@@ -460,10 +531,10 @@ The project includes a GitHub Actions workflow (`.github/workflows/publish.yml`)
 ### Near-term
 
 - [x] More formulas: `COUNT`, `IF`, `VLOOKUP`, `CONCATENATE`
-- [ ] Cell background color picker
+- [x] Cell background color picker
 - [x] Number format (currency, percentage, date, number of decimals) — *see [Number Format](#number-format)*
 - [ ] Conditional formatting rules
-- [ ] Auto-fill drag handle
+- [x] Auto-fill drag handle — *see [Auto Fill](#auto-fill)*
 - [x] Find & Replace — *see [Find & Replace](#find--replace)*
 
 ### Mid-term

package/dist/types/components/spreader/composables/core-state.d.ts

@@ -8,6 +8,14 @@ import type { CellCoord, CellData, CellStyle, SelectionRange, BorderStyle, Borde
  *  - 'all' ：左上角全选按钮 → expandSelectionForMerges 行为
  */
 export type SelectionMode = 'cell' | 'row' | 'col' | 'all';
+/** AutoFill 拖拽状态 */
+export interface AutoFillState {
+    active: boolean;
+    sourceRange: SelectionRange | null;
+    targetRange: SelectionRange | null;
+    direction: 'up' | 'down' | 'left' | 'right' | null;
+    preview: boolean;
+}
 export interface CoreState {
     props: {
         rowCount: number;
@@ -156,6 +164,10 @@ export interface CoreState {
     clampScroll?: (sx: number | null, sy: number | null) => void;
     /** 查找高亮钩子：返回某单元格当前的高亮类型（由 find-replace 模块注入） */
     findHighlight?: (col: number, row: number) => 'active' | 'match' | null;
+    /** AutoFill 拖拽状态：active 时 render 绘制预览，mouseup 触发 applyAutoFill */
+    autoFillState: Ref<AutoFillState>;
+    /** 一次性提交 AutoFill：saveUndo → ensureCapacity → applyAutoFillPlan → 写入 cells + formulaDeps → selectRange → scheduleRender */
+    applyAutoFill: (sourceRange: SelectionRange, targetRange: SelectionRange, direction: 'up' | 'down' | 'left' | 'right') => void;
 }
 export declare function createCoreState(rawProps: {
     rowCount?: number;

package/dist/types/components/spreader/core/autofill.d.ts

@@ -0,0 +1,125 @@
+import type { CellCoord, SelectionRange } from './types';
+export type FillValue = {
+    kind: 'number';
+    num: number;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'text-number';
+    prefix: string;
+    num: number;
+    digits: number;
+} | {
+    kind: 'date';
+    serial: number;
+} | {
+    kind: 'formula';
+    formula: string;
+};
+export type FillPattern = {
+    kind: 'copy';
+    sourceValues: FillValue[];
+} | {
+    kind: 'linear';
+    step: number;
+    base: number;
+    sourceLen: number;
+} | {
+    kind: 'text-number';
+    prefix: string;
+    step: number;
+    base: number;
+    digits: number;
+    sourceLen: number;
+} | {
+    kind: 'date-linear';
+    step: number;
+    baseSerial: number;
+    sourceLen: number;
+} | {
+    kind: 'text-series';
+    step: number;
+    baseCharCode: number;
+    sourceLen: number;
+} | {
+    kind: 'formula';
+};
+export interface AutofillSheetLike {
+    cells: Record<string, {
+        value: string;
+        styleId?: number;
+    }>;
+    styles: ReadonlyArray<unknown>;
+}
+export interface FillResult {
+    cells: Record<string, {
+        value: string;
+        styleId?: number;
+    }>;
+    merges: Record<string, {
+        startCol: number;
+        startRow: number;
+        endCol: number;
+        endRow: number;
+    }>;
+}
+/**
+ * 将单元格原始值解析为 FillValue。
+ * 优先级：公式 → 日期 → 文本+数字 → 纯数字 → 纯文本。
+ */
+export declare function parseFillValue(value: string, locale: string): FillValue;
+/**
+ * 由源值序列推断填充模式。
+ * - 任一公式 → formula
+ * - 全为日期 → date-linear
+ * - 全为纯数字：单值 copy；多值等差 linear；非等差 copy
+ * - 全为文本+数字且 prefix 相同：单值 copy；多值等差 text-number；否则 copy
+ * - 全为单字符 ASCII 字母且 charCode 等差 → text-series
+ * - 其余 → copy
+ */
+export declare function inferFillPattern(sourceValues: FillValue[]): FillPattern;
+/**
+ * 生成目标区域第 index 个（0-based，相对目标起点、靠近源的一端）的填充值（正向：下/右）。
+ * 目标第 index 个的逻辑索引为 sourceLen + index。
+ */
+export declare function generateFillValue(pattern: FillPattern, index: number, sourceLen: number): FillValue;
+/**
+ * 将 FillValue 转为单元格数据（value + 透传源 styleId）。
+ * 日期存序列号字符串，渲染时由 numberFormat 格式化。
+ */
+export declare function fillValueToCellData(fv: FillValue, sourceStyleId?: number): {
+    value: string;
+    styleId?: number;
+};
+/**
+ * 根据源选区与拖拽目标格计算目标区域及方向。
+ * 落在源内返回 null。
+ */
+export declare function computeTargetRange(sourceRange: SelectionRange, draggedCell: CellCoord): {
+    targetRange: SelectionRange;
+    direction: 'up' | 'down' | 'left' | 'right';
+} | null;
+/**
+ * 平移公式引用以适配目标单元格（$ 绝对引用由 shiftFormulaRefs 处理）。
+ */
+export declare function translateFormulaForTarget(sourceFormula: string, sourceCell: CellCoord, targetCell: CellCoord, colCount: number, rowCount: number, colToLabelFn: (col: number) => string): string;
+/**
+ * 校验源/目标区域与已有合并的兼容性：
+ * - 源区域不能与任何 merge 部分相交（要么完全包含，要么不相交）；
+ * - 目标区域不能与任何已有 merge 相交（会破坏 merge）。
+ */
+export declare function validateMergeCompatibility(sourceRange: SelectionRange, targetRange: SelectionRange, merges: Record<string, SelectionRange>): boolean;
+/**
+ * 自动填充核心：根据源/目标区域与方向生成填充增量（纯函数，不 mutate sheet）。
+ * - down/right：正向延伸；up/left：反向延伸。
+ * - 公式按源位置循环并平移引用；其余按模式生成。
+ * - merges 暂返回空对象（merge 复制由后续任务决定）。
+ */
+export declare function applyAutoFillPlan(sourceRange: SelectionRange, targetRange: SelectionRange, sheet: {
+    cells: Record<string, {
+        value: string;
+        styleId?: number;
+    }>;
+    styles?: ReadonlyArray<unknown>;
+}, direction: 'up' | 'down' | 'left' | 'right', locale: string, colCount: number, rowCount: number, colToLabelFn: (col: number) => string): FillResult;

package/dist/types/components/spreader/core/constants.d.ts

@@ -10,6 +10,8 @@ export declare const MAX_ROW_HEIGHT = 500;
 export declare const SB_SIZE = 11;
 export declare const ARROW_SIZE = 11;
 export declare const SCROLL_STEP = 50;
+export declare const FILL_HANDLE_SIZE = 6;
+export declare const FILL_HANDLE_HIT_PADDING = 4;
 export declare const UNDO_MAX = 50;
 export declare const i18n: Record<string, Record<string, string>>;
 export declare function t(locale: string, key: string): string;

package/dist/types/components/spreader/core/number-format.d.ts

@@ -62,6 +62,7 @@ export interface NFOption {
 export declare function parseNumberFormat(format: string): NFParsed;
 /** 清空解析缓存（主要用于测试/资源释放） */
 export declare function clearNumberFormatCache(): void;
+export declare function serialToDate(serial: number): Date;
 /**
  * 将单元格原始字符串值按格式代码格式化为显示文本。
  * 绝不修改传入的 value。
@@ -134,6 +135,11 @@ export interface DateTimeParseResult {
     serial: number;
     format: string;
 }
+/**
+ * 日期 → Excel 1900 系统序列号（与 serialToDate 互逆）。
+ * 1900-01-01 ~ 02-28 区间减 1，对齐 Excel 的 1900 虚构闰年（1900-02-29 = 60）。
+ */
+export declare function dateToSerial(y: number, m: number, d: number): number;
 /**
  * 对常规单元格的输入做常见日期/时间/日期时间字符串自动识别（对齐 Excel 输入语义）：
  * - 日期：yyyy-m-d、yyyy/m/d、yyyy年m月d日、m-d / m/d（年份补当前年）