feat(编辑器): 优化表格单元格选区处理与工具栏功能

- 提取表格可视单元格位置计算逻辑至 blockOperations 工具函数
- 增强表格工具栏支持按行/列方向精确插入（前/后插入）
- 新增表格选区边界计算函数，支持跨度单元格的准确定位
- 优化单元格合并/拆分操作，完整支持跨度单元格的结构变更
- 改进工具栏按钮状态验证，区分有效单元格与合并单元格
- 完善表格交互反馈，支持多向度单元格操作与实时视觉反馈

src/components/Editor/blocks/TableBlock.tsx

@@ -11,6 +11,7 @@ import { TableCell } from './TableCell';
 import { TableToolbar } from './TableToolbar';
 import { TableResizeHandle } from './TableResizeHandle';
 import { useTableResize } from '../../../hooks/useTableResize';
+import { getTableVisualCellPositions } from '../../../utils/blockOperations';
 import './TableBlock.css';
 
 // ══════════════════════════════════════════════════════════════════════════════
@@ -29,46 +30,8 @@ interface VisualCellPosition {
   colEnd: number;
 }
 
-type VisualCellPositions = Map<string, VisualCellPosition>;
-
 const getCellKey = (rowIndex: number, colIndex: number) => `${rowIndex}-${colIndex}`;
 
-const buildVisualCellPositions = (rows: TableBlockType['content']['rows']): VisualCellPositions => {
-  const occupied: boolean[][] = [];
-  const positions: VisualCellPositions = new Map();
-
-  rows.forEach((row, rowIndex) => {
-    if (!occupied[rowIndex]) occupied[rowIndex] = [];
-    let visualCol = 0;
-
-    row.cells.forEach((cell, colIndex) => {
-      if (cell.rowspan === 0 || cell.colspan === 0) return;
-
-      while (occupied[rowIndex][visualCol]) visualCol += 1;
-
-      const rowSpan = Math.max(cell.rowspan || 1, 1);
-      const colSpan = Math.max(cell.colspan || 1, 1);
-      const position = {
-        rowStart: rowIndex,
-        rowEnd: rowIndex + rowSpan - 1,
-        colStart: visualCol,
-        colEnd: visualCol + colSpan - 1,
-      };
-      positions.set(getCellKey(rowIndex, colIndex), position);
-
-      for (let occupiedRow = rowIndex; occupiedRow <= position.rowEnd; occupiedRow += 1) {
-        if (!occupied[occupiedRow]) occupied[occupiedRow] = [];
-        for (let occupiedCol = position.colStart; occupiedCol <= position.colEnd; occupiedCol += 1) {
-          occupied[occupiedRow][occupiedCol] = true;
-        }
-      }
-      visualCol = position.colEnd + 1;
-    });
-  });
-
-  return positions;
-};
-
 /**
  * TableBlock - 表格块(完整实现)
  */
