Preserve QExcell frozen panes in XLSX

2026-06-01 12:50:25 +03:00
parent 227915d09d
commit a1ad101729
4 changed files with 169 additions and 6 deletions
@@ -32,7 +32,7 @@ npm run build
 ## Поддержка форматов

 - QWord открывает `.docx` и сохраняет `.docx`; при импорте базовых DOCX-абзацев читает выравнивание, переносы строк, табуляцию, внешние гиперссылки, простые таблицы, базовые растровые изображения, явные цвета текста, подсветку, размер и семейство шрифта из OOXML, а при экспорте DOCX сохраняются заголовки, абзацы, переносы строк, табуляция, выравнивание абзацев, списки, простые таблицы, внешние гиперссылки, базовые растровые изображения и базовое inline-форматирование текста: полужирный, курсив, подчеркивание, зачеркивание, цвет текста, подсветка, размер и семейство шрифта.
- QExcell открывает `.xlsx` и сохраняет `.xlsx`; сетка расширяется по фактически заполненным ячейкам, поддерживает несколько листов, скрытые и veryHidden листы через `sheet state`, активный лист через `workbookView activeTab`, формулы за пределами стартового диапазона A-H, shared formulas XLSX с относительными ссылками, базовые merged cells, внешние и внутренние гиперссылки ячеек, базовые диаграммы листа и базовое форматирование ячеек: полужирный, курсив, подчеркивание, зачеркивание, размер и семейство шрифта, прямые RGB/theme/indexed цвета текста с учетом `xl/theme/theme1.xml`, заливку, горизонтальное и вертикальное выравнивание, перенос текста, границы и цвет границ ячеек, числовые форматы XLSX для дат, процентов, денежных и дробных значений.
+- QExcell открывает `.xlsx` и сохраняет `.xlsx`; сетка расширяется по фактически заполненным ячейкам, поддерживает несколько листов, скрытые и veryHidden листы через `sheet state`, закрепленные области через `sheetViews pane`, активный лист через `workbookView activeTab`, формулы за пределами стартового диапазона A-H, shared formulas XLSX с относительными ссылками, базовые merged cells, внешние и внутренние гиперссылки ячеек, базовые диаграммы листа и базовое форматирование ячеек: полужирный, курсив, подчеркивание, зачеркивание, размер и семейство шрифта, прямые RGB/theme/indexed цвета текста с учетом `xl/theme/theme1.xml`, заливку, горизонтальное и вертикальное выравнивание, перенос текста, границы и цвет границ ячеек, числовые форматы XLSX для дат, процентов, денежных и дробных значений.
 - QPowerPoint открывает `.pptx` и сохраняет `.pptx`; импорт учитывает порядок слайдов из `presentation.xml`, переносы абзацев и ручные переносы строк `a:br` внутри текстовых блоков, а также заметки докладчика через relationships слайда, сохраняет заметки докладчика, базовые растровые изображения слайдов, пользовательский цвет фона слайда, а также цвет, размер и семейство шрифта текста заголовка/подзаголовка.
 - QOutlook открывает `.eml` и одиночные сообщения Outlook `.msg`, сохраняет письма в `.eml`; импорт EML поддерживает простые текстовые письма, `multipart/alternative`, `multipart/mixed`, `multipart/related`, `text/plain`, fallback из `text/html` в читаемый текст, base64, quoted-printable, MIME encoded-word заголовки UTF-8/windows-1251, MIME-вложения и inline-вложения с `Content-ID`, `To`, `Cc` и `Bcc`. Импорт MSG читает тему, отправителя, получателей `To/Cc/Bcc`, текст/HTML body и вложения, если эти поля доступны в MSG-файле. Новые письма можно адресовать через `To/Cc/Bcc` и сохранять в EML вместе с добавленными файлами. `.pst` и экспорт в `.msg` пока не реализованы.

@@ -46,7 +46,7 @@ Desktop-меню поддерживает системные команды дл
 - `Ctrl/Cmd+Shift+E`: экспортировать текущую рабочую область в PDF.
 - `Ctrl/Cmd+P`: печать текущей рабочей области.

