@veltra/sheet 2.2.0 → 2.3.1

package/dist/report/export-xlsx.js

@@ -20,11 +20,10 @@ function buildColumnDefs(colWidths) {
 /**
 * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
 * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
-*
-* 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
-* 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+* 列宽取自 sheet 模型（`getColWidths`）。
 */
-async function exportFilledReportXlsx(sheet, colWidths) {
+async function exportFilledReportXlsx(sheet) {
+	const widths = [...sheet.getColWidths()];
 	let maxRow = -1;
 	let maxCol = -1;
 	for (const [addr] of sheet.store.entries()) {
@@ -32,17 +31,15 @@ async function exportFilledReportXlsx(sheet, colWidths) {
 		if (addr.col > maxCol) maxCol = addr.col;
 	}
 	for (const [row] of sheet.getRowHeights()) if (row > maxRow) maxRow = row;
-	for (const [col] of colWidths) if (col > maxCol) maxCol = col;
+	for (const [col] of widths) if (col > maxCol) maxCol = col;
 	const rows = maxRow < 0 ? [] : Array.from({ length: maxRow + 1 }, () => Array.from({ length: maxCol + 1 }, () => null));
 	const cells = /* @__PURE__ */ new Map();
 	for (const [addr, data] of sheet.store.entries()) {
 		const row = rows[addr.row];
 		const key = `${addr.row},${addr.col}`;
 		const cell = {};
-		if (data.s != null) {
-			const style = sheet.stylePool.get(data.s);
-			if (style) cell.style = styleToHucre(style);
-		}
+		const style = sheet.getEffectiveStyle(addr);
+		if (style) cell.style = styleToHucre(style);
 		if (data.f != null && data.f !== "") {
 			cell.formula = data.f;
 			if (data.v != null) cell.formulaResult = data.v;
@@ -76,7 +73,7 @@ async function exportFilledReportXlsx(sheet, colWidths) {
 		rows,
 		...cells.size > 0 ? { cells } : {},
 		...sheet.merges.size > 0 ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) } : {},
-		...colWidths.length > 0 ? { columns: buildColumnDefs(colWidths) } : {}
+		...widths.length > 0 ? { columns: buildColumnDefs(widths) } : {}
 	};
 	const frozen = sheet.frozen;
 	if (frozen.rows > 0 || frozen.cols > 0) writeSheet.freezePane = {

package/dist/report/index.d.ts

@@ -1,5 +1,5 @@
 import { ConditionalOperator, ConditionalRule, DatasetCatalogItem, DatasetField, DatasetRecords, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, ReportAggregate, ReportBinding, ReportExpand, ReportPreset, ReportSort } from "./types.js";
-import { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog } from "./binding.js";
+import { InferParentOptions, ListParentCandidateOptions, REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, prefersGroupParent, presetBindingPatch, presetStillApplies, setBindingCatalog } from "./binding.js";
 import { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./rules/evaluate.js";
 import "./rules/index.js";
 import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from "./params.js";
@@ -9,4 +9,4 @@ import { renderReport, resolveFilledColWidths } from "./render/index.js";
 import { ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, QueryResult, Result, createHttpConnector, resolvePortOnTypeChange } from "./connector.js";
 import { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, ReportDatasetDef, ReportTemplate, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams } from "./template.js";
 import { parseDateRangeValue, patchParamValues, resolveNumberParamValue } from "./filter-bar.js";
-export { type ConditionalEvalContext, ConditionalOperator, ConditionalRule, ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, DatasetCatalogItem, DatasetField, DatasetRecords, IncompatibleTemplateVersionError, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, QueryResult, REPORT_META_NAMESPACE, REPORT_TEMPLATE_VERSION, ReportAggregate, ReportBinding, ReportColWidthEntry, ReportDatasetDef, ReportExpand, ReportPreset, ReportSort, ReportTemplate, Result, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatCellAddress, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, presetBindingPatch, pxToExcelColWidth, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber };
+export { type ConditionalEvalContext, ConditionalOperator, ConditionalRule, ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, DatasetCatalogItem, DatasetField, DatasetRecords, IncompatibleTemplateVersionError, InferParentOptions, ListParentCandidateOptions, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, QueryResult, REPORT_META_NAMESPACE, REPORT_TEMPLATE_VERSION, ReportAggregate, ReportBinding, ReportColWidthEntry, ReportDatasetDef, ReportExpand, ReportPreset, ReportSort, ReportTemplate, Result, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, prefersGroupParent, presetBindingPatch, presetStillApplies, pxToExcelColWidth, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber };

package/dist/report/render/aggregate.js

@@ -25,7 +25,10 @@ function isRowExpanding(binding) {
 function isColExpanding(binding) {
 	return binding.expand === "right" && (binding.aggregate === "group" || binding.aggregate === "list");
 }
-function rowExpandingAncestors(binding, index) {
+function isReductionAggregate(aggregate) {
+	return aggregate === "sum" || aggregate === "avg" || aggregate === "count" || aggregate === "max" || aggregate === "min";
+}
+function rowExpandingAncestors(binding, index, groupsOnly) {
 	const chain = [];
 	let current = binding.rowParent;
 	while (current) {
@@ -36,9 +39,13 @@ function rowExpandingAncestors(binding, index) {
 		});
 		current = parentBinding?.rowParent;
 	}
-	return chain.filter((item) => isRowExpanding(item.binding));
+	return chain.filter((item) => {
+		if (!isRowExpanding(item.binding)) return false;
+		if (groupsOnly && item.binding.aggregate !== "group") return false;
+		return true;
+	});
 }
-function colExpandingAncestors(binding, index) {
+function colExpandingAncestors(binding, index, groupsOnly) {
 	const chain = [];
 	let current = binding.colParent;
 	while (current) {
@@ -49,7 +56,11 @@ function colExpandingAncestors(binding, index) {
 		});
 		current = parentBinding?.colParent;
 	}
-	return chain.filter((item) => isColExpanding(item.binding));
+	return chain.filter((item) => {
+		if (!isColExpanding(item.binding)) return false;
+		if (groupsOnly && item.binding.aggregate !== "group") return false;
+		return true;
+	});
 }
 function mergeFilters(rowFilter, colFilter) {
 	return {
@@ -61,7 +72,8 @@ function resolveAncestorFilters(binding, placement, index, data) {
 	const rowFilter = {};
 	const colFilter = {};
 	let parentFilter = {};
-	const rowAncestors = rowExpandingAncestors(binding, index);
+	const groupsOnly = isReductionAggregate(binding.aggregate);
+	const rowAncestors = rowExpandingAncestors(binding, index, groupsOnly);
 	for (let i = 0; i < rowAncestors.length; i++) {
 		const ancestor = rowAncestors[i];
 		if (ancestor.binding.dataset !== binding.dataset) continue;
@@ -74,7 +86,7 @@ function resolveAncestorFilters(binding, placement, index, data) {
 		parentFilter = instance.filter;
 	}
 	parentFilter = {};
-	const colAncestors = colExpandingAncestors(binding, index);
+	const colAncestors = colExpandingAncestors(binding, index, groupsOnly);
 	for (let i = 0; i < colAncestors.length; i++) {
 		const ancestor = colAncestors[i];
 		if (ancestor.binding.dataset !== binding.dataset) continue;
@@ -89,8 +101,8 @@ function resolveAncestorFilters(binding, placement, index, data) {
 	return mergeFilters(rowFilter, colFilter);
 }
 function resolveOwnGroupValue(binding, placement, index, data) {
-	const rowAncestors = rowExpandingAncestors(binding, index);
-	const colAncestors = colExpandingAncestors(binding, index);
+	const rowAncestors = rowExpandingAncestors(binding, index, false);
+	const colAncestors = colExpandingAncestors(binding, index, false);
 	let parentFilter = {};
 	for (let i = 0; i < rowAncestors.length; i++) {
 		const ancestor = rowAncestors[i];

package/dist/report/template.d.ts

@@ -3,7 +3,7 @@ import { DataConnection, DataConnector, Result } from "./connector.js";
 import { SheetSnapshot } from "@veltra/sheet-core";
 //#region src/report/template.d.ts
 /**
- * 模板内嵌的数据集定义（Dataset = Data Connection + SQL，ADR-0002 决策 2）。
+ * 模板内嵌的数据集定义
  * 与 playground DatasetDef 同构，connectionId 替换为内嵌的完整连接对象。
  */
 interface ReportDatasetDef {
@@ -16,7 +16,7 @@ interface ReportDatasetDef {
   /** 字段中文名覆盖（name → label）；查看器不消费，随模板序列化往返供设计器还原 */
   fieldOverrides?: Record<string, Partial<Pick<DatasetField, 'label'>>>;
 }
-/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+/** 当前支持的报表模板版本 */
 declare const REPORT_TEMPLATE_VERSION = 1;
 /** 模板版本不兼容时抛出 */
 declare class IncompatibleTemplateVersionError extends Error {
@@ -25,8 +25,9 @@ declare class IncompatibleTemplateVersionError extends Error {
 /**
  * 自包含 Report Template：SheetSnapshot + 内嵌数据集定义 + 版本段。
  * 查看器仅凭 `template` + `connector` 即可完成「参数提取 → 取数 → 展开渲染」闭环；
- * 模板可 JSON 序列化流转（凭据随之流转，持久化与安全存储由下游负责，ADR-0003 决策 4）。
+ * 模板可 JSON 序列化流转。
  *
+ * `colWidths` 继承自 `SheetSnapshot.colWidths`（模型列索引 → 像素）。
  * 注意：`Sheet.snapshot()` 不产生 `datasets` / `version` 字段，经 `restore()`/`snapshot()` 往返会丢失，
  * 由设计器 `getTemplate()` 在吐出快照时重新附加。
  */
@@ -37,7 +38,10 @@ interface ReportTemplate extends SheetSnapshot {
 }
 /** 载入模板前校验版本：缺失或高于当前支持版本时抛可读错误 */
 declare function assertCompatibleTemplateVersion(template: ReportTemplate): void;
-/** 由工作簿快照构造带版本段的 Report Template */
+/**
+ * 由工作簿快照构造带版本段的 Report Template。
+ * `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+ */
 declare function createReportTemplate(snapshot: SheetSnapshot, datasets?: ReportDatasetDef[]): ReportTemplate;
 /** 读取模板内嵌的数据集定义（旧模板未内嵌时回退空数组） */
 declare function getTemplateDatasets(template: ReportTemplate): ReportDatasetDef[];

package/dist/report/template.js

@@ -1,7 +1,7 @@
 import "./binding.js";
 import { buildParamDefs } from "./params.js";
 //#region src/report/template.ts
-/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+/** 当前支持的报表模板版本 */
 const REPORT_TEMPLATE_VERSION = 1;
 /** 模板版本不兼容时抛出 */
 var IncompatibleTemplateVersionError = class extends Error {
@@ -15,7 +15,10 @@ function assertCompatibleTemplateVersion(template) {
 	if (template.version === void 0) throw new IncompatibleTemplateVersionError("报表模板缺少 version 字段，请在设计器中重建模板后重试");
 	if (template.version > 1) throw new IncompatibleTemplateVersionError(`报表模板版本 ${template.version} 高于当前支持的版本 1，请升级组件库后重试`);
 }
-/** 由工作簿快照构造带版本段的 Report Template */
+/**
+* 由工作簿快照构造带版本段的 Report Template。
+* `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+*/
 function createReportTemplate(snapshot, datasets) {
 	return {
 		...snapshot,

package/dist/tools/apply-style.js

@@ -0,0 +1,29 @@
+//#region src/tools/apply-style.ts
+/**
+* 按选区相对渲染网格的跨度判定样式写入目标（对齐 Excel）：
+* - 跨满全部列且未跨满全部行 → 行默认样式（rowStyles）
+* - 跨满全部行且未跨满全部列 → 列默认样式（colStyles）
+* - 其余（含全表 / 局部）→ 单元格样式
+*/
+function classifySelectionStyleTarget(range, renderRows, renderCols) {
+	const cols = Math.max(renderCols, 1);
+	const rows = Math.max(renderRows, 1);
+	const spansAllCols = range.start.col === 0 && range.end.col >= cols - 1;
+	const spansAllRows = range.start.row === 0 && range.end.row >= rows - 1;
+	if (spansAllCols && !spansAllRows) return "row";
+	if (spansAllRows && !spansAllCols) return "col";
+	return "cell";
+}
+/** 整行/整列选区 → set-axis-style 写入项（partial）或清除项（clear） */
+function axisStyleItemsForRange(range, axis, patch) {
+	const start = axis === "row" ? range.start.row : range.start.col;
+	const end = axis === "row" ? range.end.row : range.end.col;
+	const items = [];
+	for (let index = start; index <= end; index++) items.push({
+		index,
+		...patch
+	});
+	return items;
+}
+//#endregion
+export { axisStyleItemsForRange, classifySelectionStyleTarget };

package/dist/tools/builtin.js

@@ -17,15 +17,15 @@ function selectionRange(ctx) {
 function toggleFontFlag(ctx, field) {
 	const sel = selectionRange(ctx);
 	if (!sel) return;
-	const on = ctx.getCellStyle(sel.activeCell)?.font?.[field] === true;
-	ctx.setCellStyle(sel.range, { font: { [field]: on ? null : true } });
+	const on = ctx.getEffectiveStyle(sel.activeCell)?.font?.[field] === true;
+	ctx.applyStyle(sel.range, { font: { [field]: on ? null : true } });
 }
 /** 对齐 toggle：点当前档 = 清除，点其它档 = 切换 */
 function toggleAlign(ctx, axis, value) {
 	const sel = selectionRange(ctx);
 	if (!sel) return;
-	if (ctx.getCellStyle(sel.activeCell)?.align?.[axis] === value) ctx.setCellStyle(sel.range, { align: { [axis]: null } });
-	else ctx.setCellStyle(sel.range, { align: { [axis]: value } });
+	if (ctx.getEffectiveStyle(sel.activeCell)?.align?.[axis] === value) ctx.applyStyle(sel.range, { align: { [axis]: null } });
+	else ctx.applyStyle(sel.range, { align: { [axis]: value } });
 }
 /**
 * 内置工具（dogfood 扩展机制）。
@@ -129,7 +129,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.bold === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.bold === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "bold")
 });
@@ -143,7 +143,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.italic === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.italic === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "italic")
 });
@@ -157,7 +157,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.underline === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.underline === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "underline")
 });
@@ -171,7 +171,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.strikethrough === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.strikethrough === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "strikethrough")
 });
@@ -207,7 +207,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "left";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "left";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "left")
 });
@@ -221,7 +221,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "center";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "center";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "center")
 });
@@ -235,7 +235,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "right";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "right";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "right")
 });
@@ -249,7 +249,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "top";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "top";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "top")
 });
@@ -263,7 +263,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "middle";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "middle";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "middle")
 });
@@ -277,7 +277,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "bottom";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "bottom";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "bottom")
 });
@@ -291,13 +291,13 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.wrap === true;
+		return !!active && ctx.getEffectiveStyle(active)?.align?.wrap === true;
 	},
 	onClick: (ctx) => {
 		const sel = selectionRange(ctx);
 		if (!sel) return;
-		const on = ctx.getCellStyle(sel.activeCell)?.align?.wrap === true;
-		ctx.setCellStyle(sel.range, { align: { wrap: on ? null : true } });
+		const on = ctx.getEffectiveStyle(sel.activeCell)?.align?.wrap === true;
+		ctx.applyStyle(sel.range, { align: { wrap: on ? null : true } });
 	}
 });
 registerTool({

package/dist/tools/context.d.ts

@@ -37,12 +37,33 @@ interface SheetContext {
   getDisplayValue(addr: CellAddress): CellValue | undefined;
   /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
   getCellInfo(addr: CellAddress): CellInfo;
-  /** 设置区域样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
+  /**
+   * 按选区形态写样式（Excel 语义）：
+   * 整行选区 → rowStyles；整列选区 → colStyles；其余 → 逐格。
+   * 判定依赖 createSheetContext 注入的渲染尺寸；未注入时一律走 setCellStyle。
+   */
+  applyStyle(range: CellRange, partial: CellStylePatch): void;
+  /**
+   * 选区样式目标（与 applyStyle 同一判定）；未注入渲染尺寸时恒为 'cell'。
+   */
+  resolveStyleTarget(range: CellRange): 'row' | 'col' | 'cell';
+  /**
+   * 按选区形态清除样式：整行/整列清对应默认样式；其余清单元格 s。
+   * 未注入渲染尺寸时一律走 clearCellStyle。
+   */
+  clearStyle(range: CellRange): void;
+  /** 设置区域单元格样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
   setCellStyle(range: CellRange, partial: CellStylePatch): void;
-  /** 清除区域样式（保留值 / 公式） */
+  /** 清除区域单元格样式（保留值 / 公式） */
   clearCellStyle(range: CellRange): void;
-  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined） */
+  /** 设置行默认样式（部分合并，进 undo） */
+  setRowStyle(row: number, partial: CellStylePatch): void;
+  /** 设置列默认样式（部分合并，进 undo） */
+  setColStyle(col: number, partial: CellStylePatch): void;
+  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined；不含行列默认） */
   getCellStyle(addr: CellAddress): CellStyle | undefined;
+  /** 有效样式：列 → 行 → 格字段级叠加（空格可继承行列默认） */
+  getEffectiveStyle(addr: CellAddress): CellStyle | undefined;
   setCellValue(addr: CellAddress, value: CellValue): void;
   setCellFormula(addr: CellAddress, formula: string): void;
   /** 批量写入（一次调用 = 一个 undo 单元） */
@@ -86,6 +107,17 @@ interface SheetContext {
     id?: string;
   }) => void): () => void;
 }
+/** createSheetContext 可选配置 */
+interface SheetContextOptions {
+  /**
+   * 当前渲染网格尺寸（与 SheetGrid / resolveRenderSize 一致）。
+   * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
+   */
+  resolveGridSize?: () => {
+    rows: number;
+    cols: number;
+  };
+}
 /**
  * 创建工具上下文。
  * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
@@ -94,7 +126,8 @@ interface SheetContext {
  *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
  *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
  *   workbook prop 后导出工具仍导出旧工作簿）
+ * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
  */
-declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook)): SheetContext;
+declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
 //#endregion
-export { SheetContext, createSheetContext };
+export { SheetContext, SheetContextOptions, createSheetContext };

package/dist/tools/context.js

@@ -1,3 +1,4 @@
+import { axisStyleItemsForRange, classifySelectionStyleTarget } from "./apply-style.js";
 //#region src/tools/context.ts
 /**
 * 创建工具上下文。
@@ -7,10 +8,16 @@
 *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
 *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
 *   workbook prop 后导出工具仍导出旧工作簿）
+* @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
 */
-function createSheetContext(resolveSheet, workbook) {
+function createSheetContext(resolveSheet, workbook, options) {
 	const sheet = typeof resolveSheet === "function" ? resolveSheet : () => resolveSheet;
 	const resolveWorkbook = typeof workbook === "function" ? workbook : workbook != null ? () => workbook : void 0;
+	const resolveGridSize = options?.resolveGridSize;
+	const resolveTarget = (range) => {
+		const size = resolveGridSize?.();
+		return size ? classifySelectionStyleTarget(range, size.rows, size.cols) : "cell";
+	};
 	return {
 		get workbook() {
 			return resolveWorkbook?.();
@@ -29,9 +36,39 @@ function createSheetContext(resolveSheet, workbook) {
 		setCells: (items) => sheet().setCells(items),
 		mergeCells: (range) => sheet().mergeCells(range),
 		unmergeCells: (range) => sheet().unmergeCells(range),
+		applyStyle: (range, partial) => {
+			const target = resolveTarget(range);
+			if (target === "row" || target === "col") {
+				const items = axisStyleItemsForRange(range, target, { partial });
+				if (items.length === 0) return;
+				sheet().executeCommand("sheet.command.set-axis-style", {
+					axis: target,
+					items
+				});
+				return;
+			}
+			sheet().setCellStyle(range, partial);
+		},
+		resolveStyleTarget: (range) => resolveTarget(range),
+		clearStyle: (range) => {
+			const target = resolveTarget(range);
+			if (target === "row" || target === "col") {
+				const items = axisStyleItemsForRange(range, target, { clear: true });
+				if (items.length === 0) return;
+				sheet().executeCommand("sheet.command.set-axis-style", {
+					axis: target,
+					items
+				});
+				return;
+			}
+			sheet().clearCellStyle(range);
+		},
 		setCellStyle: (range, partial) => sheet().setCellStyle(range, partial),
 		clearCellStyle: (range) => sheet().clearCellStyle(range),
+		setRowStyle: (row, partial) => sheet().setRowStyle(row, partial),
+		setColStyle: (col, partial) => sheet().setColStyle(col, partial),
 		getCellStyle: (addr) => sheet().getCellStyle(addr),
+		getEffectiveStyle: (addr) => sheet().getEffectiveStyle(addr),
 		executeCommand: (commandId, params) => sheet().executeCommand(commandId, params),
 		get frozen() {
 			return sheet().frozen;

package/dist/types/report-designer.d.ts

@@ -24,6 +24,8 @@ interface ReportDesignerProps {
 /** 报表设计器组件定义的事件 */
 interface ReportDesignerEmits {
   (e: 'update:connections', value: DataConnection[]): void;
+  /** 数据集增删改或数据中枢关闭：宿主可立即持久化工作区 */
+  (e: 'datasets-change'): void;
 }
 /** 在组件内部引用 */
 interface _ReportDesignerExposed {

package/dist/types/report-viewer.d.ts

@@ -17,8 +17,8 @@ interface ReportViewerProps {
   /** 承载填充报表的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
   workbook?: Workbook;
   /**
-   * 列宽（sheet-core 列宽未进 SheetSnapshot）：载入填充结果后写入 VTable 运行时，
-   * 供 `exportXlsx()` 读取保真列宽（设计器预览态传入设计态捕获值）
+   * 列宽显式覆盖（可选）：优先于模板 `colWidths` / 展开映射结果写入模型与网格。
+   * 列宽已进 `SheetSnapshot.colWidths`，通常无需再传。
    */
   colWidths?: ReadonlyArray<ReportColWidthEntry>;
 }

package/dist/types/sheet.d.ts

@@ -33,6 +33,10 @@ interface SheetProps {
   showFormulaBar?: boolean;
   /** 是否显示底部 sheet 标签栏，默认 true */
   showTabs?: boolean;
+  /** 是否显示行号列，默认 true */
+  showRowHeader?: boolean;
+  /** 是否显示列字母表头，默认 true */
+  showColHeader?: boolean;
   /** 只读预览（关闭编辑回写、填充柄等写入口） */
   readonly?: boolean;
 }

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@veltra/sheet",
-  "version": "2.2.0",
+  "version": "2.3.1",
+  "homepage": "https://github.com/cabinet-fe/ultra-ui#readme",
+  "bugs": {
+    "url": "https://github.com/cabinet-fe/ultra-ui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cabinet-fe/ultra-ui",
+    "directory": "packages/sheet"
+  },
   "files": [
     "dist",
     "src"
@@ -30,12 +39,12 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.1.8",
     "@cat-kit/fe": ">=1.1.8",
-    "@veltra/compositions": "^1.5.0",
-    "@veltra/desktop": "^1.5.0",
+    "@veltra/compositions": "^1.6.2",
+    "@veltra/desktop": "^1.6.2",
     "@veltra/icons": "^1.5.0",
-    "@veltra/sheet-core": "^2.2.0",
-    "@veltra/styles": "^1.5.0",
-    "@veltra/utils": "^1.5.0",
+    "@veltra/sheet-core": "^2.3.1",
+    "@veltra/styles": "^1.6.2",
+    "@veltra/utils": "^1.6.2",
     "vue": ">=3.5.41"
   }
 }

package/src/components/report/__test__/conditional-rules-helpers.test.ts

@@ -72,6 +72,7 @@ describe('conditional-rules helpers', () => {
       '本格字段',
       '地区'
     ])
+    expect(ruleEvalFieldOptions('amount', fields).map((item) => item.value)).toEqual(['', 'region'])
     expect(RULE_SCOPE_OPTIONS.map((item) => item.label)).toEqual(['本格', '整行'])
     expect(resolveEvalFieldType({ operator: 'eq', value: '', style: {} }, 'amount', fields)).toBe(
       'number'

package/src/components/report/__test__/preview-grid-size.test.ts

@@ -0,0 +1,63 @@
+import type { SheetSnapshot } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { previewGridSize } from '../preview-grid-size'
+
+function snap(
+  partial: Partial<SheetSnapshot> & Pick<SheetSnapshot, 'cells'>
+): Pick<SheetSnapshot, 'cells' | 'merges' | 'meta' | 'rows'> {
+  return { merges: [], rows: 0, ...partial }
+}
+
+describe('previewGridSize', () => {
+  it('template 模式用内容包围盒，忽略设计态 canvas 尺寸', () => {
+    expect(
+      previewGridSize(
+        snap({
+          cells: [
+            { row: 0, col: 0, v: '客户' },
+            { row: 0, col: 1, v: '金额' }
+          ],
+          rows: 24,
+          cols: 10
+        }),
+        'template'
+      )
+    ).toEqual({ rows: 1, cols: 2 })
+  })
+
+  it('filled 模式行保留展开布局尺寸，列按包围盒收敛（去掉设计态撑大的列）', () => {
+    expect(
+      previewGridSize(
+        snap({
+          cells: [
+            { row: 0, col: 0, v: '客户' },
+            { row: 3, col: 1, v: 300 }
+          ],
+          rows: 4,
+          cols: 10
+        }),
+        'filled'
+      )
+    ).toEqual({ rows: 4, cols: 2 })
+  })
+
+  it('空快照至少 1×1（VTable 需要非零网格）', () => {
+    expect(previewGridSize(snap({ cells: [] }), 'template')).toEqual({ rows: 1, cols: 1 })
+  })
+
+  it('包围盒计入合并区终点与 meta 绑定格', () => {
+    expect(
+      previewGridSize(
+        snap({
+          cells: [{ row: 0, col: 0, v: '标题' }],
+          merges: [{ start: { row: 0, col: 0 }, end: { row: 0, col: 2 } }],
+          meta: [{ row: 2, col: 1, namespace: 'report', payload: {} }],
+          rows: 24,
+          cols: 10
+        }),
+        'template'
+      )
+    ).toEqual({ rows: 3, cols: 3 })
+  })
+})