如何使用Microsoft Office JS在Excel选中单元格上显示工具提示

核心思路 #

通过Office.js监听单元格选中事件，获取目标单元格的公式、文本等数据，动态创建浮动工具提示并定位到选中单元格的屏幕位置。

实现步骤及代码示例 #

1. 初始化Office.js并绑定选中事件

在Add-in的入口脚本中完成Office.js初始化，同时绑定单元格选中变化的监听事件：

Office.initialize = function(reason) {
    // 绑定单元格选中变化事件
    Office.context.document.onSelectionChanged.addHandlerAsync(onSelectionChanged);
};

async function onSelectionChanged(eventArgs) {
    // 先移除已存在的工具提示
    removeTooltip();
    
    try {
        await Excel.run(async (context) => {
            // 获取当前选中的单元格区域
            const range = context.workbook.getSelectedRange();
            range.load(['formula', 'values', 'address']);
            await context.sync();
            
            // 仅处理单个单元格的选中场景
            if (range.rowCount === 1 && range.columnCount === 1) {
                // 获取单元格的屏幕坐标，用于定位工具提示
                await getCellScreenPosition(range.address, (position) => {
                    createTooltip(position, range.formula, range.values[0][0]);
                });
            }
        });
    } catch (error) {
        console.error('获取单元格数据失败:', error);
    }
}

2. 获取单元格的屏幕位置

通过Office.js的异步方法获取单元格在屏幕上的坐标信息：

function getCellScreenPosition(cellAddress, callback) {
    Office.context.document.getSelectedRange().getBoundingClientRectAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            const rect = result.value;
            callback({
                top: rect.top,
                left: rect.left,
                width: rect.width
            });
        } else {
            console.error('获取单元格位置失败:', result.error);
        }
    });
}

3. 创建并渲染自定义工具提示

用HTML+CSS构建浮动提示框，填充单元格的公式和文本内容：

<!-- 在Add-in的HTML页面中添加工具提示容器（初始隐藏） -->
<div id="customTooltip" style="display:none; position:absolute; background:#f5f5f5; border:1px solid #ccc; padding:8px; border-radius:4px; z-index:9999; font-size:12px;"></div>

function createTooltip(position, formula, text) {
    const tooltip = document.getElementById('customTooltip');
    
    // 组装提示内容，优先展示公式，再展示单元格文本
    let content = '';
    if (formula) {
        content += `<p><strong>公式:</strong> ${formula}</p>`;
    }
    content += `<p><strong>内容:</strong> ${text || '空单元格'}</p>`;
    tooltip.innerHTML = content;
    
    // 设置提示框位置，偏移一点避免遮挡原单元格
    tooltip.style.display = 'block';
    tooltip.style.top = `${position.top + position.width + 10}px`;
    tooltip.style.left = `${position.left}px`;
}

// 移除已显示的工具提示
function removeTooltip() {
    const tooltip = document.getElementById('customTooltip');
    if (tooltip) {
        tooltip.style.display = 'none';
    }
}

关键注意事项 #

• 多选区域适配：示例仅处理单个单元格，若需支持多选，可修改逻辑遍历区域内单元格，或展示汇总信息。
• 样式自定义：可根据需求调整提示框的背景色、字体大小、边框样式，确保与Excel界面风格协调。
• 资源清理：切换选中单元格或关闭Add-in时，及时隐藏提示框，避免不必要的DOM残留。

内容的提问来源于stack exchange，提问作者Dixit Golani