@@ -94,7 +57,7 @@ export const TableBlock: React.FC<TableBlockProps> = ({
   const isSelectingRef = useRef(false);
   const didDragSelectRef = useRef(false);
   const [isSelecting, setIsSelecting] = useState(false);
-  const visualCellPositions = buildVisualCellPositions(block.content.rows);
+  const visualCellPositions = getTableVisualCellPositions(block);
 
   // ══════════════════════════════════════════════════════════════════════════════
   // 使用表格调整大小Hook
@@ -383,6 +346,7 @@ export const TableBlock: React.FC<TableBlockProps> = ({
           block={block}
           selectedCell={selectedCell}
           selectedRange={selectedRange}
+          selectedVisualRange={selectedVisualRange}
           onClose={() => {
             setSelectedCell(null);
             setSelectedRange(null);

src/components/Editor/blocks/TableToolbar.tsx

@@ -7,8 +7,11 @@
 import React, { useCallback } from 'react';
 import { Button, Space, Divider, message, Popconfirm } from 'antd';
 import {
-  PlusOutlined,
   MinusOutlined,
+  ArrowUpOutlined,
+  ArrowDownOutlined,
+  ArrowLeftOutlined,
+  ArrowRightOutlined,
   MergeCellsOutlined,
   SplitCellsOutlined,
   DeleteOutlined,
@@ -18,11 +21,15 @@ import { useEditorStore } from '../../../stores/editorStore';
 import { TableWidthControl } from './TableWidthControl';
 import {
   insertTableRow,
+  insertTableRowBefore,
   insertTableColumn,
+  insertTableColumnBefore,
   deleteTableRow,
   deleteTableColumn,
-  mergeCells,
+  mergeCellsByVisualBounds,
   splitCell,
+  getTableSelectionBounds,
+  getTableCellRangeForVisualBounds,
 } from '../../../utils/blockOperations';
 import './TableToolbar.css';
 
@@ -46,6 +53,12 @@ export interface TableToolbarProps {
     endRow: number;
     endCol: number;
   } | null;
+  selectedVisualRange?: {
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+  } | null;
   /** 关闭回调 */
   onClose: () => void;
 }
@@ -66,6 +79,7 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
   block,
   selectedCell,
   selectedRange,
+  selectedVisualRange,
   onClose,
 }) => {
   const updateBlock = useEditorStore((state) => state.updateBlock);
@@ -79,20 +93,35 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     && selectedCell.row < rowCount
     && selectedCell.col >= 0
     && selectedCell.col < columnCount
-    && !!block.content.rows[selectedCell.row]?.cells[selectedCell.col];
-  const hasValidRange = !!selectedRange
-    && selectedRange.startRow >= 0
-    && selectedRange.startCol >= 0
-    && selectedRange.endRow >= selectedRange.startRow
-    && selectedRange.endCol >= selectedRange.startCol
-    && selectedRange.endRow < rowCount
-    && selectedRange.endCol < columnCount
-    && block.content.rows.every((row) => row.cells.length > selectedRange.endCol);
+    && !!block.content.rows[selectedCell.row]?.cells[selectedCell.col]
+    && (block.content.rows[selectedCell.row]?.cells[selectedCell.col]?.rowspan ?? 1) > 0
+    && (block.content.rows[selectedCell.row]?.cells[selectedCell.col]?.colspan ?? 1) > 0;
+  const selectionBounds = selectedVisualRange
+    || (selectedRange
+      ? getTableSelectionBounds(
+        block,
+        selectedRange.startRow,
+        selectedRange.startCol,
+        selectedRange.endRow,
+        selectedRange.endCol,
+      )
+      : null);
+  const visualCellRange = selectionBounds
+    ? getTableCellRangeForVisualBounds(block, selectionBounds)
+    : null;
+    const hasValidRange = !!selectionBounds && !!visualCellRange;
   const isMultiCellRange = hasValidRange
-    && (selectedRange.endRow > selectedRange.startRow || selectedRange.endCol > selectedRange.startCol);
+    && (selectionBounds.rowEnd > selectionBounds.rowStart || selectionBounds.colEnd > selectionBounds.colStart);
+  const selectedCellData = hasValidSelectedCell
+    ? block.content.rows[selectedCell.row]?.cells[selectedCell.col]
+    : undefined;
+  const canEditTableStructure = hasValidSelectedCell;
+  const isMergedCell = hasValidSelectedCell
+    && ((selectedCellData?.rowspan ?? 1) > 1 || (selectedCellData?.colspan ?? 1) > 1);
 
   // 插入行
   const handleInsertRow = useCallback(() => {
+    if (!canEditTableStructure) return;
     try {
       const newBlock = insertTableRow(block, selectedCell.row);
       updateBlock(block.id, {
@@ -103,10 +132,26 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '插入行失败'));
     }
-  }, [block, selectedCell.row, updateBlock]);
+  }, [block, canEditTableStructure, selectedCell.row, updateBlock]);
+
+  // 在上方插入行
+  const handleInsertRowBefore = useCallback(() => {
+    if (!canEditTableStructure) return;
+    try {
+      const newBlock = insertTableRowBefore(block, selectedCell.row);
+      updateBlock(block.id, {
+        content: newBlock.content,
+        metadata: newBlock.metadata,
+      });
+      message.success('已在上方插入行');
+    } catch (error: unknown) {
+      message.error(getOperationError(error, '插入行失败'));
+    }
+  }, [block, canEditTableStructure, selectedCell.row, updateBlock]);
 
   // 插入列
   const handleInsertColumn = useCallback(() => {
+    if (!canEditTableStructure) return;
     try {
       const newBlock = insertTableColumn(block, selectedCell.col);
       updateBlock(block.id, {
@@ -117,10 +162,26 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '插入列失败'));
     }
-  }, [block, selectedCell.col, updateBlock]);
+  }, [block, canEditTableStructure, selectedCell.col, updateBlock]);
+
+  // 在左侧插入列
+  const handleInsertColumnBefore = useCallback(() => {
+    if (!canEditTableStructure) return;
+    try {
+      const newBlock = insertTableColumnBefore(block, selectedCell.col);
+      updateBlock(block.id, {
+        content: newBlock.content,
+        metadata: newBlock.metadata,
+      });
+      message.success('已在左侧插入列');
+    } catch (error: unknown) {
+      message.error(getOperationError(error, '插入列失败'));
+    }
+  }, [block, canEditTableStructure, selectedCell.col, updateBlock]);
 
   // 删除行
   const handleDeleteRow = useCallback(() => {
+    if (!canEditTableStructure) return;
     try {
       const newBlock = deleteTableRow(block, selectedCell.row);
       updateBlock(block.id, {
@@ -132,10 +193,11 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '删除行失败'));
     }
-  }, [block, selectedCell.row, updateBlock, onClose]);
+  }, [block, canEditTableStructure, selectedCell.row, updateBlock, onClose]);
 
   // 删除列
   const handleDeleteColumn = useCallback(() => {
+    if (!canEditTableStructure) return;
     try {
       const newBlock = deleteTableColumn(block, selectedCell.col);
       updateBlock(block.id, {
@@ -147,23 +209,17 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '删除列失败'));
     }
-  }, [block, selectedCell.col, updateBlock, onClose]);
+  }, [block, canEditTableStructure, selectedCell.col, updateBlock, onClose]);
 
   // 合并单元格
   const handleMergeCells = useCallback(() => {
-    if (!selectedRange) {
+    if (!isMultiCellRange || !visualCellRange) {
       message.warning('请先选择要合并的单元格范围(Shift+点击)');
       return;
     }
 
     try {
-      const newBlock = mergeCells(
-        block,
-        selectedRange.startRow,
-        selectedRange.startCol,
-        selectedRange.endRow,
-        selectedRange.endCol
-      );
+        const newBlock = mergeCellsByVisualBounds(block, selectionBounds);
       updateBlock(block.id, {
         content: newBlock.content,
       });
@@ -172,10 +228,11 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '合并单元格失败'));
     }
-  }, [block, selectedRange, updateBlock, onClose]);
+  }, [block, isMultiCellRange, selectionBounds, visualCellRange, updateBlock, onClose]);
 
   // 拆分单元格
   const handleSplitCell = useCallback(() => {
+    if (!hasValidSelectedCell || !isMergedCell) return;
     try {
       const newBlock = splitCell(block, selectedCell.row, selectedCell.col);
       updateBlock(block.id, {
@@ -186,7 +243,7 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     } catch (error: unknown) {
       message.error(getOperationError(error, '拆分单元格失败'));
     }
-  }, [block, selectedCell, updateBlock, onClose]);
+  }, [block, hasValidSelectedCell, isMergedCell, selectedCell, updateBlock, onClose]);
 
   // 删除整个表格
   const handleDeleteTable = useCallback(async () => {
@@ -199,13 +256,6 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
     }
   }, [block.id, deleteBlock, onClose]);
 