-Импорт и экспорт реализуют базовую совместимость с Office Open XML, EML и чтением MSG: текст, базовое inline-форматирование, явные `w:br`, `w:tab`, `w:color`, `w:shd`, `w:highlight`, `w:sz`, `w:rFonts` и `w:strike` для переносов строк/табуляции/цвета/подсветки/размера/семейства/зачеркивания текста DOCX, выравнивание абзацев DOCX, внешние гиперссылки DOCX, внешние и внутренние гиперссылки XLSX, базовые растровые изображения DOCX/PPTX, простые таблицы, несколько листов, скрытые/veryHidden листы через `sheet state` и активный лист XLSX через `workbookView activeTab`, ячейки, формулы, shared formulas XLSX с относительными ссылками, базовые merged cells, базовые стили, RGB/theme/indexed цвета XLSX с учетом `xl/theme/theme1.xml`, размеры и семейства шрифта, зачеркивание ячеек, горизонтальное и вертикальное выравнивание, перенос текста, границы и цвет границ ячеек, числовые форматы и простые bar/line/pie диаграммы ячеек XLSX, текстовые слайды PPTX с переносами абзацев и ручными переносами строк `a:br` при импорте, пользовательский фон слайдов PPTX, цвет, размер и семейство шрифта текста заголовка/подзаголовка PPTX, импорт и экспорт заметок докладчика, адресацию `To/Cc/Bcc`, MIME encoded-word заголовки UTF-8/windows-1251, MIME-вложения EML, inline-вложения EML с `Content-ID` и базовые поля одиночных MSG-писем. Сложные стили, макросы, сложные диаграммы, сложное позиционирование и обтекание изображений, PST, экспорт MSG и полная fidelity документов Microsoft Office в текущем инкременте не заявлены.
+Импорт и экспорт реализуют базовую совместимость с Office Open XML, EML и чтением MSG: текст, базовое inline-форматирование, явные `w:br`, `w:tab`, `w:color`, `w:shd`, `w:highlight`, `w:sz`, `w:rFonts` и `w:strike` для переносов строк/табуляции/цвета/подсветки/размера/семейства/зачеркивания текста DOCX, выравнивание абзацев DOCX, внешние гиперссылки DOCX, внешние и внутренние гиперссылки XLSX, базовые растровые изображения DOCX/PPTX, простые таблицы, несколько листов, скрытые/veryHidden листы через `sheet state`, закрепленные области через `sheetViews pane` и активный лист XLSX через `workbookView activeTab`, ячейки, формулы, shared formulas XLSX с относительными ссылками, базовые merged cells, базовые стили, RGB/theme/indexed цвета XLSX с учетом `xl/theme/theme1.xml`, размеры и семейства шрифта, зачеркивание ячеек, горизонтальное и вертикальное выравнивание, перенос текста, границы и цвет границ ячеек, числовые форматы и простые bar/line/pie диаграммы ячеек XLSX, текстовые слайды PPTX с переносами абзацев и ручными переносами строк `a:br` при импорте, пользовательский фон слайдов PPTX, цвет, размер и семейство шрифта текста заголовка/подзаголовка PPTX, импорт и экспорт заметок докладчика, адресацию `To/Cc/Bcc`, MIME encoded-word заголовки UTF-8/windows-1251, MIME-вложения EML, inline-вложения EML с `Content-ID` и базовые поля одиночных MSG-писем. Сложные стили, макросы, сложные диаграммы, сложное позиционирование и обтекание изображений, PST, экспорт MSG и полная fidelity документов Microsoft Office в текущем инкременте не заявлены.

 ## Сборка пакета

