25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
feat(export): add two-row name/comment header mode for XLSX
弈秋0f87ce0b6a4d
diff --git a/apps/desktop/src/components/export/XlsxHeaderDialog.vue b/apps/desktop/src/components/export/XlsxHeaderDialog.vueindex e96fbfe27b..b6f7f76d0f 100644--- a/apps/desktop/src/components/export/XlsxHeaderDialog.vue+++ b/apps/desktop/src/components/export/XlsxHeaderDialog.vue@@ -56,6 +56,11 @@ function onOpenChange(value: boolean) {<input type="radio" v-model="selected" value="name-comment" class="h-4 w-4" /><span class="text-sm">{{ t("grid.xlsxHeaderNameAndComment") }}</span></label>+ <label class="flex items-center gap-2 cursor-pointer">+ <input type="radio" v-model="selected" value="name-comment-rows" class="h-4 w-4" />+ <span class="text-sm">{{ t("grid.xlsxHeaderNameAndCommentRows") }}</span>+ </label>+ <p v-if="selected === 'name-comment-rows'" class="text-xs text-muted-foreground">{{ t("grid.xlsxHeaderNameAndCommentRowsHint") }}</p></div></div><div class="space-y-3">diff --git a/apps/desktop/src/components/objects/ObjectBrowser.vue b/apps/desktop/src/components/objects/ObjectBrowser.vueindex 7eefb48917..1025c2130e 100644--- a/apps/desktop/src/components/objects/ObjectBrowser.vue+++ b/apps/desktop/src/components/objects/ObjectBrowser.vue@@ -105,7 +105,7 @@ import { buildRenameObjectSql, supportsObjectRename } from "@/lib/table/objectReimport { isTauriRuntime } from "@/lib/backend/tauriRuntime";import { autoRevealExportedPathIfConfigured, promptExportSavePath } from "@/lib/export/exportPath";import { generateDatabaseExportId } from "@/lib/export/databaseExport";-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";import { showSqlInsertModeDialog, type SqlInsertDialect, type SqlInsertMode } from "@/lib/export/sqlInsertMode";import { csvNullLiteralForMode } from "@/lib/export/csvNullMode";import { copyToClipboard, eventTargetAllowsAppClipboardShortcut } from "@/lib/common/clipboard";@@ -2535,7 +2535,7 @@ async function exportTableData(row: ObjectBrowserRow, format: "csv" | "xlsx" | "} else {const comments = result.columns.map((name) => columnInfos?.find((column) => column.name.toLocaleLowerCase() === name.toLocaleLowerCase())?.comment);const headerOverrides = buildXlsxHeaderOverrides(result.columns, comments, headerMode);- await api.exportQueryResultXlsx(filePath, row.name, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined);+ await api.exportQueryResultXlsx(filePath, row.name, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined, xlsxHeaderUsesCommentRows(headerMode));}toast(t("grid.exported"));void autoRevealExportedPathIfConfigured(filePath);@@ -2582,6 +2582,7 @@ async function exportTableData(row: ObjectBrowserRow, format: "csv" | "xlsx" | "nullLiteral: csvNullLiteralForMode(settingsStore.editorSettings.csvNullMode),columns,columnComments: format === "xlsx" ? columnComments : undefined,+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,autoFilter: format === "xlsx" ? autoFilter : undefined,batchSize: settingsStore.editorSettings.exportBatchSize,skipCount: format === "sql",diff --git a/apps/desktop/src/composables/useDataGridExport.ts b/apps/desktop/src/composables/useDataGridExport.tsindex 4838cbb106..119bbf9363 100644--- a/apps/desktop/src/composables/useDataGridExport.ts+++ b/apps/desktop/src/composables/useDataGridExport.ts@@ -37,7 +37,7 @@ import { formatTemporalRowsForExport } from "@/lib/dataGrid/columnFormatter";import { translateBackendError } from "@/i18n/backend-errors";import XlsxHeaderDialog from "@/components/export/XlsxHeaderDialog.vue";import i18n from "@/i18n";-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";/*** Format metadata for backend table exports. Each entry maps a format key@@ -588,7 +588,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {return resultPageSql?.value || currentExportSql();}- async function writeXlsxResult(outputPath: string, result: { columns: string[]; columnTypes: string[]; columnComments?: (string | null)[]; rows: CellValue[][] }, includeSqlSheet: boolean, autoFilter: boolean, sqlOverride?: string) {+ async function writeXlsxResult(outputPath: string, result: { columns: string[]; columnTypes: string[]; columnComments?: (string | null)[]; rows: CellValue[][] }, includeSqlSheet: boolean, autoFilter: boolean, sqlOverride?: string, headerCommentRows = false) {const effectiveSql = sqlOverride ?? currentExportSql();const sqlWorksheet = includeSqlSheet ? buildXlsxSqlWorksheet([{ sql: effectiveSql || "" }]) : undefined;const rightAlign = useSettingsStore().editorSettings.numericColumnRightAlign;@@ -597,7 +597,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {// a `SSS` pattern silently displays as `yyyy-mm-dd hh:mm:ss`.const dateTimeFormat = useSettingsStore().editorSettings.globalDateTimeExportFormat || undefined;if (!sqlWorksheet) {- await api.exportQueryResultXlsx(outputPath, currentXlsxSheetName(), result.columns, result.columnTypes, result.columnComments, result.rows, rightAlign, autoFilter, dateTimeFormat);+ await api.exportQueryResultXlsx(outputPath, currentXlsxSheetName(), result.columns, result.columnTypes, result.columnComments, result.rows, rightAlign, autoFilter, dateTimeFormat, headerCommentRows);return;}await api.exportQueryResultsXlsx(@@ -611,6 +611,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {rows: result.rows,numericColumnRightAlign: rightAlign,autoFilter,+ headerCommentRows,},{ ...sqlWorksheet, autoFilter: false },],@@ -1272,7 +1273,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {totalRows: result.rows.length,};}- await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter);+ await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, undefined, xlsxHeaderUsesCommentRows(exportOptions.headerMode));if (needsFullExport && exportProgressState) {exportProgressState.value = {...exportProgressState.value,@@ -1332,7 +1333,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {outputPath = path;}const result = await resultToExport({ columnIndexes }, undefined, false, true, exportOptions.headerMode);- await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, currentPageExportSql());+ await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, currentPageExportSql(), xlsxHeaderUsesCommentRows(exportOptions.headerMode));notifyExportSuccess(outputPath);} catch (e: any) {toast(t("grid.exportFailed", { message: translateBackendError(t, e) }), 5000);@@ -1378,6 +1379,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {rows: formatTemporalRowsForExport(sheet.result.rows, sheet.result.column_types ?? [], exportPattern),numericColumnRightAlign: rightAlign,autoFilter: exportOptions.autoFilter,+ headerCommentRows: xlsxHeaderUsesCommentRows(exportOptions.headerMode),}));const sqlWorksheet = includeSqlSheet ? buildXlsxSqlWorksheet(sheets.map((sheet) => ({ resultName: sheet.sheetName, sql: sheet.sql || sheet.result.sourceStatement || "" }))) : undefined;await api.exportQueryResultsXlsx(outputPath, sqlWorksheet ? [...worksheets, { ...sqlWorksheet, autoFilter: false }] : worksheets, exportOptions.autoFilter, exportPattern || undefined);@@ -1516,6 +1518,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {columnTypes: columnTypes.value,...(format === "sql" ? { columnExtras: sqlExportColumnExtras(effectiveColumns(sourceColumns.value, columns.value).map((column, index) => column ?? columns.value[index]!)) } : {}),columnComments: format === "xlsx" ? buildXlsxHeaderOverrides(columns.value, visibleXlsxColumnComments.value, headerMode) : undefined,+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,primaryKeys: meta.primaryKeys,...sqlExportPrimaryKeyOptions(),whereInput: whereInput.value,@@ -1603,6 +1606,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {...(format === "sql" && sqlExportOptions ? { insertMode: sqlExportOptions.insertMode } : {}),});const columnComments = format === "xlsx" ? buildXlsxHeaderOverrides(allColumns.value, allXlsxColumnComments.value, headerMode) : undefined;+ const headerCommentRows = format === "xlsx" && xlsxHeaderUsesCommentRows(headerMode);const request = baseRequest? {...baseRequest,@@ -1613,6 +1617,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {dateTimeFormat: useSettingsStore().editorSettings.globalDateTimeExportFormat || undefined,numericColumnRightAlign: useSettingsStore().editorSettings.numericColumnRightAlign ?? true,columnComments,+ headerCommentRows,autoFilter: format === "xlsx" ? autoFilter : undefined,}: undefined;diff --git a/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts b/apps/desktop/src/composables/useSidebarTreeExportRuntime.tsindex 603caa9aa2..65de957cbc 100644--- a/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts+++ b/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts@@ -20,7 +20,7 @@ import { sidebarStructureExportTargets, sidebarTableDataExportTargets } from "@/import { fetchTableDataForExport } from "@/lib/table/tableDataExport";import { dropsSchemaQualifier } from "@/lib/table/tableSelectSql";import XlsxHeaderDialog from "@/components/export/XlsxHeaderDialog.vue";-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";import {isLoadingStructurePreview,showStructureDocCopyDialog,@@ -489,7 +489,18 @@ export function useSidebarTreeExportRuntime(options: SidebarTreeExportRuntimeOpt} else {const comments = result.columns.map((name) => exportColumnInfos?.find((column) => column.name.toLocaleLowerCase() === name.toLocaleLowerCase())?.comment);const headerOverrides = buildXlsxHeaderOverrides(result.columns, comments, headerMode);- await api.exportQueryResultXlsx(outputPath, target.tableName, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined);+ await api.exportQueryResultXlsx(+ outputPath,+ target.tableName,+ result.columns,+ result.column_types ?? result.columns.map(() => ""),+ headerOverrides,+ result.rows,+ undefined,+ autoFilter,+ settingsStore.editorSettings.globalDateTimeExportFormat || undefined,+ xlsxHeaderUsesCommentRows(headerMode),+ );}currentTask.status = "Done";currentTask.rowsExported = result.rows.length;@@ -531,6 +542,7 @@ export function useSidebarTreeExportRuntime(options: SidebarTreeExportRuntimeOptnullLiteral: target.nullLiteral,columns: queryColumns,columnComments,+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,autoFilter: format === "xlsx" ? autoFilter : undefined,primaryKeys,excludePrimaryKeys: settingsStore.editorSettings.dataGridExtractorOptions.sql.excludePrimaryKeysFromInsert === true,diff --git a/apps/desktop/src/i18n/locales/az.ts b/apps/desktop/src/i18n/locales/az.tsindex da7c0793bf..e5602966a8 100644--- a/apps/desktop/src/i18n/locales/az.ts+++ b/apps/desktop/src/i18n/locales/az.ts@@ -1985,6 +1985,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Sütun adlarından başlıq kimi istifadə et",xlsxHeaderComment: "Sütun şərhlərindən başlıq kimi istifadə et",xlsxHeaderNameAndComment: "Sütun adlarından və şərhlərindən başlıq kimi istifadə et",+ xlsxHeaderNameAndCommentRows: "Sütun adları və şərhləri iki başlıq sətrində istifadə et",+ xlsxHeaderNameAndCommentRowsHint: "1-ci sətirdə sütun adları, 2-ci sətirdə şərhlər yer alır, məlumatlar 3-cü sətirdən başlayır. Yenidən idxal etməzdən əvvəl şərh sətrini silərək sütun adları ilə uyğunlaşdıra bilərsiniz.",xlsxFilterPrompt: "İxrac edilən Excel faylına süzgəclərin daxil edilib-edilməyəcəyini seçin:",xlsxIncludeAutoFilter: "Süzgəcləri daxil et",copied: "Kopyalandı",diff --git a/apps/desktop/src/i18n/locales/en.ts b/apps/desktop/src/i18n/locales/en.tsindex 2b2a6ceca2..95293e8f69 100644--- a/apps/desktop/src/i18n/locales/en.ts+++ b/apps/desktop/src/i18n/locales/en.ts@@ -2422,6 +2422,8 @@ export default {xlsxHeaderOriginal: "Use column names as headers",xlsxHeaderComment: "Use column comments as headers",xlsxHeaderNameAndComment: "Use column names and comments as headers",+ xlsxHeaderNameAndCommentRows: "Use column names and comments as two header rows",+ xlsxHeaderNameAndCommentRowsHint: "Row 1 keeps the column names, row 2 lists the comments, and data starts at row 3 — delete the comment row before re-importing to match the column names.",xlsxFilterPrompt: "Choose whether the exported Excel file includes filters:",xlsxIncludeAutoFilter: "Include filters",copied: "Copied",diff --git a/apps/desktop/src/i18n/locales/es.ts b/apps/desktop/src/i18n/locales/es.tsindex 9ecf3aebb3..32eb2a0752 100644--- a/apps/desktop/src/i18n/locales/es.ts+++ b/apps/desktop/src/i18n/locales/es.ts@@ -2932,6 +2932,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Encabezado usando nombres de campos",xlsxHeaderComment: "Encabezado usando comentarios",xlsxHeaderNameAndComment: "Encabezado usando nombres de campos y comentarios",+ xlsxHeaderNameAndCommentRows: "Usar nombres y comentarios como dos filas de encabezado",+ xlsxHeaderNameAndCommentRowsHint: "La fila 1 contiene los nombres de los campos, la fila 2 los comentarios y los datos empiezan en la fila 3; elimina la fila de comentarios antes de reimportar para alinear con los nombres.",xlsxFilterPrompt: "Seleccione si el Excel exportado incluye filtros:",xlsxIncludeAutoFilter: "Incluir filtros",jumpToPage: "Ir a la página",diff --git a/apps/desktop/src/i18n/locales/id.ts b/apps/desktop/src/i18n/locales/id.tsindex 479ad8bf06..1da84fa966 100644--- a/apps/desktop/src/i18n/locales/id.ts+++ b/apps/desktop/src/i18n/locales/id.ts@@ -2257,6 +2257,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Gunakan nama kolom sebagai header",xlsxHeaderComment: "Gunakan komentar kolom sebagai header",xlsxHeaderNameAndComment: "Gunakan nama dan komentar kolom sebagai header",+ xlsxHeaderNameAndCommentRows: "Gunakan nama dan komentar sebagai dua baris header",+ xlsxHeaderNameAndCommentRowsHint: "Baris 1 berisi nama kolom, baris 2 komentar, dan data mulai dari baris 3. Hapus baris komentar sebelum mengimpor ulang agar sesuai dengan nama kolom.",xlsxFilterPrompt: "Pilih apakah file Excel yang diekspor menyertakan filter:",xlsxIncludeAutoFilter: "Sertakan filter",copied: "Disalin",diff --git a/apps/desktop/src/i18n/locales/it.ts b/apps/desktop/src/i18n/locales/it.tsindex d23fa94f2b..e109e4ecaf 100644--- a/apps/desktop/src/i18n/locales/it.ts+++ b/apps/desktop/src/i18n/locales/it.ts@@ -2805,6 +2805,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Intestazione con nome campo",xlsxHeaderComment: "Intestazione con commento",xlsxHeaderNameAndComment: "Intestazione con nome campo e commento",+ xlsxHeaderNameAndCommentRows: "Usa nomi dei campi e commenti come due righe di intestazione",+ xlsxHeaderNameAndCommentRowsHint: "La riga 1 contiene i nomi dei campi, la riga 2 i commenti e i dati iniziano dalla riga 3; elimina la riga dei commenti prima di reimportare per allinearti ai nomi.",xlsxFilterPrompt: "Scegli se il file Excel esportato include filtri:",xlsxIncludeAutoFilter: "Includi filtri",jumpToPage: "Vai alla pagina",diff --git a/apps/desktop/src/i18n/locales/ja.ts b/apps/desktop/src/i18n/locales/ja.tsindex ba7af5c86c..295468002f 100644--- a/apps/desktop/src/i18n/locales/ja.ts+++ b/apps/desktop/src/i18n/locales/ja.ts@@ -2820,6 +2820,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "ヘッダーにフィールド名を使用",xlsxHeaderComment: "ヘッダーにコメントを使用",xlsxHeaderNameAndComment: "ヘッダーにフィールド名とコメントを使用",+ xlsxHeaderNameAndCommentRows: "フィールド名とコメントを2行のヘッダーに分ける",+ xlsxHeaderNameAndCommentRowsHint: "1行目にフィールド名、2行目にコメント、データは3行目から始まります。再インポート時にコメント行を削除すればフィールド名が一致します。",xlsxFilterPrompt: "エクスポートする Excel にフィルターを含めるか選択してください:",xlsxIncludeAutoFilter: "フィルターを含める",searchMode: "検索モード",diff --git a/apps/desktop/src/i18n/locales/ko.ts b/apps/desktop/src/i18n/locales/ko.tsindex c257855823..197e586c63 100644--- a/apps/desktop/src/i18n/locales/ko.ts+++ b/apps/desktop/src/i18n/locales/ko.ts@@ -2764,6 +2764,8 @@ export default withEnglishFallback({xlsxExportTitle: "내보내기 옵션",xlsxFilterPrompt: "내보낸 Excel에 필터를 포함할지 선택하십시오:",xlsxIncludeAutoFilter: "필터 포함",+ xlsxHeaderNameAndCommentRows: "필드 이름과 주석을 두 헤더 행으로 사용",+ xlsxHeaderNameAndCommentRowsHint: "1행은 필드 이름, 2행은 주석이며 데이터는 3행부터 시작합니다. 다시 가져오기 전에 주석 행을 삭제하면 필드 이름과 일치합니다.",batchAppendPasteNoMatchingColumns: "INSERT 문의 열 이름이 현재 결과 집합의 어떤 열과도 일치하지 않습니다.",},exportProgress: {diff --git a/apps/desktop/src/i18n/locales/pt-BR.ts b/apps/desktop/src/i18n/locales/pt-BR.tsindex 34b65e6c3c..782b17f8d7 100644--- a/apps/desktop/src/i18n/locales/pt-BR.ts+++ b/apps/desktop/src/i18n/locales/pt-BR.ts@@ -2805,6 +2805,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Cabeçalho usa nome do campo",xlsxHeaderComment: "Cabeçalho usa comentário",xlsxHeaderNameAndComment: "Cabeçalho usa nome do campo e comentário",+ xlsxHeaderNameAndCommentRows: "Usar nomes e comentários como duas linhas de cabeçalho",+ xlsxHeaderNameAndCommentRowsHint: "A linha 1 mantém os nomes dos campos, a linha 2 os comentários e os dados começam na linha 3; exclua a linha de comentários antes de reimportar para alinhar com os nomes.",xlsxFilterPrompt: "Selecione se o Excel exportado inclui filtros:",xlsxIncludeAutoFilter: "Incluir filtros",jumpToPage: "Ir para a página",diff --git a/apps/desktop/src/i18n/locales/ru.ts b/apps/desktop/src/i18n/locales/ru.tsindex 2a24283c63..29a8646431 100644--- a/apps/desktop/src/i18n/locales/ru.ts+++ b/apps/desktop/src/i18n/locales/ru.ts@@ -2320,6 +2320,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Использовать имена столбцов как заголовки",xlsxHeaderComment: "Использовать комментарии столбцов как заголовки",xlsxHeaderNameAndComment: "Использовать имена и комментарии столбцов как заголовки",+ xlsxHeaderNameAndCommentRows: "Имена и комментарии в двух строках заголовка",+ xlsxHeaderNameAndCommentRowsHint: "Строка 1 — имена столбцов, строка 2 — комментарии, данные начинаются со строки 3. Перед повторным импортом удалите строку комментариев, чтобы выровнять имена.",xlsxFilterPrompt: "Выберите, включать ли фильтры в экспортируемый файл Excel:",xlsxIncludeAutoFilter: "Включить фильтры",copied: "Скопировано",diff --git a/apps/desktop/src/i18n/locales/tr.ts b/apps/desktop/src/i18n/locales/tr.tsindex f35a76147d..fbff073fc1 100644--- a/apps/desktop/src/i18n/locales/tr.ts+++ b/apps/desktop/src/i18n/locales/tr.ts@@ -1978,6 +1978,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "Başlık olarak sütun adlarını kullan",xlsxHeaderComment: "Başlık olarak sütun açıklamalarını kullan",xlsxHeaderNameAndComment: "Başlık olarak sütun adlarını ve açıklamalarını kullan",+ xlsxHeaderNameAndCommentRows: "Alan adları ve açıklamaları iki başlık satırı olarak kullan",+ xlsxHeaderNameAndCommentRowsHint: "1. satırda alan adları, 2. satırda açıklamalar yer alır ve veriler 3. satırdan başlar. Yeniden içe aktarmadan önce açıklama satırını silerek alan adlarıyla eşleştirebilirsiniz.",xlsxFilterPrompt: "Dışa aktarılan Excel dosyasının filtre içerip içermeyeceğini seçin:",xlsxIncludeAutoFilter: "Filtreleri dâhil et",copied: "Kopyalandı",diff --git a/apps/desktop/src/i18n/locales/zh-CN.ts b/apps/desktop/src/i18n/locales/zh-CN.tsindex c903e7c08a..4969d7f7b0 100644--- a/apps/desktop/src/i18n/locales/zh-CN.ts+++ b/apps/desktop/src/i18n/locales/zh-CN.ts@@ -2356,6 +2356,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "表头使用字段名称",xlsxHeaderComment: "表头使用注释",xlsxHeaderNameAndComment: "表头使用字段名称 + 注释",+ xlsxHeaderNameAndCommentRows: "字段名称与注释分两行表头",+ xlsxHeaderNameAndCommentRowsHint: "第 1 行为字段名称,第 2 行为注释,数据从第 3 行开始;重新导入前删除注释行即可对齐字段名称。",xlsxFilterPrompt: "请选择是否在导出的 Excel 中包含筛选:",xlsxIncludeAutoFilter: "包含筛选",copied: "已复制",diff --git a/apps/desktop/src/i18n/locales/zh-TW.ts b/apps/desktop/src/i18n/locales/zh-TW.tsindex 27d8960441..e549694f57 100644--- a/apps/desktop/src/i18n/locales/zh-TW.ts+++ b/apps/desktop/src/i18n/locales/zh-TW.ts@@ -2815,6 +2815,8 @@ export default withEnglishFallback({xlsxHeaderOriginal: "表頭使用欄位名稱",xlsxHeaderComment: "表頭使用註解",xlsxHeaderNameAndComment: "表頭使用欄位名稱 + 註解",+ xlsxHeaderNameAndCommentRows: "欄位名稱與註解分兩列表頭",+ xlsxHeaderNameAndCommentRowsHint: "第 1 列為欄位名稱,第 2 列為註解,資料從第 3 列開始;重新匯入前刪除註解列即可對齊欄位名稱。",xlsxFilterPrompt: "請選擇匯出的 Excel 是否包含篩選:",xlsxIncludeAutoFilter: "包含篩選",cut: "已剪下",diff --git a/apps/desktop/src/lib/backend/http.ts b/apps/desktop/src/lib/backend/http.tsindex 3d937c3ad9..5497379a91 100644--- a/apps/desktop/src/lib/backend/http.ts+++ b/apps/desktop/src/lib/backend/http.ts@@ -3510,6 +3510,7 @@ export async function exportQueryResultXlsx(// text the grid already formatted (milliseconds included) and never goes// through a `numFmt` display pattern._dateTimeFormat?: string,+ headerCommentRows?: boolean,): Promise<void> {const { buildXlsxWorkbook } = await import("@/lib/export/xlsxExport");const workbook = buildXlsxWorkbook({@@ -3520,6 +3521,7 @@ export async function exportQueryResultXlsx(rows,numericColumnRightAlign,autoFilter,+ headerCommentRows,});const fileName = filePath.split(/[\\/]/).pop() || "export.xlsx";const blob = new Blob([new Uint8Array(workbook)], {@@ -3543,6 +3545,7 @@ export async function exportQueryResultsXlsx(rows: readonly (readonly XlsxCellValue[])[];numericColumnRightAlign?: boolean;autoFilter?: boolean;+ headerCommentRows?: boolean;}[],autoFilter?: boolean,_dateTimeFormat?: string,diff --git a/apps/desktop/src/lib/backend/tauri.ts b/apps/desktop/src/lib/backend/tauri.tsindex e9281581a3..3f76156e9c 100644--- a/apps/desktop/src/lib/backend/tauri.ts+++ b/apps/desktop/src/lib/backend/tauri.ts@@ -6172,6 +6172,8 @@ export interface TableExportRequest {/** 与 `columns` 对齐的列 EXTRA 元数据(identity 等),用于 SQL INSERT 导出的 `SET IDENTITY_INSERT`。 */columnExtras?: Array<string | null | undefined>;columnComments?: Array<string | null> | null;+ /** xlsx 专用:注释作为第二行表头(第 1 行列名、第 2 行注释、数据从第 3 行开始)。 */+ headerCommentRows?: boolean;primaryKeys?: string[];/** 导出 SQL 时是否排除主键列(对应数据提取设置里的“排除主键”)。 */excludePrimaryKeys?: boolean;@@ -6252,6 +6254,8 @@ export interface QueryResultExportRequest {exportColumnExtras?: Array<string | null | undefined>;numericColumnRightAlign?: boolean;columnComments?: Array<string | null> | null;+ /** xlsx 专用:注释作为第二行表头(第 1 行列名、第 2 行注释、数据从第 3 行开始)。 */+ headerCommentRows?: boolean;autoFilter?: boolean;identifierQuote?: string;/** 导出 SQL 时是否排除主键列(对应数据提取设置里的“排除主键”)。 */@@ -6420,6 +6424,7 @@ export async function exportQueryResultXlsx(numericColumnRightAlign?: boolean,autoFilter?: boolean,dateTimeFormat?: string,+ headerCommentRows?: boolean,): Promise<void> {return invoke("export_query_result_xlsx", {request: {@@ -6432,6 +6437,7 @@ export async function exportQueryResultXlsx(numericColumnRightAlign,autoFilter,dateTimeFormat,+ headerCommentRows,},});}@@ -6446,6 +6452,7 @@ export async function exportQueryResultsXlsx(rows: readonly (readonly XlsxCellValue[])[];numericColumnRightAlign?: boolean;autoFilter?: boolean;+ headerCommentRows?: boolean;}[],autoFilter?: boolean,dateTimeFormat?: string,diff --git a/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts b/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.tsindex 9a7dd30c8a..98c952fb88 100644--- a/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts+++ b/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts@@ -1,5 +1,5 @@import { describe, expect, it } from "vitest";-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments } from "../xlsxHeader";+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows } from "../xlsxHeader";describe("xlsxHeader", () => {it("builds comment-only and combined header overrides", () => {@@ -16,4 +16,18 @@ describe("xlsxHeader", () => {expect(hasXlsxHeaderComments([undefined, " ", "Name"])).toBe(true);expect(hasXlsxHeaderComments([undefined, " "])).toBe(false);});++ it("passes raw comments through for the two-row header mode", () => {+ const columns = ["id", "name", "created_at"];+ const comments = [" Identifier ", "", undefined];++ // The comments ride along as plain data (paired with the headerCommentRows+ // flag) instead of overriding the header text.+ expect(buildXlsxHeaderOverrides(columns, comments, "name-comment-rows")).toEqual(["Identifier", null, null]);+ expect(buildXlsxHeaderOverrides(["id"], [" "], "name-comment-rows")).toBeUndefined();+ expect(xlsxHeaderUsesCommentRows("name-comment-rows")).toBe(true);+ expect(xlsxHeaderUsesCommentRows("name")).toBe(false);+ expect(xlsxHeaderUsesCommentRows("comment")).toBe(false);+ expect(xlsxHeaderUsesCommentRows("name-comment")).toBe(false);+ });});diff --git a/apps/desktop/src/lib/export/xlsxExport.ts b/apps/desktop/src/lib/export/xlsxExport.tsindex c92ba8d582..4697d9d644 100644--- a/apps/desktop/src/lib/export/xlsxExport.ts+++ b/apps/desktop/src/lib/export/xlsxExport.ts@@ -10,6 +10,8 @@ export interface XlsxWorksheetData {rows: readonly (readonly XlsxCellValue[])[];numericColumnRightAlign?: boolean;autoFilter?: boolean;+ /** Render comments as a second header row (names row 1, comments row 2, data from row 3). */+ headerCommentRows?: boolean;}interface XlsxWorksheetSegment {@@ -114,14 +116,18 @@ function normalizeUniqueSheetNames(sheets: readonly { sheetName?: string }[]): sreturn names;}-function estimateColumnWidths(columns: readonly string[], rows: readonly (readonly XlsxCellValue[])[], rowStart: number, rowEnd: number, columnComments?: readonly (string | null)[]): number[] {+function estimateColumnWidths(columns: readonly string[], rows: readonly (readonly XlsxCellValue[])[], rowStart: number, rowEnd: number, columnComments?: readonly (string | null)[], headerCommentRows = false): number[] {return columns.map((column, colIndex) => {- const headerText = columnComments?.[colIndex] || column;+ // With a separate comment row both texts are visible, so the column must+ // fit the wider of the two; otherwise the comment overrides the header.+ const headerText = headerCommentRows ? column : columnComments?.[colIndex] || column;+ const commentText = headerCommentRows ? columnComments?.[colIndex] || "" : "";const isSqlCol = column.toUpperCase() === "SQL";const maxClamp = isSqlCol ? 100 : 60;const values = Array.from({ length: Math.min(100, rowEnd - rowStart) }, (_, index) => rows[rowStart + index]?.[colIndex]);const maxLen = [headerText,+ commentText,...values.map((value) => {if (value == null) return "";const str = String(value);@@ -182,15 +188,19 @@ function worksheetXml(segment: XlsxWorksheetSegment): string {const data = segment.worksheet;const columns = data.columns;const rows = data.rows;- const totalRows = segment.rowEnd - segment.rowStart + 1;+ const hasCommentRow = data.headerCommentRows === true && data.columnComments?.some((comment) => !!comment?.trim());+ const headerRows = hasCommentRow ? 2 : 1;+ const totalRows = segment.rowEnd - segment.rowStart + headerRows;const range = sheetRange(columns.length, totalRows);- const widths = estimateColumnWidths(columns, rows, segment.rowStart, segment.rowEnd, data.columnComments);+ const widths = estimateColumnWidths(columns, rows, segment.rowStart, segment.rowEnd, data.columnComments, hasCommentRow);const rightAlignEnabled = data.numericColumnRightAlign !== false;const colsXml = widths.map((width, index) => `<col min="${index + 1}" max="${index + 1}" width="${width}" customWidth="1"/>`).join("");- const headerXml = `<row r="1">${columns.map((column, index) => cellXml(data.columnComments?.[index] || column, 0, index, 1)).join("")}</row>`;+ const headerXml = `<row r="1">${columns.map((column, index) => cellXml(hasCommentRow ? column : data.columnComments?.[index] || column, 0, index, 1)).join("")}</row>${+ hasCommentRow ? `<row r="2">${columns.map((_, index) => cellXml(data.columnComments?.[index] ?? null, 1, index, 1)).join("")}</row>` : ""+ }`;const bodyXml = Array.from({ length: segment.rowEnd - segment.rowStart }, (_, rowIndex) => {const row = rows[segment.rowStart + rowIndex]!;- const excelRowIndex = rowIndex + 2;+ const excelRowIndex = rowIndex + headerRows + 1;const cells = columns.map((colName, colIndex) => cellXml(row[colIndex], excelRowIndex - 1, colIndex, numericColumnStyle(data.columnTypes?.[colIndex], rightAlignEnabled), data.columnTypes?.[colIndex], colName)).join("");return `<row r="${excelRowIndex}">${cells}</row>`;}).join("");@@ -200,7 +210,7 @@ function worksheetXml(segment: XlsxWorksheetSegment): string {return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><dimension ref="${range}"/>- <sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>+ <sheetViews><sheetView workbookViewId="0"><pane ySplit="${headerRows}" topLeftCell="A${headerRows + 1}" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews><sheetFormatPr defaultRowHeight="15"/><cols>${colsXml}</cols><sheetData>${headerXml}${bodyXml}</sheetData>${autoFilterXml}diff --git a/apps/desktop/src/lib/export/xlsxHeader.ts b/apps/desktop/src/lib/export/xlsxHeader.tsindex afd86c8c3c..b45559428d 100644--- a/apps/desktop/src/lib/export/xlsxHeader.ts+++ b/apps/desktop/src/lib/export/xlsxHeader.ts@@ -1,4 +1,4 @@-export type XlsxHeaderMode = "name" | "comment" | "name-comment";+export type XlsxHeaderMode = "name" | "comment" | "name-comment" | "name-comment-rows";export interface XlsxExportOptions {headerMode: XlsxHeaderMode;@@ -9,8 +9,20 @@ export function hasXlsxHeaderComments(comments: readonly (string | null | undefireturn comments?.some((comment) => !!comment?.trim()) ?? false;}+/** True when the header mode renders comments on a separate second row. */+export function xlsxHeaderUsesCommentRows(mode: XlsxHeaderMode): boolean {+ return mode === "name-comment-rows";+}+export function buildXlsxHeaderOverrides(columns: readonly string[], comments: readonly (string | null | undefined)[] | undefined, mode: XlsxHeaderMode): (string | null)[] | undefined {if (mode === "name") return undefined;+ if (mode === "name-comment-rows") {+ // The comments render as their own header row, so they travel as plain+ // comment data (paired with the headerCommentRows flag) instead of+ // overriding the header text.+ const overrides = columns.map((_, index) => comments?.[index]?.trim() || null);+ return overrides.some((header) => header !== null) ? overrides : undefined;+ }const overrides = columns.map((column, index) => {const comment = comments?.[index]?.trim();diff --git a/crates/dbx-core/examples/data_transfer_bench.rs b/crates/dbx-core/examples/data_transfer_bench.rsindex 9181cbd812..157376aefd 100644--- a/crates/dbx-core/examples/data_transfer_bench.rs+++ b/crates/dbx-core/examples/data_transfer_bench.rs@@ -117,6 +117,7 @@ fn run() -> Result<(), String> {rows,numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,})?;let xlsx_ms = elapsed_ms(xlsx_started);diff --git a/crates/dbx-core/examples/table_import_bench.rs b/crates/dbx-core/examples/table_import_bench.rsindex b1a370166f..265d19705e 100644--- a/crates/dbx-core/examples/table_import_bench.rs+++ b/crates/dbx-core/examples/table_import_bench.rs@@ -103,6 +103,7 @@ fn write_xlsx(path: &Path, row_count: usize, column_count: usize) -> Result<(),rows: (0..row_count).map(|row_index| row(row_index, column_count)).collect(),numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,})?;fs::write(path, workbook).map_err(|error| error.to_string())}diff --git a/crates/dbx-core/examples/table_import_live_bench.rs b/crates/dbx-core/examples/table_import_live_bench.rsindex aa49c20d83..928bf71b32 100644--- a/crates/dbx-core/examples/table_import_live_bench.rs+++ b/crates/dbx-core/examples/table_import_live_bench.rs@@ -274,6 +274,7 @@ fn write_xlsx(path: &Path, row_count: usize, column_count: usize, text_bytes: usrows: (0..row_count).map(|row_index| row(row_index, column_count, text_bytes)).collect(),numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,})?;fs::write(path, workbook).map_err(|error| error.to_string())}diff --git a/crates/dbx-core/src/data/query_result_export.rs b/crates/dbx-core/src/data/query_result_export.rsindex 4507125ad6..fbde86e79b 100644--- a/crates/dbx-core/src/data/query_result_export.rs+++ b/crates/dbx-core/src/data/query_result_export.rs@@ -133,6 +133,10 @@ pub struct QueryResultExportRequest {pub numeric_column_right_align: bool,#[serde(default, skip_serializing_if = "Option::is_none")]pub column_comments: Option<Vec<Option<String>>>,+ /// Render `column_comments` as a second header row (names on row 1,+ /// comments on row 2, data from row 3) instead of overriding headers.+ #[serde(default)]+ pub header_comment_rows: bool,#[serde(default, skip_serializing_if = "Option::is_none")]pub auto_filter: Option<bool>,#[serde(default, skip_serializing_if = "Option::is_none")]@@ -254,6 +258,7 @@ fn query_sql_worksheets(request: &QueryResultExportRequest) -> Vec<XlsxWorksheetrows: split_excel_cell_text(&request.sql).into_iter().map(|sql| vec![Value::String(sql)]).collect(),numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,}]}@@ -275,6 +280,7 @@ fn start_query_result_xlsx_workbook<W: Write + Seek>(request.date_time_format.as_deref(),request.numeric_column_right_align,request.auto_filter.unwrap_or(true),+ request.header_comment_rows,)}@@ -2249,6 +2255,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,identifier_quote: None,insert_mode: SqlInsertMode::Batch,csv_quote_mode: Default::default(),@@ -2341,6 +2348,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,identifier_quote: None,insert_mode: Default::default(),csv_quote_mode: Default::default(),@@ -2430,6 +2438,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,identifier_quote: None,exclude_primary_keys: false,primary_keys: Vec::new(),diff --git a/crates/dbx-core/src/data/table_export.rs b/crates/dbx-core/src/data/table_export.rsindex ae4af06cb6..6c28684c1e 100644--- a/crates/dbx-core/src/data/table_export.rs+++ b/crates/dbx-core/src/data/table_export.rs@@ -124,6 +124,10 @@ pub struct TableExportRequest {pub numeric_column_right_align: bool,#[serde(default, skip_serializing_if = "Option::is_none")]pub column_comments: Option<Vec<Option<String>>>,+ /// Render `column_comments` as a second header row (names on row 1,+ /// comments on row 2, data from row 3) instead of overriding headers.+ #[serde(default)]+ pub header_comment_rows: bool,#[serde(default, skip_serializing_if = "Option::is_none")]pub auto_filter: Option<bool>,/// SQL format only: when set, the export is packaged as a `.zip` archive@@ -1319,6 +1323,7 @@ async fn try_export_native_table_stream(request.date_time_format.as_deref(),request.numeric_column_right_align,request.auto_filter.unwrap_or(true),+ request.header_comment_rows,)?;let result = stream_native_table_rows(state,@@ -2020,6 +2025,7 @@ async fn export_table_data_core_inner(request.date_time_format.as_deref(),request.numeric_column_right_align,request.auto_filter.unwrap_or(true),+ request.header_comment_rows,)?;loop {@@ -2593,6 +2599,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -2762,6 +2769,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -2934,6 +2942,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -2963,6 +2972,7 @@ mod tests {rows: vec![vec![json!(1_700_000_000_000_i64), json!(21.5)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).unwrap();let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");@@ -3000,6 +3010,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3043,6 +3054,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3081,6 +3093,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3127,6 +3140,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3185,6 +3199,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3237,6 +3252,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3317,6 +3333,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3379,6 +3396,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3443,6 +3461,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3499,6 +3518,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: None,};@@ -3544,6 +3564,7 @@ mod tests {numeric_column_right_align: false,column_comments: None,auto_filter: None,+ header_comment_rows: false,split_max_mb: None,omit_database_qualifier: Some(true),};@@ -4218,6 +4239,7 @@ esac"#,],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let workbook = build_xlsx_workbook(&data).expect("XLSX build should succeed");diff --git a/crates/dbx-core/src/data/table_import.rs b/crates/dbx-core/src/data/table_import.rsindex 3344b7ea6c..628e86aa1a 100644--- a/crates/dbx-core/src/data/table_import.rs+++ b/crates/dbx-core/src/data/table_import.rs@@ -9382,6 +9382,7 @@ mod tests {rows: vec![vec![serde_json::json!(""), serde_json::Value::Null]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}]).unwrap();std::fs::write(&path, workbook).unwrap();@@ -10711,6 +10712,7 @@ mod tests {rows: vec![vec![serde_json::json!(1)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},XlsxWorksheetData {sheet_name: Some("Second".to_string()),@@ -10720,6 +10722,7 @@ mod tests {rows: vec![vec![serde_json::json!("Ada")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},]).unwrap();@@ -10759,6 +10762,7 @@ mod tests {rows: vec![vec![serde_json::json!(1)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},XlsxWorksheetData {sheet_name: Some("Second".to_string()),@@ -10768,6 +10772,7 @@ mod tests {rows: vec![vec![serde_json::json!("Ada")], vec![serde_json::json!("Grace")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},]).unwrap();@@ -10982,6 +10987,7 @@ mod tests {],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}]).unwrap();std::fs::write(&path, workbook).unwrap();@@ -11360,6 +11366,7 @@ mod tests {],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}]).unwrap();std::fs::write(&path, workbook).unwrap();@@ -11965,6 +11972,7 @@ mod tests {],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}]).unwrap();std::fs::write(&path, workbook).unwrap();@@ -12065,6 +12073,7 @@ mod tests {],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}]).unwrap();std::fs::write(&path, workbook).unwrap();diff --git a/crates/dbx-core/tests/live_clickhouse_query_result_export.rs b/crates/dbx-core/tests/live_clickhouse_query_result_export.rsindex 9aace93a06..1569123b8d 100644--- a/crates/dbx-core/tests/live_clickhouse_query_result_export.rs+++ b/crates/dbx-core/tests/live_clickhouse_query_result_export.rs@@ -109,6 +109,7 @@ async fn live_clickhouse_query_result_export_xlsx_streams_random_order_query_oncselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,diff --git a/crates/dbx-core/tests/live_mysql57.rs b/crates/dbx-core/tests/live_mysql57.rsindex 2f13313386..37c1c2efff 100644--- a/crates/dbx-core/tests/live_mysql57.rs+++ b/crates/dbx-core/tests/live_mysql57.rs@@ -484,6 +484,7 @@ async fn live_mysql_query_result_export_xlsx_streams_single_query_without_duplicselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -581,6 +582,7 @@ async fn live_mysql_csv_temporal_export_round_trip_preserves_dbx_force_text_valuselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -702,6 +704,7 @@ async fn live_mysql_xlsx_export_can_outlive_query_timeout_while_rows_keep_arriviselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,diff --git a/crates/dbx-core/tests/live_postgres_query_result_export.rs b/crates/dbx-core/tests/live_postgres_query_result_export.rsindex d3f965442c..8a8df4e5ee 100644--- a/crates/dbx-core/tests/live_postgres_query_result_export.rs+++ b/crates/dbx-core/tests/live_postgres_query_result_export.rs@@ -161,6 +161,7 @@ async fn live_postgres_query_result_export_uses_single_streamed_query() {selected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -251,6 +252,7 @@ async fn live_postgres_query_result_xlsx_preserves_temporal_cell_types() {selected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -330,6 +332,7 @@ async fn live_postgres_numeric_xlsx_ignores_fractional_trailing_zeros() {selected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: true,@@ -414,6 +417,7 @@ async fn live_postgres_truncated_batch_result_export_replays_safe_temp_setup() {selected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -501,6 +505,7 @@ async fn live_postgres_xlsx_export_can_outlive_query_timeout_while_rows_keep_arrselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,@@ -578,6 +583,7 @@ async fn live_postgres_stream_still_times_out_without_progress_and_recovers() {selected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,diff --git a/crates/dbx-core/tests/live_sqlserver_completion.rs b/crates/dbx-core/tests/live_sqlserver_completion.rsindex fb8d4aa71c..805c930884 100644--- a/crates/dbx-core/tests/live_sqlserver_completion.rs+++ b/crates/dbx-core/tests/live_sqlserver_completion.rs@@ -530,6 +530,7 @@ async fn live_sqlserver_bulk_imports_zero_fraction_xlsx_numbers_into_bigint() {rows: vec![vec![serde_json::json!(1.0), serde_json::json!("xlsx")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build SQL Server XLSX integer fixture");let path = dir.join("zero-fraction-integer.xlsx");@@ -1231,6 +1232,7 @@ async fn live_sqlserver_query_result_export_streams_cte_query_to_csv() {export_column_extras: None,column_comments: None,auto_filter: None,+ header_comment_rows: false,identifier_quote: None,numeric_column_right_align: false,exclude_primary_keys: false,diff --git a/crates/dbx-core/tests/live_sqlserver_query_result_export.rs b/crates/dbx-core/tests/live_sqlserver_query_result_export.rsindex fe71389980..3045b27e9f 100644--- a/crates/dbx-core/tests/live_sqlserver_query_result_export.rs+++ b/crates/dbx-core/tests/live_sqlserver_query_result_export.rs@@ -140,6 +140,7 @@ async fn live_sqlserver_xlsx_export_can_outlive_query_timeout_while_rows_keep_arselected_columns: None,export_column_extras: None,column_comments: None,+ header_comment_rows: false,auto_filter: None,identifier_quote: None,numeric_column_right_align: false,diff --git a/crates/dbx-formats/src/xlsx_export.rs b/crates/dbx-formats/src/xlsx_export.rsindex de603fad01..96b0298228 100644--- a/crates/dbx-formats/src/xlsx_export.rs+++ b/crates/dbx-formats/src/xlsx_export.rs@@ -53,6 +53,10 @@ pub struct XlsxWorksheetData {pub numeric_column_right_align: bool,#[serde(default)]pub auto_filter: Option<bool>,+ /// Render column comments as a second header row (names on row 1, comments+ /// on row 2, data from row 3) instead of overriding the header text.+ #[serde(default)]+ pub header_comment_rows: bool,}impl XlsxWorksheetData {@@ -65,6 +69,7 @@ impl XlsxWorksheetData {rows,numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}}}@@ -173,6 +178,7 @@ pub struct StreamingXlsxWriter<W: Write + Seek> {trailing_sheets: Vec<XlsxWorksheetData>,width_cache: Vec<usize>,column_comments: Vec<Option<String>>,+ header_comment_rows: bool,date_time_format: Option<String>,numeric_right_align: bool,auto_filter: bool,@@ -182,17 +188,34 @@ pub struct StreamingXlsxWriter<W: Write + Seek> {/// Estimate column widths from header names only (used by the streaming path/// where full row data is not available up-front). Each width is clamped to/// [10, 60] to stay within reasonable bounds.-fn estimate_header_widths(columns: &[String], column_comments: &[Option<String>]) -> Vec<usize> {+fn estimate_header_widths(+ columns: &[String],+ column_comments: &[Option<String>],+ header_comment_rows: bool,+) -> Vec<usize> {columns.iter().enumerate().map(|(index, col)| {let is_sql_col = col.eq_ignore_ascii_case("sql");- let header_text = column_comments.get(index).and_then(|c| c.as_deref()).unwrap_or(col.as_str());+ // With a separate comment row both texts are visible, so the column+ // must fit the wider of the two; otherwise the comment overrides+ // the header text outright.+ let header_text = if header_comment_rows {+ col.as_str()+ } else {+ column_comments.get(index).and_then(|c| c.as_deref()).unwrap_or(col.as_str())+ };+ let comment_len = if header_comment_rows {+ column_comments.get(index).and_then(|c| c.as_deref()).map(str::chars).map(Iterator::count).unwrap_or(0)+ } else {+ 0+ };+ let width = header_text.chars().count().max(comment_len) + 2;if is_sql_col {- (header_text.chars().count() + 2).clamp(40, 100)+ width.clamp(40, 100)} else {- (header_text.chars().count() + 2).clamp(10, 60)+ width.clamp(10, 60)}}).collect()@@ -215,19 +238,48 @@ fn effective_header<'a>(column: &'a str, comment: Option<&'a str>) -> &'a str {comment.filter(|c| !c.is_empty()).unwrap_or(column)}-/// Build a single `<row>` XML fragment for the header row (row 1).-pub fn header_row_xml(columns: &[String], column_comments: &[Option<String>]) -> String {- format!(+/// Number of header rows a sheet renders: 2 when the comments are shown on+/// their own row below the column names, 1 otherwise. Returns 1 even when the+/// flag is set but every comment is empty — an all-empty second row would+/// just shift the data down for nothing.+pub fn header_row_count(column_comments: &[Option<String>], header_comment_rows: bool) -> usize {+ let has_comments = column_comments.iter().any(|comment| comment.as_deref().is_some_and(|c| !c.is_empty()));+ usize::from(header_comment_rows && has_comments) + 1+}++/// Build the `<row>` XML fragment(s) for the header. With `header_comment_rows`+/// the column names stay on row 1 and the comments move to row 2; without it a+/// non-empty comment overrides the header text in row 1 (legacy behavior).+pub fn header_row_xml(columns: &[String], column_comments: &[Option<String>], header_comment_rows: bool) -> String {+ let mut output = format!("<row r=\"1\">{}</row>",columns.iter().enumerate().map(|(index, col)| {- let header = effective_header(col, column_comments.get(index).and_then(|c| c.as_deref()));+ let header = if header_comment_rows {+ col.as_str()+ } else {+ effective_header(col, column_comments.get(index).and_then(|c| c.as_deref()))+ };cell_xml(Some(&Value::String(header.to_string())), 0, index, Some(1))}).collect::<String>()- )+ );+ if header_row_count(column_comments, header_comment_rows) > 1 {+ output.push_str(&format!(+ "<row r=\"2\">{}</row>",+ columns+ .iter()+ .enumerate()+ .map(|(index, _)| {+ let comment = column_comments.get(index).and_then(|c| c.as_deref()).filter(|c| !c.is_empty());+ cell_xml(comment.map(|c| Value::String(c.to_string())).as_ref(), 1, index, Some(1))+ })+ .collect::<String>()+ ));+ }+ output}fn push_data_row_xml(@@ -281,7 +333,18 @@ pub fn start_streaming_xlsx_workbook<W: Write + Seek>(columns: &[String],column_types: &[String],) -> Result<StreamingXlsxWriter<W>, String> {- start_streaming_xlsx_workbook_with_options(writer, sheet_name, columns, column_types, &[], &[], None, false, true)+ start_streaming_xlsx_workbook_with_options(+ writer,+ sheet_name,+ columns,+ column_types,+ &[],+ &[],+ None,+ false,+ true,+ false,+ )}#[cfg(test)]@@ -302,9 +365,23 @@ pub fn start_streaming_xlsx_workbook_with_trailing_sheets<W: Write + Seek>(None,false,true,+ false,)}+/// Sheet-level rendering options shared by the streaming writer and the+/// in-memory worksheet writer.+#[derive(Debug, Clone, Default)]+struct XlsxSheetRenderOptions {+ date_time_format: Option<String>,+ numeric_right_align: bool,+ auto_filter: bool,+ max_data_rows_per_sheet: usize,+ /// Render comments as a second header row (names row 1, comments row 2,+ /// data from row 3) instead of overriding the header text.+ header_comment_rows: bool,+}+/// Start a new streaming XLSX workbook with full options. Metadata files/// ([Content_Types].xml, workbook.xml, styles.xml, etc.) are deferred to/// [`StreamingXlsxWriter::finish`] so that the final sheet count is known@@ -316,12 +393,19 @@ fn start_xlsx_writer_inner<W: Write + Seek>(column_types: &[String],column_comments: &[Option<String>],trailing_sheets: &[XlsxWorksheetData],- date_time_format: Option<&str>,- numeric_right_align: bool,- auto_filter: bool,- max_data_rows_per_sheet: usize,+ render_options: XlsxSheetRenderOptions,) -> Result<StreamingXlsxWriter<W>, String> {- let width_cache = estimate_header_widths(columns, column_comments);+ let XlsxSheetRenderOptions {+ date_time_format,+ numeric_right_align,+ auto_filter,+ max_data_rows_per_sheet,+ header_comment_rows,+ } = render_options;+ // The comment row only renders when at least one comment is non-empty; an+ // all-empty second row would shift the data down for nothing.+ let header_comment_rows = header_comment_rows && header_row_count(column_comments, true) > 1;+ let width_cache = estimate_header_widths(columns, column_comments, header_comment_rows);let sheet_name_allocator = SheetNameAllocator::new(sheet_name, trailing_sheets);let mut zip = zip::ZipWriter::new(writer);@@ -330,27 +414,32 @@ fn start_xlsx_writer_inner<W: Write + Seek>(let options = xlsx_zip_options();zip.start_file("xl/worksheets/sheet1.xml", options).map_err(|err| err.to_string())?;+ let header_rows = header_row_count(column_comments, header_comment_rows);+ let top_left_cell = format!("A{}", header_rows + 1);let sheet_header = format!(concat!("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>","<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">","<sheetViews><sheetView workbookViewId=\"0\">",- "<pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/>",+ "<pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/>","</sheetView></sheetViews>","<sheetFormatPr defaultRowHeight=\"15\"/>","<cols>{cols}</cols>","<sheetData>"),+ y_split = header_rows,+ top_left = top_left_cell,cols = cols_xml(&width_cache),);zip.write_all(sheet_header.as_bytes()).map_err(|err| err.to_string())?;- zip.write_all(header_row_xml(columns, column_comments).as_bytes()).map_err(|err| err.to_string())?;+ zip.write_all(header_row_xml(columns, column_comments, header_comment_rows).as_bytes())+ .map_err(|err| err.to_string())?;Ok(StreamingXlsxWriter {zip,columns: columns.to_vec(),column_types: column_types.to_vec(),- next_row_number: 2,+ next_row_number: header_rows + 1,current_data_rows: 0,max_data_rows_per_sheet,current_sheet_number: 1,@@ -358,7 +447,8 @@ fn start_xlsx_writer_inner<W: Write + Seek>(trailing_sheets: trailing_sheets.to_vec(),width_cache,column_comments: column_comments.to_vec(),- date_time_format: date_time_format.map(str::to_string),+ header_comment_rows,+ date_time_format,numeric_right_align,auto_filter,row_buffer: String::with_capacity(columns.len().saturating_mul(48)),@@ -375,6 +465,7 @@ pub fn start_streaming_xlsx_workbook_with_options<W: Write + Seek>(date_time_format: Option<&str>,numeric_right_align: bool,auto_filter: bool,+ header_comment_rows: bool,) -> Result<StreamingXlsxWriter<W>, String> {start_xlsx_writer_inner(writer,@@ -383,10 +474,13 @@ pub fn start_streaming_xlsx_workbook_with_options<W: Write + Seek>(column_types,column_comments,trailing_sheets,- date_time_format,- numeric_right_align,- auto_filter,- XLSX_MAX_DATA_ROWS,+ XlsxSheetRenderOptions {+ date_time_format: date_time_format.map(str::to_string),+ numeric_right_align,+ auto_filter,+ max_data_rows_per_sheet: XLSX_MAX_DATA_ROWS,+ header_comment_rows,+ },)}@@ -406,10 +500,7 @@ pub fn start_streaming_xlsx_workbook_with_max_rows<W: Write + Seek>(column_types,&[],trailing_sheets,- None,- false,- true,- max_data_rows_per_sheet,+ XlsxSheetRenderOptions { max_data_rows_per_sheet, auto_filter: true, ..XlsxSheetRenderOptions::default() },)}@@ -457,26 +548,30 @@ impl<W: Write + Seek> StreamingXlsxWriter<W> {.start_file(format!("xl/worksheets/sheet{}.xml", self.current_sheet_number), options).map_err(|err| err.to_string())?;+ let header_rows = header_row_count(&self.column_comments, self.header_comment_rows);+ let top_left_cell = format!("A{}", header_rows + 1);let sheet_header = format!(concat!("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>","<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">","<sheetViews><sheetView workbookViewId=\"0\">",- "<pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/>",+ "<pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/>","</sheetView></sheetViews>","<sheetFormatPr defaultRowHeight=\"15\"/>","<cols>{cols}</cols>","<sheetData>"),+ y_split = header_rows,+ top_left = top_left_cell,cols = cols_xml(&self.width_cache),);self.zip.write_all(sheet_header.as_bytes()).map_err(|err| err.to_string())?;self.zip- .write_all(header_row_xml(&self.columns, &self.column_comments).as_bytes())+ .write_all(header_row_xml(&self.columns, &self.column_comments, self.header_comment_rows).as_bytes()).map_err(|err| err.to_string())?;// Reset row counters for the new sheet.- self.next_row_number = 2;+ self.next_row_number = header_rows + 1;self.current_data_rows = 0;Ok(())}@@ -502,6 +597,8 @@ impl<W: Write + Seek> StreamingXlsxWriter<W> {rows: &sheet.rows,numeric_column_right_align: sheet.numeric_column_right_align,auto_filter: sheet.auto_filter,+ // Trailing sheets (SQL previews) keep the single-row header.+ header_comment_rows: false,};write_worksheet_xml(&mut self.zip, &segment, self.auto_filter, self.date_time_format.as_deref())?;}@@ -600,15 +697,29 @@ fn value_text(value: Option<&Value>) -> String {}}-fn estimate_column_widths(columns: &[String], column_comments: &[Option<String>], rows: &[Vec<Value>]) -> Vec<usize> {+fn estimate_column_widths(+ columns: &[String],+ column_comments: &[Option<String>],+ rows: &[Vec<Value>],+ header_comment_rows: bool,+) -> Vec<usize> {columns.iter().enumerate().map(|(col_index, col)| {let is_sql_col = col.eq_ignore_ascii_case("sql");let max_clamp = if is_sql_col { 100 } else { 60 };- let header_text = effective_header(col, column_comments.get(col_index).and_then(|c| c.as_deref()));- let max_len = std::iter::once(header_text.chars().count().min(max_clamp))+ let comment = column_comments.get(col_index).and_then(|c| c.as_deref());+ // With a separate comment row both texts are visible, so the column+ // must fit the wider of the two; otherwise the comment overrides+ // the header text outright.+ let header_text = if header_comment_rows { col.as_str() } else { effective_header(col, comment) };+ let header_len = header_text.chars().count().max(if header_comment_rows {+ comment.map(str::chars).map(Iterator::count).unwrap_or(0)+ } else {+ 0+ });+ let max_len = std::iter::once(header_len.min(max_clamp)).chain(rows.iter().take(100).map(|row| {let text = value_text(row.get(col_index));if is_sql_col {@@ -891,10 +1002,13 @@ fn write_worksheet_xml<W: Write>(auto_filter: bool,date_time_format: Option<&str>,) -> Result<(), String> {- let total_rows = segment.rows.len() + 1;+ let header_rows = header_row_count(segment.column_comments, segment.header_comment_rows);+ let total_rows = segment.rows.len() + header_rows;let range = sheet_range(segment.columns.len(), total_rows);- let widths = estimate_column_widths(segment.columns, segment.column_comments, segment.rows);+ let widths =+ estimate_column_widths(segment.columns, segment.column_comments, segment.rows, segment.header_comment_rows);+ let top_left_cell = format!("A{}", header_rows + 1);writer.write_all(format!(@@ -902,24 +1016,26 @@ fn write_worksheet_xml<W: Write>("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>","<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">","<dimension ref=\"{range}\"/>",- "<sheetViews><sheetView workbookViewId=\"0\"><pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/></sheetView></sheetViews>",+ "<sheetViews><sheetView workbookViewId=\"0\"><pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/></sheetView></sheetViews>","<sheetFormatPr defaultRowHeight=\"15\"/>","<cols>{cols}</cols>","<sheetData>"),range = range,+ y_split = header_rows,+ top_left = top_left_cell,cols = cols_xml(&widths),).as_bytes(),).map_err(|err| err.to_string())?;writer- .write_all(header_row_xml(segment.columns, segment.column_comments).as_bytes())+ .write_all(header_row_xml(segment.columns, segment.column_comments, segment.header_comment_rows).as_bytes()).map_err(|err| err.to_string())?;let mut row_buffer = String::with_capacity(segment.columns.len().saturating_mul(48));for (row_index, row) in segment.rows.iter().enumerate() {- let excel_row = row_index + 2;+ let excel_row = row_index + header_rows + 1;row_buffer.clear();push_data_row_xml(&mut row_buffer,@@ -1142,6 +1258,7 @@ struct WorksheetSegment<'a> {rows: &'a [Vec<Value>],numeric_column_right_align: bool,auto_filter: Option<bool>,+ header_comment_rows: bool,}fn normalize_unique_sheet_names(segments: &[WorksheetSegment]) -> Vec<String> {@@ -1186,6 +1303,7 @@ fn split_sheets_for_max_rows<'a>(rows: &sheet.rows,numeric_column_right_align: sheet.numeric_column_right_align,auto_filter: sheet.auto_filter,+ header_comment_rows: sheet.header_comment_rows,});continue;}@@ -1211,6 +1329,7 @@ fn split_sheets_for_max_rows<'a>(rows: chunk,numeric_column_right_align: sheet.numeric_column_right_align,auto_filter: sheet.auto_filter,+ header_comment_rows: sheet.header_comment_rows,});}}@@ -1374,6 +1493,7 @@ mod tests {rows: vec![vec![json!(1), json!("Ada & Bob"), json!(true)], vec![json!(2), json!(null), json!(false)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1401,6 +1521,7 @@ mod tests {rows: vec![vec![json!(1)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let workbook = build_xlsx_workbook_multi_with_auto_filter(&[worksheet], false, None).expect("build workbook");@@ -1412,6 +1533,7 @@ mod tests {let data = XlsxWorksheetData::new(Some("Data".to_string()), vec!["id".to_string()], vec![vec![json!(1)]]);let sql = XlsxWorksheetData {auto_filter: Some(false),+ header_comment_rows: false,..XlsxWorksheetData::new(Some("SQL".to_string()), vec!["SQL".to_string()], vec![vec![json!("SELECT 1")]])};let workbook = build_xlsx_workbook_multi_with_auto_filter(&[data, sql], true, None).expect("build workbook");@@ -1430,6 +1552,7 @@ mod tests {rows: vec![vec![json!("1.00000"), json!("2800.000000"), json!("00123")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1449,6 +1572,7 @@ mod tests {rows: vec![vec![json!("5.0000"), json!("0.3500000"), json!("1.23E-5")]],numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1475,6 +1599,7 @@ mod tests {rows: vec![vec![json!("5.0000"), json!("7")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1493,6 +1618,7 @@ mod tests {rows: vec![vec![json!("0.00000000000000000001")]],numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1524,6 +1650,7 @@ mod tests {]],numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1567,6 +1694,7 @@ mod tests {]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1596,6 +1724,7 @@ mod tests {rows: vec![vec![json!("2026-07-25 13:02:15.456")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let workbook =@@ -1648,6 +1777,7 @@ mod tests {]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1676,6 +1806,7 @@ mod tests {rows: vec![vec![json!("9223372036854775807"), json!("123456789012345.6789000000")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1710,6 +1841,7 @@ mod tests {]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -1750,6 +1882,7 @@ mod tests {rows: vec![vec![json!("ok")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");let workbook_xml = read_zip_entry(&workbook, "xl/workbook.xml");@@ -1768,6 +1901,7 @@ mod tests {rows: vec![vec![json!(1)]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},XlsxWorksheetData {sheet_name: Some("Result 2".to_string()),@@ -1777,6 +1911,7 @@ mod tests {rows: vec![vec![json!("Ada")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,},]).expect("build multi-sheet workbook");@@ -1851,6 +1986,7 @@ mod tests {Some("YYYY/MM/DD HH:mm:ss.SSS"),false,true,+ false,).expect("start workbook");writer.write_row(&[json!("2024/02/25 13:02:15.125")]).expect("write temporal row");@@ -1878,6 +2014,7 @@ mod tests {rows: vec![vec![json!("SELECT id, name FROM users")]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let mut writer = start_streaming_xlsx_workbook_with_trailing_sheets(file,@@ -1910,6 +2047,7 @@ mod tests {rows: vec![vec![json!(1.5), json!("row")]],numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");@@ -1928,6 +2066,7 @@ mod tests {rows: vec![vec![json!(1.5), json!("row")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");@@ -1969,6 +2108,7 @@ mod tests {rows: vec![row],numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");@@ -2080,6 +2220,7 @@ mod tests {rows: vec![vec![json!("SELECT 1")]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let mut writer = start_streaming_xlsx_workbook_with_max_rows(file,@@ -2165,6 +2306,7 @@ mod tests {rows: vec![vec![json!("SELECT 1")]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let sql_sheet_b = XlsxWorksheetData {sheet_name: Some("SQL".to_string()),@@ -2174,6 +2316,7 @@ mod tests {rows: vec![vec![json!("SELECT 2")]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let mut writer = start_streaming_xlsx_workbook_with_max_rows(file,@@ -2215,6 +2358,7 @@ mod tests {rows: vec![vec![json!("SELECT 1")]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let mut writer = start_streaming_xlsx_workbook_with_max_rows(file,@@ -2255,6 +2399,7 @@ mod tests {rows,numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}],2,None,@@ -2319,6 +2464,7 @@ mod tests {rows,numeric_column_right_align: true,auto_filter: None,+ header_comment_rows: false,};let segment = WorksheetSegment {name: worksheet.sheet_name.clone(),@@ -2328,6 +2474,7 @@ mod tests {rows: &worksheet.rows,numeric_column_right_align: worksheet.numeric_column_right_align,auto_filter: worksheet.auto_filter,+ header_comment_rows: worksheet.header_comment_rows,};let mut stats = WriteStats::default();@@ -2354,6 +2501,7 @@ mod tests {rows: (0..7).map(|i| vec![json!(i)]).collect(),numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let sheet_b = XlsxWorksheetData {sheet_name: Some("B".to_string()),@@ -2363,6 +2511,7 @@ mod tests {rows: (100..102).map(|i| vec![json!(i)]).collect(),numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let data = build_xlsx_workbook_multi_with_max_rows(&[sheet_a, sheet_b], 3, None).expect("build workbook");@@ -2397,6 +2546,7 @@ mod tests {rows,numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}],100,None,@@ -2425,6 +2575,7 @@ mod tests {rows: vec![],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,}).expect("build workbook");@@ -2463,6 +2614,7 @@ mod tests {rows: vec![vec![json!(1), json!("Ada")]],numeric_column_right_align: false,auto_filter: None,+ header_comment_rows: false,};let multiline_sql = "SELECT id, name\n FROM users\n WHERE active = 1\n ORDER BY id ASC";let sql_sheet = XlsxWorksheetData {@@ -2473,6 +2625,7 @@ mod tests {rows: vec![vec![json!(multiline_sql)]],numeric_column_right_align: false,auto_filter: Some(false),+ header_comment_rows: false,};let workbook = build_xlsx_workbook_multi_with_auto_filter(&[data_sheet, sql_sheet], true, None)@@ -2510,4 +2663,80 @@ mod tests {}}}++ #[test]+ fn header_row_xml_keeps_override_semantics_without_comment_rows() {+ let columns = vec!["id".to_string(), "name".to_string()];+ let comments = vec![Some("Identifier".to_string()), None];++ let single = super::header_row_xml(&columns, &comments, false);+ assert!(single.starts_with("<row r=\"1\">"));+ assert!(single.contains(">Identifier<"), "comment overrides header: {single}");+ assert!(!single.contains("<row r=\"2\">"), "no second row by default: {single}");+ assert_eq!(super::header_row_count(&comments, false), 1);+ }++ #[test]+ fn header_row_xml_emits_names_and_comment_rows() {+ let columns = vec!["id".to_string(), "name".to_string()];+ let comments = vec![Some("Identifier".to_string()), Some(String::new())];++ let rows = super::header_row_xml(&columns, &comments, true);+ assert!(rows.contains("<row r=\"1\">"), "{rows}");+ assert!(rows.contains("<row r=\"2\">"), "{rows}");+ // Row 1 keeps the plain column names; row 2 carries the comments.+ let row1_end = rows.find("<row r=\"2\">").expect("second row");+ let row1 = &rows[..row1_end];+ assert!(row1.contains(">id<") && row1.contains(">name<"), "names on row 1: {row1}");+ assert!(!row1.contains(">Identifier<"), "comment must not override the name: {row1}");+ let row2 = &rows[row1_end..];+ assert!(row2.contains(">Identifier<"), "comment on row 2: {row2}");+ assert_eq!(super::header_row_count(&comments, true), 2);+ }++ #[test]+ fn header_row_count_skips_the_comment_row_when_every_comment_is_empty() {+ let empty = vec![Some(String::new()), None];+ assert_eq!(super::header_row_count(&empty, true), 1);+ assert_eq!(super::header_row_count(&[], true), 1);+ let comments = vec![Some("note".to_string())];+ assert_eq!(super::header_row_count(&comments, true), 2);+ }++ #[test]+ fn streaming_workbook_with_comment_rows_offsets_data_and_freezes_both_headers() {+ let path = std::env::temp_dir().join(format!("dbx-comment-rows-{}.xlsx", uuid::Uuid::new_v4()));+ {+ let file = std::fs::File::create(&path).expect("create temp xlsx");+ let columns = vec!["id".to_string()];+ let types = vec![String::new()];+ let comments = vec![Some("Identifier".to_string())];+ let mut writer = super::start_streaming_xlsx_workbook_with_options(+ file,+ Some("Result"),+ &columns,+ &types,+ &comments,+ &[],+ None,+ false,+ true,+ true,+ )+ .expect("start workbook");+ writer.write_row(&[json!(1)]).expect("write row");+ drop(writer.finish().expect("finish workbook"));+ }++ let bytes = std::fs::read(&path).expect("read workbook");+ let sheet = read_zip_entry(&bytes, "xl/worksheets/sheet1.xml");+ assert!(sheet.contains("ySplit=\"2\" topLeftCell=\"A3\""), "freeze both header rows: {sheet}");+ assert!(sheet.contains("<row r=\"1\">"), "{sheet}");+ assert!(sheet.contains("<row r=\"2\">"), "{sheet}");+ assert!(sheet.contains("<row r=\"3\">"), "data starts on row 3: {sheet}");+ let row3 = sheet.split("<row r=\"3\">").nth(1).expect("row 3 cells");+ assert!(row3.starts_with("<c r=\"A3\"><v>1</v></c>"), "row 3 is the data row: {row3}");+ assert!(sheet.contains("<autoFilter ref=\"A1:A3\"/>"), "filter covers both header rows and data: {sheet}");+ std::fs::remove_file(&path).ok();+ }}diff --git a/packages/app-tests/xlsxExport.test.ts b/packages/app-tests/xlsxExport.test.tsindex b7b079aef7..b5c70e6999 100644--- a/packages/app-tests/xlsxExport.test.ts+++ b/packages/app-tests/xlsxExport.test.ts@@ -293,3 +293,39 @@ test("numeric right-align disabled applies left-align style across cross-databas});assert.doesNotMatch(text, /s="2"/);});++test("header comment rows render names on row 1, comments on row 2, data from row 3", () => {+ const workbook = buildXlsxWorkbook({+ sheetName: "Comments",+ columns: ["id", "name"],+ columnComments: ["Identifier", null],+ rows: [+ [1, "Ada"],+ [2, "Bob"],+ ],+ headerCommentRows: true,+ });+ const sheet = readStoredZipEntry(workbook, "xl/worksheets/sheet1.xml");++ assert.match(sheet, /ySplit="2" topLeftCell="A3"/);+ assert.match(sheet, /<row r="1"><c r="A1"[^>]*><is><t[^>]*>id<\/t><\/is><\/c><c r="B1"[^>]*><is><t[^>]*>name<\/t><\/is><\/c><\/row>/);+ assert.match(sheet, /<row r="2"><c r="A2"[^>]*><is><t[^>]*>Identifier<\/t><\/is><\/c><c r="B2"[^>]*\/><\/row>/);+ assert.match(sheet, /<c r="A3"><v>1<\/v><\/c>/);+ assert.match(sheet, /<c r="A4"><v>2<\/v><\/c>/);+ assert.doesNotMatch(sheet, /<c r="A1"[^>]*><is><t[^>]*>Identifier<\/t>/);+});++test("header comment rows are skipped when every comment is empty", () => {+ const workbook = buildXlsxWorkbook({+ sheetName: "NoComments",+ columns: ["id"],+ columnComments: [null],+ rows: [[1]],+ headerCommentRows: true,+ });+ const sheet = readStoredZipEntry(workbook, "xl/worksheets/sheet1.xml");++ assert.match(sheet, /ySplit="1" topLeftCell="A2"/);+ assert.match(sheet, /<c r="A2"><v>1<\/v><\/c>/);+ assert.doesNotMatch(sheet, /<row r="2"><c r="A2"[^>]*><is><t[^>]*>/);+});diff --git a/src-tauri/src/commands/xlsx_export.rs b/src-tauri/src/commands/xlsx_export.rsindex 9348b84650..4462566e0c 100644--- a/src-tauri/src/commands/xlsx_export.rs+++ b/src-tauri/src/commands/xlsx_export.rs@@ -14,6 +14,10 @@ pub struct QueryResultXlsxExportRequest {pub column_types: Vec<String>,#[serde(default)]pub column_comments: Vec<Option<String>>,+ /// Render comments as a second header row (names row 1, comments row 2,+ /// data from row 3) instead of overriding the header text.+ #[serde(default)]+ pub header_comment_rows: bool,pub rows: Vec<Vec<Value>>,#[serde(default)]pub numeric_column_right_align: bool,@@ -48,6 +52,7 @@ pub async fn export_query_result_xlsx(request: QueryResultXlsxExportRequest) ->rows: request.rows,numeric_column_right_align: request.numeric_column_right_align,auto_filter: request.auto_filter,+ header_comment_rows: request.header_comment_rows,};// Ensure consistency: if the feature is disabled, clear the flag.if !data.numeric_column_right_align {