-  // 检查当前单元格是否已合并
-  const isMergedCell = useCallback(() => {
-    if (!hasValidSelectedCell) return false;
-    const cell = block.content.rows[selectedCell.row]?.cells[selectedCell.col];
-    return cell && (cell.rowspan > 1 || cell.colspan > 1);
-  }, [block, hasValidSelectedCell, selectedCell]);
-
   return (
     <div className="table-toolbar">
       <Space size="small">
@@ -218,22 +268,46 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
         <Button
           type="text"
           size="small"
-          icon={<PlusOutlined />}
+          icon={<ArrowUpOutlined />}
+          onClick={handleInsertRowBefore}
+          disabled={!canEditTableStructure}
+          title={canEditTableStructure ? '在上方插入行' : '请选择未合并的可见单元格'}
+        >
+          上方插入行
+        </Button>
+
+        <Button
+          type="text"
+          size="small"
+          icon={<ArrowDownOutlined />}
           onClick={handleInsertRow}
-          title="在下方插入行"
+          disabled={!canEditTableStructure}
+          title={canEditTableStructure ? '在下方插入行' : '请选择未合并的可见单元格'}
         >
-          插入行
+          在下方插入行
         </Button>
 
         {/* 插入列 */}
         <Button
           type="text"
           size="small"
-          icon={<PlusOutlined />}
+          icon={<ArrowLeftOutlined />}
+          onClick={handleInsertColumnBefore}
+          disabled={!canEditTableStructure}
+          title={canEditTableStructure ? '在左侧插入列' : '请选择未合并的可见单元格'}
+        >
+          左侧插入列
+        </Button>
+
+        <Button
+          type="text"
+          size="small"
+          icon={<ArrowRightOutlined />}
           onClick={handleInsertColumn}
-          title="在右侧插入列"
+          disabled={!canEditTableStructure}
+          title={canEditTableStructure ? '在右侧插入列' : '请选择未合并的可见单元格'}
         >
-          插入列
+          在右侧插入列
         </Button>
 
         <Divider type="vertical" style={{ margin: '0 4px' }} />
@@ -245,7 +319,7 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
           icon={<MergeCellsOutlined />}
           onClick={handleMergeCells}
           disabled={!isMultiCellRange}
-          title={isMultiCellRange ? '合并选中的单元格' : '请先按住Shift选择多个单元格'}
+          title={isMultiCellRange ? '合并选中的单元格' : '请选择连续且不截断已有合并的单元格'}
         >
           合并单元格
         </Button>
@@ -256,8 +330,8 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
           size="small"
           icon={<SplitCellsOutlined />}
           onClick={handleSplitCell}
-          disabled={!isMergedCell()}
-          title={isMergedCell() ? '拆分此单元格' : '此单元格未合并'}
+          disabled={!isMergedCell}
+          title={isMergedCell ? '拆分此单元格' : '此单元格未合并'}
         >
           拆分单元格
         </Button>
@@ -276,8 +350,8 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
             size="small"
             icon={<MinusOutlined />}
             danger
-            disabled={!hasValidSelectedCell || rowCount <= 1}
-            title="删除当前行"
+            disabled={!canEditTableStructure || rowCount <= 1}
+            title={canEditTableStructure ? '删除当前行' : '请选择未合并的可见单元格'}
           >
             删除行
           </Button>
@@ -295,8 +369,8 @@ export const TableToolbar: React.FC<TableToolbarProps> = ({
             size="small"
             icon={<MinusOutlined />}
             danger
-            disabled={!hasValidSelectedCell || columnCount <= 1}
-            title="删除当前列"
+            disabled={!canEditTableStructure || columnCount <= 1}
+            title={canEditTableStructure ? '删除当前列' : '请选择未合并的可见单元格'}
           >
             删除列
           </Button>

src/utils/blockOperations.ts

@@ -117,11 +117,178 @@ function assertTableRange(
   assertTableIndex(startCol, table.metadata.cols, '起始列');
   assertTableIndex(endCol, table.metadata.cols, '结束列');
   if (startCol > endCol) throw new Error('列范围无效');
-  if (table.content.rows.some((row) => row.cells.length <= endCol)) {
+  const selectedRows = table.content.rows.slice(startRow, endRow + 1);
+  if (selectedRows.some((row) => row.cells.length <= endCol)) {
     throw new Error('表格单元格结构无效');
   }
 }
 
+export interface TableVisualCellPosition {
+  rowStart: number;
+  rowEnd: number;
+  colStart: number;
+  colEnd: number;
+}
+
+export function getTableVisualCellPositions(table: TableBlock): Map<string, TableVisualCellPosition> {
+  const occupied: boolean[][] = [];
+  const positions = new Map<string, TableVisualCellPosition>();
+
+  table.content.rows.forEach((row, rowIndex) => {
+    if (!occupied[rowIndex]) occupied[rowIndex] = [];
+    let visualCol = 0;
+
+    row.cells.forEach((cell, cellIndex) => {
+      const rowSpan = cell.rowspan ?? 1;
+      const colSpan = cell.colspan ?? 1;
+      if (rowSpan <= 0 || colSpan <= 0) {
+        const hiddenCol = Number.isInteger(cell.col_index) && (cell.col_index ?? 0) > 0
+          ? (cell.col_index ?? 1) - 1
+          : visualCol;
+        visualCol = Math.max(visualCol, hiddenCol + 1);
+        return;
+      }
+
+      while (occupied[rowIndex][visualCol]) visualCol += 1;
+
+      const position = {
+        rowStart: rowIndex,
+        rowEnd: rowIndex + rowSpan - 1,
+        colStart: visualCol,
+        colEnd: visualCol + colSpan - 1,
+      };
+      positions.set(`${rowIndex}-${cellIndex}`, position);
+
+      for (let occupiedRow = position.rowStart; occupiedRow <= position.rowEnd; occupiedRow += 1) {
+        if (!occupied[occupiedRow]) occupied[occupiedRow] = [];
+        for (let occupiedCol = position.colStart; occupiedCol <= position.colEnd; occupiedCol += 1) {
+          occupied[occupiedRow][occupiedCol] = true;
+        }
+      }
+      visualCol = position.colEnd + 1;
+    });
+  });
+
+  return positions;
+}
+
+function createHiddenCell(colIndex: number): TableCell {
+  return {
+    text: '',
+    rowspan: 0,
+    colspan: 0,
+    col_index: colIndex + 1,
+    style: {},
+    word_style: 'Normal',
+    width: 100,
+  };
+}
+
+interface PositionedTableCell {
+  cell: TableCell;
+  position: TableVisualCellPosition;
+}
+
+function rebuildTableRows(
+  cells: PositionedTableCell[],
+  rowHeights: Array<number | undefined>,
+  columnCount: number,
+): TableRow[] {
+  const starts = new Map<string, PositionedTableCell>();
+  for (const entry of cells) {
+    starts.set(`${entry.position.rowStart}-${entry.position.colStart}`, entry);
+  }
+
+  return rowHeights.map((height, rowIndex) => {
+    const rowCells: TableCell[] = [];
+    for (let colIndex = 0; colIndex < columnCount; colIndex += 1) {
+      const start = starts.get(`${rowIndex}-${colIndex}`);
+      if (start) {
+        rowCells.push({
+          ...start.cell,
+          rowspan: start.position.rowEnd - start.position.rowStart + 1,
+          colspan: start.position.colEnd - start.position.colStart + 1,
+          col_index: colIndex + 1,
+        });
+        continue;
+      }
+
+      const covered = cells.some(({ position }) =>
+        position.rowStart <= rowIndex
+        && position.rowEnd >= rowIndex
+        && position.colStart <= colIndex
+        && position.colEnd >= colIndex
+      );
+      rowCells.push(covered ? createHiddenCell(colIndex) : createEmptyCell(colIndex + 1));
+    }
+
+    return {
+      cells: rowCells,
+      ...(height !== undefined ? { height } : {}),
+    };
+  });
+}
+
+export function getTableSelectionBounds(
+  table: TableBlock,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): TableVisualCellPosition | null {
+  if (![startRow, startCol, endRow, endCol].every(Number.isInteger)) return null;
+  if (startRow < 0 || endRow < startRow || endRow >= table.content.rows.length) return null;
+
+  const positions = getTableVisualCellPositions(table);
+  const startPosition = positions.get(`${startRow}-${startCol}`);
+  const endPosition = positions.get(`${endRow}-${endCol}`);
+  if (!startPosition || !endPosition) return null;
+
+  const bounds = {
+    rowStart: Math.min(startPosition.rowStart, endPosition.rowStart),
+    rowEnd: Math.max(startPosition.rowEnd, endPosition.rowEnd),
+    colStart: Math.min(startPosition.colStart, endPosition.colStart),
+    colEnd: Math.max(startPosition.colEnd, endPosition.colEnd),
+  };
+
+  for (const position of positions.values()) {
+    const intersects = position.rowStart <= bounds.rowEnd
+      && position.rowEnd >= bounds.rowStart
+      && position.colStart <= bounds.colEnd
+      && position.colEnd >= bounds.colStart;
+    const isContained = position.rowStart >= bounds.rowStart
+      && position.rowEnd <= bounds.rowEnd
+      && position.colStart >= bounds.colStart
+      && position.colEnd <= bounds.colEnd;
+    if (intersects && !isContained) return null;
+  }
+
+  return bounds;
+}
+
+export function getTableCellRangeForVisualBounds(
+  table: TableBlock,
+  bounds: TableVisualCellPosition,
+): { startRow: number; startCol: number; endRow: number; endCol: number } | null {
+  const positions = getTableVisualCellPositions(table);
+  let start: { row: number; col: number } | null = null;
+  let end: { row: number; col: number } | null = null;
+
+  for (const [key, position] of positions.entries()) {
+    if (position.rowStart !== bounds.rowStart || position.colStart !== bounds.colStart) continue;
+    const [row, col] = key.split('-').map(Number);
+    start = { row, col };
+  }
+  for (const [key, position] of positions.entries()) {
+    if (position.rowEnd !== bounds.rowEnd || position.colEnd !== bounds.colEnd) continue;
+    const [row, col] = key.split('-').map(Number);
+    end = { row, col };
+  }
+
+  if (!start || !end) return null;
+  return { startRow: start.row, startCol: start.col, endRow: end.row, endCol: end.col };
+}
+
 /**
  * 将 text 字段从富文本数组转换为纯字符串
  * 
@@ -188,8 +355,8 @@ export function serializeTableCell(
   
   return {
     text: flattenTextToString(cell.text), // 转换为纯字符串
-    rowspan: cell.rowspan || 1,
-    colspan: cell.colspan || 1,
+    rowspan: cell.rowspan ?? 1,
+    colspan: cell.colspan ?? 1,
     col_index: cell.col_index !== undefined ? cell.col_index : colIndex,
     style: style,
     word_style: cell.word_style || 'Normal',
@@ -296,8 +463,8 @@ export function normalizeTableCell(
   
   return {
     text: cell.text || '',
-    rowspan: cell.rowspan || 1,
-    colspan: cell.colspan || 1,
+    rowspan: cell.rowspan ?? 1,
+    colspan: cell.colspan ?? 1,
     col_index: cell.col_index !== undefined ? cell.col_index : colIndex,
     style: style,
     word_style: cell.word_style || 'Normal',
@@ -402,8 +569,10 @@ export function createEmptyRow(cols: number, colWidths?: number[], height?: numb
  * const newTable = insertTableRow(table, 1); // 在第2行后插入
  * ```
  */
-export function insertTableRow(table: TableBlock, afterRow: number): TableBlock {
-  assertTableIndex(afterRow, table.content.rows.length, '行');
+function insertTableRowAt(table: TableBlock, insertIndex: number): TableBlock {
+  if (!Number.isInteger(insertIndex) || insertIndex < 0 || insertIndex > table.content.rows.length) {
+    throw new Error('行索引无效');
+  }
   // 使用合理的默认行高
   const defaultHeight = 58; // 默认行高58磅
   
@@ -426,8 +595,26 @@ export function insertTableRow(table: TableBlock, afterRow: number): TableBlock
   }
   
   const newRow = createEmptyRow(table.metadata.cols, colWidths, defaultHeight);
-  const rows = [...table.content.rows];
-  rows.splice(afterRow + 1, 0, newRow);
+  const positions = getTableVisualCellPositions(table);
+  const rows = table.content.rows.map((row, rowIndex) => ({
+    ...row,
+    cells: row.cells.map((cell, cellIndex) => {
+      const position = positions.get(`${rowIndex}-${cellIndex}`);
+      if (!position || position.rowStart >= insertIndex || position.rowEnd < insertIndex) return cell;
+      return { ...cell, rowspan: (cell.rowspan ?? 1) + 1 };
+    }),
+  }));
+
+  newRow.cells = newRow.cells.map((cell, colIndex) => {
+    const spanningCell = [...positions.values()].find((position) =>
+      position.rowStart < insertIndex
+      && position.rowEnd >= insertIndex
+      && position.colStart <= colIndex
+      && position.colEnd >= colIndex
+    );
+    return spanningCell ? createHiddenCell(colIndex) : cell;
+  });
+  rows.splice(insertIndex, 0, newRow);
   
   return {
     ...table,
@@ -443,6 +630,23 @@ export function insertTableRow(table: TableBlock, afterRow: number): TableBlock
   };
 }
 
+export function insertTableRow(table: TableBlock, afterRow: number): TableBlock {
+  assertTableIndex(afterRow, table.content.rows.length, '行');
+  return insertTableRowAt(table, afterRow + 1);
+}
+
+/**
+ * 在表格中插入行
+ *
+ * @param table 表格块
+ * @param beforeRow 在此行之前插入
+ * @returns 新的表格块
+ */
+export function insertTableRowBefore(table: TableBlock, beforeRow: number): TableBlock {
+  assertTableIndex(beforeRow, table.content.rows.length, '行');
+  return insertTableRowAt(table, beforeRow);
+}
+
 /**
  * 在表格中插入列
  * 
@@ -455,55 +659,58 @@ export function insertTableRow(table: TableBlock, afterRow: number): TableBlock
  * const newTable = insertTableColumn(table, 1); // 在第2列后插入
  * ```
  */
-export function insertTableColumn(table: TableBlock, afterCol: number): TableBlock {
-  assertTableIndex(afterCol, table.metadata.cols, '列');
+function insertTableColumnAt(table: TableBlock, insertIndex: number): TableBlock {
+  if (!Number.isInteger(insertIndex) || insertIndex < 0 || insertIndex > table.metadata.cols) {
+    throw new Error('列索引无效');
+  }
   // 计算新列的宽度
   // 如果有content.col_widths，使用相邻列的宽度；否则使用默认值
   let newColWidth = 100; // 默认列宽100磅
   
-  if (table.content.col_widths && table.content.col_widths.length > afterCol) {
-    newColWidth = table.content.col_widths[afterCol];
-  } else if (table.metadata.col_widths && table.metadata.col_widths.length > afterCol) {
+  const adjacentCol = Math.min(insertIndex, Math.max(table.metadata.cols - 1, 0));
+  if (table.content.col_widths && table.content.col_widths.length > adjacentCol) {
+    newColWidth = table.content.col_widths[adjacentCol];
+  } else if (table.metadata.col_widths && table.metadata.col_widths.length > adjacentCol) {
     // 从百分比反推pt值
     const tableWidthPercent = table.metadata.table_width || 100;
     const pageWidthPt = 478;
     const tableActualWidthPt = pageWidthPt * (tableWidthPercent / 100);
-    newColWidth = tableActualWidthPt * table.metadata.col_widths[afterCol] / 100;
+    newColWidth = tableActualWidthPt * table.metadata.col_widths[adjacentCol] / 100;
   }
   
-  const rows = table.content.rows.map((row) => {
-    const cells = [...row.cells];
-    
-    // 插入新单元格，使用计算出的宽度
-    const newCell = createEmptyCell(afterCol + 2, newColWidth);
-    cells.splice(afterCol + 1, 0, newCell);
-    
-    // 更新后续单元格的 col_index
-    for (let i = afterCol + 2; i < cells.length; i++) {
-      if (cells[i].col_index !== undefined) {
-        cells[i] = {
-          ...cells[i],
-          col_index: i + 1,
-        };
-      }
-    }
-    
-    return { 
-      cells,
-      height: row.height, // 保留行高
-    };
+  const positions = getTableVisualCellPositions(table);
+  const positionedCells: PositionedTableCell[] = [];
+  table.content.rows.forEach((row, rowIndex) => {
+    row.cells.forEach((cell, cellIndex) => {
+      const position = positions.get(`${rowIndex}-${cellIndex}`);
+      if (!position) return;
+      positionedCells.push({
+        cell,
+        position: position.colStart < insertIndex && position.colEnd >= insertIndex
+          ? { ...position, colEnd: position.colEnd + 1 }
+          : position.colStart >= insertIndex
+            ? { ...position, colStart: position.colStart + 1, colEnd: position.colEnd + 1 }
+            : position,
+      });
+    });
   });
+
+  const rows = rebuildTableRows(
+    positionedCells,
+    table.content.rows.map((row) => row.height),
+    table.metadata.cols + 1,
+  );
   
   // 更新metadata.col_widths（百分比）
   const metadataColWidths = [...table.metadata.col_widths];
   // 新列使用相邻列的百分比，如果没有则平均分配
-  const newColPercent = metadataColWidths[afterCol] || (100 / (metadataColWidths.length + 1));
-  metadataColWidths.splice(afterCol + 1, 0, newColPercent);
+  const newColPercent = metadataColWidths[adjacentCol] || (100 / (metadataColWidths.length + 1));
+  metadataColWidths.splice(insertIndex, 0, newColPercent);
   
   // 更新content.col_widths（pt单位）
   const contentColWidths = table.content.col_widths ? [...table.content.col_widths] : [];
   if (contentColWidths.length > 0) {
-    contentColWidths.splice(afterCol + 1, 0, newColWidth);
+    contentColWidths.splice(insertIndex, 0, newColWidth);
   }
   
   return {
@@ -520,6 +727,23 @@ export function insertTableColumn(table: TableBlock, afterCol: number): TableBlo
   };
 }
 
+export function insertTableColumn(table: TableBlock, afterCol: number): TableBlock {
+  assertTableIndex(afterCol, table.metadata.cols, '列');
+  return insertTableColumnAt(table, afterCol + 1);
+}
+
+/**
+ * 在表格中插入列
+ *
+ * @param table 表格块
+ * @param beforeCol 在此列之前插入
+ * @returns 新的表格块
+ */
+export function insertTableColumnBefore(table: TableBlock, beforeCol: number): TableBlock {
+  assertTableIndex(beforeCol, table.metadata.cols, '列');
+  return insertTableColumnAt(table, beforeCol);
+}
+
 /**
  * 删除表格行
  * 
@@ -533,7 +757,39 @@ export function deleteTableRow(table: TableBlock, rowIndex: number): TableBlock
     throw new Error('表格至少需要一行');
   }
   
-  const rows = table.content.rows.filter((_, i) => i !== rowIndex);
+  const positions = getTableVisualCellPositions(table);
+  const positionedCells: PositionedTableCell[] = [];
+  table.content.rows.forEach((row, sourceRow) => {
+    row.cells.forEach((cell, sourceCol) => {
+      const position = positions.get(`${sourceRow}-${sourceCol}`);
+      if (!position) return;
+      if (position.rowStart <= rowIndex && position.rowEnd >= rowIndex) {
+        if (position.rowStart === position.rowEnd) return;
+        positionedCells.push({
+          cell,
+          position: {
+            ...position,
+            rowStart: position.rowStart > rowIndex ? position.rowStart - 1 : position.rowStart,
+            rowEnd: position.rowEnd - 1,
+          },
+        });
+        return;
+      }
+      positionedCells.push({
+        cell,
+        position: {
+          ...position,
+          rowStart: position.rowStart > rowIndex ? position.rowStart - 1 : position.rowStart,
+          rowEnd: position.rowEnd > rowIndex ? position.rowEnd - 1 : position.rowEnd,
+        },
+      });
+    });
+  });
+
+  const rowHeights = table.content.rows
+    .filter((_, index) => index !== rowIndex)
+    .map((row) => row.height);
+  const rows = rebuildTableRows(positionedCells, rowHeights, table.metadata.cols);
   
   return {
     ...table,
@@ -562,18 +818,40 @@ export function deleteTableColumn(table: TableBlock, colIndex: number): TableBlo
     throw new Error('表格至少需要一列');
   }
   
-  const rows = table.content.rows.map((row) => {
-    const cells = row.cells.filter((_, i) => i !== colIndex);
-    
-    // 更新剩余单元格的 col_index
-    return {
-      cells: cells.map((cell, i) => ({
-        ...cell,
-        col_index: i + 1,
-      })),
-      height: row.height, // 保留行高
-    };
+  const positions = getTableVisualCellPositions(table);
+  const positionedCells: PositionedTableCell[] = [];
+  table.content.rows.forEach((row, sourceRow) => {
+    row.cells.forEach((cell, sourceCol) => {
+      const position = positions.get(`${sourceRow}-${sourceCol}`);
+      if (!position) return;
+      if (position.colStart <= colIndex && position.colEnd >= colIndex) {
+        if (position.colStart === position.colEnd) return;
+        positionedCells.push({
+          cell,
+          position: {
+            ...position,
+            colStart: position.colStart > colIndex ? position.colStart - 1 : position.colStart,
+            colEnd: position.colEnd - 1,
+          },
+        });
+        return;
+      }
+      positionedCells.push({
+        cell,
+        position: {
+          ...position,
+          colStart: position.colStart > colIndex ? position.colStart - 1 : position.colStart,
+          colEnd: position.colEnd > colIndex ? position.colEnd - 1 : position.colEnd,
+        },
+      });
+    });
   });
+
+  const rows = rebuildTableRows(
+    positionedCells,
+    table.content.rows.map((row) => row.height),
+    table.metadata.cols - 1,
+  );
   
   // 更新metadata.col_widths
   const metadataColWidths = table.metadata.col_widths.filter((_, i) => i !== colIndex);
@@ -637,9 +915,72 @@ export function mergeCells(
 ): TableBlock {
   assertTableRange(table, startRow, startCol, endRow, endCol);
 
+  const selectionBounds = getTableSelectionBounds(table, startRow, startCol, endRow, endCol);
+  if (!selectionBounds) {
+    throw new Error('合并范围不能截断已有合并单元格');
+  }
+  return mergeCellsByVisualBounds(table, selectionBounds);
+}
+
+/**
+ * 按视觉网格边界合并单元格。
+ *
+ * 视觉坐标与行内 cells 数组下标不是同一个坐标系，尤其在跨行单元格
+ * 产生隐藏占位时，不能先把视觉范围当作数组范围再次校验。
+ */
+export function mergeCellsByVisualBounds(
+  table: TableBlock,
+  selectionBounds: TableVisualCellPosition,
+): TableBlock {
+  if (selectionBounds.rowStart > selectionBounds.rowEnd) {
+    throw new Error('行范围无效');
+  }
+  if (selectionBounds.colStart > selectionBounds.colEnd) {
+    throw new Error('列范围无效');
+  }
+  const visualPositions = getTableVisualCellPositions(table);
+  const visualColumnEnd = Math.max(
+    table.metadata.cols - 1,
+    ...[...visualPositions.values()].map((position) => position.colEnd),
+  );
+  const visualRowEnd = Math.max(
+    table.content.rows.length - 1,
+    ...[...visualPositions.values()].map((position) => position.rowEnd),
+  );
+  if (
+    selectionBounds.rowStart < 0
+    || selectionBounds.rowEnd > visualRowEnd
+    || selectionBounds.colStart < 0
+    || selectionBounds.colEnd > visualColumnEnd
+  ) {
+    throw new Error('结束索引无效');
+  }
+
+  for (const position of visualPositions.values()) {
+    const intersects = position.rowStart <= selectionBounds.rowEnd
+      && position.rowEnd >= selectionBounds.rowStart
+      && position.colStart <= selectionBounds.colEnd
+      && position.colEnd >= selectionBounds.colStart;
+    const isContained = position.rowStart >= selectionBounds.rowStart
+      && position.rowEnd <= selectionBounds.rowEnd
+      && position.colStart >= selectionBounds.colStart
+      && position.colEnd <= selectionBounds.colEnd;
+    if (intersects && !isContained) {
+      throw new Error('合并范围不能截断已有合并单元格');
+    }
+  }
+
+  const primaryEntry = [...visualPositions.entries()].find(([, position]) =>
+    position.rowStart === selectionBounds.rowStart && position.colStart === selectionBounds.colStart
+  );
+  if (!primaryEntry) {
+    throw new Error('合并起始单元格不存在');
+  }
+  const primaryKey = primaryEntry[0];
+
   // 计算合并范围
-  const rowSpan = endRow - startRow + 1;
-  const colSpan = endCol - startCol + 1;
+  const rowSpan = selectionBounds.rowEnd - selectionBounds.rowStart + 1;
+  const colSpan = selectionBounds.colEnd - selectionBounds.colStart + 1;
   
   // 收集所有被合并单元格的文本内容
   const displayTexts: string[] = [];
@@ -655,29 +996,32 @@ export function mergeCells(
   
   // 收集文本
   table.content.rows.forEach((row, rowIdx) => {
-    if (rowIdx >= startRow && rowIdx <= endRow) {
-      row.cells.forEach((cell, colIdx) => {
-        if (colIdx >= startCol && colIdx <= endCol) {
-          const text = normalizeText(cell.text);
-          if (text.trim()) {
-            displayTexts.push(text.trim());
-          }
-        }
-      });
-    }
+    row.cells.forEach((cell, colIdx) => {
+      const position = visualPositions.get(`${rowIdx}-${colIdx}`);
+      if (!position) return;
+      const isContained = position.rowStart >= selectionBounds.rowStart
+        && position.rowEnd <= selectionBounds.rowEnd
+        && position.colStart >= selectionBounds.colStart
+        && position.colEnd <= selectionBounds.colEnd;
+      if (isContained) {
+        const text = normalizeText(cell.text);
+        if (text.trim()) displayTexts.push(text.trim());
+      }
+    });
   });
   
   const rows = table.content.rows.map((row, rowIdx) => {
-    if (rowIdx < startRow || rowIdx > endRow) {
-      return row;
-    }
-    
     const cells = row.cells.map((cell, colIdx) => {
-      if (colIdx < startCol || colIdx > endCol) {
-        return cell;
-      }
-      
-      if (rowIdx === startRow && colIdx === startCol) {
+      const key = `${rowIdx}-${colIdx}`;
+      const position = visualPositions.get(key);
+      if (!position) return cell;
+      const isContained = position.rowStart >= selectionBounds.rowStart
+        && position.rowEnd <= selectionBounds.rowEnd
+        && position.colStart >= selectionBounds.colStart
+        && position.colEnd <= selectionBounds.colEnd;
+      if (!isContained) return cell;
+
+      if (key === primaryKey) {
         // 主单元格：设置完整的标准格式
         // 合并后的文本统一为纯字符串格式
         const mergedText = displayTexts.join(' ');
@@ -687,7 +1031,7 @@ export function mergeCells(
           text: mergedText || normalizeText(cell.text),
           rowspan: rowSpan,
           colspan: colSpan,
-          col_index: startCol + 1, // 列索引从1开始
+          col_index: colIdx + 1, // 列索引从1开始
           style: {
             ...cell.style, // 保留原有样式
           },