@@ -5,6 +5,7 @@ import {
  buildCellXml,
  buildHyperlinksXml,
  buildMergeCellsXml,
+  buildSheetViewsXml,
  createCellStyleRegistry,
  buildWorksheetRelationshipsXml,
  buildWorksheetXml,
@@ -17,6 +18,7 @@ import {
  workbookSheetRefs,
  worksheetXmlToCells,
  worksheetXmlToCellFormats,
+  worksheetXmlToFrozenPane,
  worksheetXmlToHyperlinks,
  worksheetXmlToMergedCells,
  xlsxStylesXmlToCellFormatTable,
@@ -587,6 +589,60 @@ describe("excellOffice OOXML helpers", () => {
    expect(imported.sheets[2]).toMatchObject({ id: "sheet-3", name: "Служебный", visibility: "veryHidden" });
  });

+  it("читает и записывает закрепленные области XLSX через sheetViews pane", async () => {
+    expect(
+      worksheetXmlToFrozenPane({
+        worksheet: {
+          sheetViews: {
+            sheetView: {
+              pane: { xSplit: "1", ySplit: "2", topLeftCell: "B3", activePane: "bottomRight", state: "frozen" }
+            }
+          }
+        }
+      })
+    ).toEqual({ columns: 1, rows: 2, topLeftCell: "B3", activePane: "bottomRight" });
+
+    expect(
+      worksheetXmlToFrozenPane({
+        worksheet: {
+          sheetViews: {
+            sheetView: {
+              pane: { xSplit: "1", state: "split" }
+            }
+          }
+        }
+      })
+    ).toBeUndefined();
+
+    expect(buildSheetViewsXml({ columns: 1, rows: 1 })).toBe(
+      '<sheetViews><sheetView workbookViewId="0"><pane xSplit="1" ySplit="1" topLeftCell="B2" activePane="bottomRight" state="frozen"/></sheetView></sheetViews>'
+    );
+
+    const blob = await exportXlsxBlob({
+      id: "book-1",
+      title: "Frozen panes.xlsx",
+      updatedAt: "2026-06-01T00:00:00.000Z",
+      activeSheet: "sheet-1",
+      sheets: [
+        {
+          id: "sheet-1",
+          name: "Freeze",
+          frozenPane: { columns: 1, rows: 1 },
+          cells: { A1: "Header", B2: "Body" }
+        }
+      ]
+    });
+    const zip = await JSZip.loadAsync(await blob.arrayBuffer());
+    const sheetXml = (await zip.file("xl/worksheets/sheet1.xml")?.async("string")) ?? "";
+    const imported = await importXlsxFile(new File([blob], "Frozen panes.xlsx", { type: blob.type }));
+
+    expect(sheetXml).toContain(
+      '<sheetViews><sheetView workbookViewId="0"><pane xSplit="1" ySplit="1" topLeftCell="B2" activePane="bottomRight" state="frozen"/></sheetView></sheetViews>'
+    );
+    expect(sheetXml.indexOf("<sheetViews>")).toBeLessThan(sheetXml.indexOf("<sheetData>"));
+    expect(imported.sheets[0].frozenPane).toEqual({ columns: 1, rows: 1, topLeftCell: "B2", activePane: "bottomRight" });
+  });
+
  it("создает OOXML chart part для диаграммы XLSX", () => {
    const xml = buildChartXml(
      {
@@ -1,4 +1,4 @@
-import type { CellFormat, MergedCellRange, SheetChart, SheetChartType, Workbook } from "../types";
+import type { CellFormat, MergedCellRange, SheetChart, SheetChartType, SheetFrozenPane, Workbook } from "../types";
 import { evaluateCell, expandRange } from "../utils/spreadsheet";
 import { officeTitleFromFileName, readOfficeFileAsArrayBuffer, XLSX_MIME_TYPE } from "./fileHelpers";

@@ -9,6 +9,7 @@ export interface ImportedExcellWorkbook {
    id: string;
    name: string;
    visibility?: "hidden" | "veryHidden";
+    frozenPane?: SheetFrozenPane;
    cells: Record<string, string>;
    mergedCells?: MergedCellRange[];
    hyperlinks?: Record<string, string>;
@@ -56,6 +57,7 @@ interface ParsedSheet {
  id: string;
  name: string;
  visibility?: "hidden" | "veryHidden";
+  frozenPane?: SheetFrozenPane;
  cells: Record<string, string>;
  mergedCells?: MergedCellRange[];
  hyperlinks?: Record<string, string>;
@@ -63,6 +65,13 @@ interface ParsedSheet {
  charts?: SheetChart[];
 }

+type NormalizedFrozenPane = {
+  columns: number;
+  rows: number;
+  topLeftCell: string;
+  activePane: NonNullable<SheetFrozenPane["activePane"]>;
+};
+
 interface WorksheetCellRecord {
  address: string;
  cell: XmlRecord;
@@ -245,7 +254,7 @@ export async function exportXlsxBlob(workbook: Workbook): Promise<Blob> {
    const drawingRelationshipId = sheetChartParts.length > 0 ? `rId${sortedExternalHyperlinkEntries(sheet.hyperlinks).length + 1}` : "";
    zip.file(
      `xl/worksheets/sheet${index + 1}.xml`,
-      buildWorksheetXml(sheet.cells, sheet.mergedCells, sheet.hyperlinks, sheet.cellFormats, styleRegistry, drawingRelationshipId)
+      buildWorksheetXml(sheet.cells, sheet.mergedCells, sheet.hyperlinks, sheet.cellFormats, styleRegistry, drawingRelationshipId, sheet.frozenPane)
    );
    const relationshipsXml = buildWorksheetRelationshipsXml(
      sheet.hyperlinks,
@@ -276,10 +285,13 @@ export function parsedWorksheetToSheet(
  relationshipsXml?: unknown,
  styleTable: Array<CellFormat | undefined> = []
 ): ParsedSheet {
+  const frozenPane = worksheetXmlToFrozenPane(worksheetXml);
+
  return {
    id: sheet.id || `sheet-${index + 1}`,
    name: sheet.name || `Лист ${index + 1}`,
    ...(sheet.visibility ? { visibility: sheet.visibility } : {}),
+    ...(frozenPane ? { frozenPane } : {}),
    cells: worksheetXmlToCells(worksheetXml, sharedStrings),
    mergedCells: worksheetXmlToMergedCells(worksheetXml),
    hyperlinks: worksheetXmlToHyperlinks(worksheetXml, relationshipsXml),
@@ -371,6 +383,33 @@ export function worksheetXmlToHyperlinks(worksheetXml: unknown, relationshipsXml
  }, {});
 }

+export function worksheetXmlToFrozenPane(worksheetXml: unknown): SheetFrozenPane | undefined {
+  const worksheet = childRecord(worksheetXml, "worksheet");
+  const sheetViews = childRecord(worksheet, "sheetViews");
+  const sheetView = asRecord(toArray(sheetViews.sheetView)[0]);
+  const pane = childRecord(sheetView, "pane");
+  const state = String(pane.state ?? "").trim().toLowerCase();
+  if (state !== "frozen" && state !== "frozensplit") {
+    return undefined;
+  }
+
+  const columns = paneSplitCount(pane.xSplit);
+  const rows = paneSplitCount(pane.ySplit);
+  if (columns === 0 && rows === 0) {
+    return undefined;
+  }
+
+  const topLeftCell = normalizeCellAddress(String(pane.topLeftCell ?? "")) || frozenPaneTopLeftCell(columns, rows);
+  const activePane = normalizedFrozenPaneActivePane(pane.activePane) || frozenPaneActivePane(columns, rows);
+
+  return {
+    ...(columns > 0 ? { columns } : {}),
+    ...(rows > 0 ? { rows } : {}),
+    topLeftCell,
+    activePane
+  };
+}
+
 async function worksheetXmlToCharts(
  zip: ZipInstance,
  parser: InstanceType<XmlParserConstructor>,
@@ -541,7 +580,8 @@ export function buildWorksheetXml(
  hyperlinks: Record<string, string> = {},
  cellFormats: Record<string, CellFormat> = {},
  styleRegistry = createCellStyleRegistry([cellFormats]),
-  drawingRelationshipId = ""
+  drawingRelationshipId = "",
+  frozenPane?: SheetFrozenPane
 ) {
  const rows = sortedWorksheetEntries(cells, cellFormats).reduce<Record<number, Array<[string, string]>>>((grouped, entry) => {
    const rowNumber = cellRowNumber(entry[0]);
@@ -562,9 +602,10 @@ export function buildWorksheetXml(
  const mergeCellsXml = buildMergeCellsXml(mergedCells);
  const hyperlinksXml = buildHyperlinksXml(hyperlinks);
  const drawingXml = drawingRelationshipId ? `<drawing r:id="${escapeXmlAttribute(drawingRelationshipId)}"/>` : "";
+  const sheetViewsXml = buildSheetViewsXml(frozenPane);

  return xmlDeclaration(
-    `<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheetData>${rowXml}</sheetData>${mergeCellsXml}${hyperlinksXml}${drawingXml}</worksheet>`
+    `<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">${sheetViewsXml}<sheetData>${rowXml}</sheetData>${mergeCellsXml}${hyperlinksXml}${drawingXml}</worksheet>`
  );
 }

@@ -621,6 +662,25 @@ export function buildHyperlinksXml(hyperlinks: Record<string, string> = {}) {
  return `<hyperlinks>${hyperlinkXml}</hyperlinks>`;
 }

+export function buildSheetViewsXml(frozenPane?: SheetFrozenPane) {
+  const pane = normalizedFrozenPane(frozenPane);
+  if (!pane) {
+    return "";
+  }
+
+  const attributes = [
+    pane.columns > 0 ? `xSplit="${pane.columns}"` : "",
+    pane.rows > 0 ? `ySplit="${pane.rows}"` : "",
+    `topLeftCell="${escapeXmlAttribute(pane.topLeftCell)}"`,
+    `activePane="${pane.activePane}"`,
+    'state="frozen"'
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return `<sheetViews><sheetView workbookViewId="0"><pane ${attributes}/></sheetView></sheetViews>`;
+}
+
 export function buildWorksheetRelationshipsXml(hyperlinks: Record<string, string> = {}, drawingTarget = "") {
  const refs = sortedExternalHyperlinkEntries(hyperlinks);
  if (refs.length === 0 && !drawingTarget) {
@@ -1305,6 +1365,45 @@ function numberAttribute(value: unknown) {
  return Number.isInteger(number) && number >= 0 ? number : 0;
 }

+function normalizedFrozenPane(pane?: SheetFrozenPane): NormalizedFrozenPane | null {
+  const columns = paneSplitCount(pane?.columns);
+  const rows = paneSplitCount(pane?.rows);
+  if (columns === 0 && rows === 0) {
+    return null;
+  }
+
+  const topLeftCell = normalizeCellAddress(pane?.topLeftCell ?? "") || frozenPaneTopLeftCell(columns, rows);
+  const activePane = normalizedFrozenPaneActivePane(pane?.activePane) || frozenPaneActivePane(columns, rows);
+
+  return {
+    columns,
+    rows,
+    topLeftCell,
+    activePane
+  };
+}
+
+function paneSplitCount(value: unknown) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;
+}
+
+function frozenPaneTopLeftCell(columns: number, rows: number) {
+  return cellAddress(columns + 1, rows + 1);
+}
+
+function frozenPaneActivePane(columns: number, rows: number): NormalizedFrozenPane["activePane"] {
+  if (columns > 0 && rows > 0) {
+    return "bottomRight";
+  }
+
+  return columns > 0 ? "topRight" : "bottomLeft";
+}
+
+function normalizedFrozenPaneActivePane(value: unknown): NormalizedFrozenPane["activePane"] | "" {
+  return value === "topRight" || value === "bottomLeft" || value === "bottomRight" ? value : "";
+}
+
 async function readSharedStrings(zip: ZipInstance, parser: InstanceType<XmlParserConstructor>) {
  const sharedStringsFile = zip.file("xl/sharedStrings.xml");
  if (!sharedStringsFile) {
@@ -19,6 +19,7 @@ export interface Sheet {
  id: string;
  name: string;
  visibility?: "hidden" | "veryHidden";
+  frozenPane?: SheetFrozenPane;
  cells: Record<string, string>;
  mergedCells?: MergedCellRange[];
  hyperlinks?: Record<string, string>;
@@ -26,6 +27,13 @@ export interface Sheet {
  charts?: SheetChart[];
 }

+export interface SheetFrozenPane {
+  columns?: number;
+  rows?: number;
+  topLeftCell?: string;
+  activePane?: "topRight" | "bottomLeft" | "bottomRight";
+}
+
 export interface CellFormat {
  bold?: boolean;
  italics?: boolean;