luckysheet如何获取鼠标选中单元格的行列坐标？

Question

在使用 Luckysheet 进行在线表格开发时，如何实时获取鼠标选中单元格的行列坐标是一个常见需求。许多开发者在实现单元格数据读取、自定义右键菜单或联动其他组件时，需要准确获取当前选区的 `row` 和 `column` 索引。然而，由于 Luckysheet 的选区事件较为复杂，初学者常不清楚应监听哪个事件（如 `selectionChanged`）或如何从回调参数中解析出 `r1, r2, c1, c2` 等信息。此外，合并单元格和多区域选中的处理也增加了获取精确行列坐标的难度。如何通过官方 API 正确获取并解析鼠标选中区域的起始与结束行列索引，成为实际开发中的典型技术问题。

Answer 1

1. 初识 Luckysheet 选区事件机制

Luckysheet 是一个功能强大的在线电子表格库，广泛应用于数据填报、报表展示和协同编辑场景。在实际开发中，开发者常需实时获取用户鼠标选中的单元格行列坐标（row 和 column 索引），以实现数据联动、右键菜单定制或高亮交互等功能。

最基础的切入点是监听 selectionChanged 事件，该事件在用户更改选区时触发。Luckysheet 提供了配置项用于注册回调函数：

luckysheet.create({
    container: 'luckysheet',
    data: [...],
    showtoolbar: true,
    showformulaBar: true,
    enableAddRow: false,
    enableAddCol: false,
    selectionMode: 'range', // 可选 single, range, row, column
    defaultColWidth: 73,
    defaultRowHeight: 19,
    onSelectionChange: function (param) {
        console.log('当前选区信息:', param);
    }
});

其中 onSelectionChange 回调返回的 param 参数包含了关键的选区坐标数据。

2. 解析选区参数：r1, r2, c1, c2 的含义与提取逻辑

当用户选择一个区域时，Luckysheet 在 param 中提供如下核心字段：

• r1：起始行索引（Start Row）
• r2：结束行索引（End Row）
• c1：起始列索引（Start Column）
• c2：结束列索引（End Column）

这些值均为零基索引（zero-based），即第一行/列为 0。

参数	类型	说明
r1	Number	选区起始行索引
r2	Number	选区结束行索引
c1	Number	选区起始列索引
c2	Number	选区结束列索引
row	Array	包含所有选中行范围的对象数组
column	Array	包含所有选中列范围的对象数组
sheetIndex	String	当前工作表索引
direction	String	扩展方向（如 "down", "right"）
type	String	选区类型（"cell", "row", "column"）
multiple	Boolean	是否为多区域选中

通过解析这些字段，可以精确获取用户当前操作的单元格位置。

3. 处理单区域与多区域选中的差异

当用户按住 Ctrl 键进行非连续区域选择时，Luckysheet 支持多区域选中（multiple selection）。此时 param.multiple === true，且 param.row 和 param.column 将包含多个区间对象。

onSelectionChange: function (param) {
    if (param.multiple) {
        console.log('多区域选中');
        param.row.forEach(range => {
            console.log(`行范围: ${range[0]} 到 ${range[1]}`);
        });
        param.column.forEach(range => {
            console.log(`列范围: ${range[0]} 到 ${range[1]}`);
        });
    } else {
        console.log(`单区域选中: 行 [${param.r1}, ${param.r2}], 列 [${param.c1}, ${param.c2}]`);
    }
}

这种结构要求开发者对数组遍历有清晰理解，并能处理不规则选区组合。

4. 合并单元格下的坐标映射问题

在存在合并单元格的场景下，Luckysheet 的选区坐标可能指向“主单元格”而非实际点击位置。例如，一个跨 2x2 的合并单元格，其内容只存储在左上角 (r=0, c=0)，其余位置为空引用。

可通过以下方式获取真实数据源位置：

function getRealCellPosition(row, col) {
    const merge = luckysheet.getMerge();
    for (let key in merge) {
        const { r, c, rs, cs } = merge[key];
        if (row >= r && row < r + rs && col >= c && col < c + cs) {
            return { realR: r, realC: c, isMerged: true };
        }
    }
    return { realR: row, realC: col, isMerged: false };
}

此函数可用于将任意选中坐标映射到其所属合并单元格的主坐标，确保数据读取一致性。

5. 实际应用场景与性能优化建议

结合上述技术点，构建一个完整的选区监听模块示例：

luckysheet.create({
    container: 'luckysheet',
    data: [],
    onSelectionChange: function (param) {
        const selections = [];
        
        if (param.multiple) {
            for (let i = 0; i < param.row.length; i++) {
                const r1 = param.row[i][0], r2 = param.row[i][1];
                const c1 = param.column[i][0], c2 = param.column[i][1];
                selections.push({ r1, r2, c1, c2 });
            }
        } else {
            selections.push({ r1: param.r1, r2: param.r2, c1: param.c1, c2: param.c2 });
        }

        selections.forEach(sel => {
            const mainCell = getRealCellPosition(sel.r1, sel.c1);
            console.log(`有效单元格坐标: (${mainCell.realR}, ${mainCell.realC})`);
            // 可在此处触发其他组件更新或 API 请求
        });
    }
});

graph TD A[用户鼠标选择单元格] --> B{是否为多区域?} B -- 是 --> C[遍历 param.row/column 数组] B -- 否 --> D[使用 r1,r2,c1,c2 直接获取] C --> E[提取每个子区域的行列范围] D --> F[判断是否处于合并单元格] E --> F F --> G[调用 getRealCellPosition 映射主单元格] G --> H[输出标准化行列坐标]

该流程图展示了从原始事件到最终坐标输出的完整处理链路。

6. 高级技巧：结合状态管理与外部系统联动

对于复杂应用，建议将选区状态抽象为独立模块，利用观察者模式或 Redux 类状态机进行管理。例如：

• 封装 SelectionManager 类，统一处理坐标解析与缓存
• 暴露 getCurrentCells() 方法供其他组件调用
• 通过 WebSocket 将选区同步至协作用户，实现“谁在看哪里”的协同感知
• 结合 Vue/React 响应式系统自动刷新关联视图

此外，可借助 luckysheet.getCellValue(r, c) 获取具体单元格值，进一步增强上下文感知能力。