在浏览包含大量数据的 Excel 工作表时，固定表头或关键列能显著提升数据查看效率。冻结窗格功能可以让指定行或列在滚动时保持可见；查询冻结窗格范围可以确认当前工作表中哪些区域被冻结；取消冻结窗格则能在不需要固定显示时恢复常规浏览方式。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端直接完成这些操作，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。

本文介绍三个核心功能点：

• 冻结窗格
• 查询冻结窗格范围
• 取消冻结窗格

有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。

冻结窗格

当工作表包含大量数据时，冻结窗格可以固定表头或特定区域，使你在滚动查看数据时始终能看到关键的行或列。Spire.XLS for JavaScript 通过 FreezePanes 方法冻结指定行列上方及左侧的窗格。例如 FreezePanes(2, 1) 会冻结第一行，使其在上下滚动时保持可见。

function App() {
  const sheetToSVG = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;

    // 检查模块是否就绪
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'FreezePanes.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // 加载工作簿
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 获取第一个工作表
    const sheet = workbook.Worksheets.get(0);

    // 冻结第一行
    sheet.FreezePanes(2, 1);

    // 设置第二列的列宽
    sheet.SetColumnWidth(2, 10);

    const outputFileName = "FreezePanes_output.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放 workbook 对象以释放资源
    workbook.Dispose();

    // 从 VFS 读取转换后的文件，触发下载
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Freeze Panes</h1>
      <button onClick={sheetToSVG}>
        Start
      </button>
    </div>
  );
}

export default App;

原文档 冻结首行后

查询冻结窗格范围

在处理冻结窗格时，有时需要确认当前工作表中冻结窗格所在的位置。Spire.XLS for JavaScript 通过 GetFreezePanes 方法获取冻结窗格所在的行索引和列索引，返回值为 0 时表示该方向未冻结。

function App() {
  const sheetToSVG = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;

    // 检查模块是否就绪
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'GetFreezePaneRange.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // 加载工作簿
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 获取第一个工作表
    const sheet = workbook.Worksheets.get(0);

    // 获取冻结窗格所在的行索引和列索引
    const indexs = sheet.GetFreezePanes();
    const rowIndex = indexs[0];
    const colIndex = indexs[1];

    // 将查询结果写入文本文件
    const outputFileName = "GetFreezePaneRange_output.txt";
    window.dotnetRuntime.Module.FS.writeFile(outputFileName, `Row index: ${rowIndex}, column index: ${colIndex}`);

    // 释放 workbook 对象以释放资源
    workbook.Dispose();

    // 从 VFS 读取转换后的文件，触发下载
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: "text/plain" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Get Freeze Pane Range</h1>
      <button onClick={sheetToSVG}>
        Start
      </button>
    </div>
  );
}

export default App;

含冻结窗格原文档 查询结果

取消冻结窗格

当不再需要固定显示时，可以通过 RemovePanes 方法取消工作表中已设置的冻结窗格，恢复正常滚动浏览。

function App() {
  const sheetToSVG = async () => {
    // 获取 Spire.XLS WASM 模块
    const xlsModule = window.wasmModule?.spirexls;

    // 检查模块是否就绪
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // 将字体和 Excel 文件载入 VFS
    await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'Template_Xls_2.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // 加载工作簿
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // 获取第一个工作表
    const sheet = workbook.Worksheets.get(0);

    // 取消冻结窗格
    sheet.RemovePanes();

    const outputFileName = "UnfreezeExcelPanes_output.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放 workbook 对象以释放资源
    workbook.Dispose();

    // 从 VFS 读取转换后的文件，触发下载
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Unfreeze Panes</h1>
      <button onClick={sheetToSVG}>
        Start
      </button>
    </div>
  );
}

export default App;

取消冻结前 取消冻结后

常见问题

冻结窗格后首行仍会滚动

原因：FreezePanes 方法的参数设置不正确，导致冻结的区域不是预期的行或列。

解决：FreezePanes 方法以指定位置为分界，冻结该位置上方及左侧的窗格。例如冻结首行使用 FreezePanes(2, 1)，冻结前两行使用 FreezePanes(3, 1)，同时冻结首行和首列使用 FreezePanes(2, 2)。

查询冻结窗格范围时返回 0

原因：工作表尚未设置冻结窗格，因此查询到的行列索引为 0。

解决：先调用 FreezePanes 方法设置冻结窗格，再调用 GetFreezePanes 查询冻结范围。

取消冻结窗格后仍显示冻结效果

原因：取消冻结后未正确保存工作簿，或者打开的是修改前的文件。

解决：调用 RemovePanes 方法后务必通过 SaveToFile 保存工作簿，并打开输出文件确认取消效果。

获取免费许可证

如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。