技术文章

使用 HotXLS 在 Delphi 中复制 XLSX 工作表

你已经把一张工作表调得完全到位:标题带已合并,列宽贴合数据,顶端两行已冻结,打印区域和页边距为干净的 A4 导出设好,工作表标签也上了色,方便财务一眼找到。现在报表需要十二张这样的表,每个区域一张,全部从同一份版式出发。用代码把这张表重建十二遍,细微的偏差就是这么混进来的:区域 7 的某一列窄了一磅,区域 11 丢了冻结窗格,等 PDF 送到经理桌上才有人发现。你真正想要的,是 Excel 里右键、移动或复制、建立副本这一套操作的程序化版本:拿做好的工作表,批量盖出相互独立的副本

HotXLS 是一个读写 Excel 文件、无需自动化 Excel 本身的 Delphi 与 C++Builder 原生库,它的 XLSX 引擎本来就能移动工作表、删除工作表、跨表复制单元格区域,而从 v2.91.0 起还能一次调用克隆整张工作表。入口有两个:TXLSXWorksheet.CopyFrom 把一张工作表的表级状态复制到另一张上,TXLSXSheets.Duplicate 则新增一张工作表并替你调用 CopyFrom。有意思的不是它能复制东西,而是它在深复制与浅复制之间划下的那条刻意为之的线,以及这条线为什么划在那里

HotXLS 的 Duplicate 与 CopyFrom 入口示意图:两者经由同一个复制引擎克隆 Delphi XLSX 工作表,带 nil 与自复制保护,返回一张独立工作表
Duplicate 用一张新表包装 CopyFrom,索引无效时返回 nil 而不是抛异常

一次调用克隆做好的工作表

高阶入口是 Duplicate。把源工作表的 1-based 索引交给它,它会返回一张全新的工作表,版式和数据都与原表一致。索引约定与 XLSX 侧的 Items[] 一致,所以第一张表是索引 1,不是 0;索引越界时返回 nil 而不是抛异常,与 XLSX 工作表集合其余部分遵循的失败契约相同

var
  Book: TXLSXWorkbook;
  Template, Copy: TXLSXWorksheet;
begin
  Book := TXLSXWorkbook.Create;
  try
    Template := Book.Sheets.Add('Template');
    Template.Cells[1, 1].Value := 'Quarterly Statement';
    Template.Range['A1:C1'].Merge;
    Template.ColWidth[1] := 18;
    Template.FreezePanes(2, 1);          // freeze top row + first column
    Template.TabColorIsAuto := False;
    Template.TabColor := $FF1F4E79;

    // Clone with an explicit name...
    Copy := Book.Sheets.Duplicate(1, 'Region-North');
    // ...or let it pick the Excel-style default name.
    Copy := Book.Sheets.Duplicate(1);    // -> "Template (2)"

    Book.SaveAs('regions.xlsx');
  finally
    Book.Free;
  end;
end;

这段代码里有两处值得放慢速度。第一,FreezePanes 的参数是行在前的 FreezePanes(ARow, ACol),与 Cells[Row, Col] 的索引顺序一致;副本会原样继承冻结切分。第二,这个方法叫 Duplicate 而不是更直觉的 Copy,这不是命名口味问题。Copy 是 System 单元里的标准例程,字符串和动态数组天天在用;类上再叫 Copy 的方法会在方法体内部遮蔽它,恰恰制造那种半年后才咬你一口的解析歧义。Duplicate 完全绕开这个问题,在调用点读起来也顺

默认命名遵循 Excel 自家的规则

调用单参数重载或传入空名称字符串时,新工作表会以源表命名并加 (2) 后缀,后缀不断递增直到名称唯一。把 Template 表复制一次得到 Template (2);再复制一次得到 Template (3),因为 Template (2) 已经被占了。这与 Excel 自己的建立副本命令生成的名称如出一辙,你的代码产出的工作簿看起来就是用户熟悉的、手工复制出来的样子。唯一性检查针对的是活动工作表集合,也就是说它同样会避开你手动创建的名称,而不只是早先复制产生的名称

如果要做每区域一张或每月一张的工作表,请改用显式名称重载。可预期的 Region-North、Region-South 命名方案,日后引用起来比一串 (2)、(3) 后缀轻松,也让你定义的名称和跨表公式保持可读

CopyFrom 深复制的内容

在底层,Duplicate 先新增工作表再调用 CopyFrom(ASource);想克隆到一张已经建好的工作表上时,也可以直接调用它。CopyFrom 会先挡掉两种退化情形:从 nil 复制,或把工作表复制到它自己,两者都立即返回、什么都不做。之后的全部内容就是复制本身,而且覆盖面刻意放得很宽

单元格数据最先来。CopyFrom 向源表要来 UsedRange——已填充单元格与合并区域的紧凑边界框——然后复用现成的 CopyRangeTo 机制,把每个值、公式和逐单元格样式索引进目标,从 A1 开始。在单元格之上,它还会重放让模板显得成品化的整层表级状态:

  • 合并区域:按坐标重新建立,横幅因此跨在同一个矩形上
  • 列宽与行高,加上隐藏、折叠和大纲级别清单:逐字复制,非默认的行和列因此精确对位
  • 冻结窗格与视图状态:缩放比例、网格线和零值显示、从右到左方向,以及视图类型
  • 保护状态及其按动作的权限选项:被锁定的模板会以同样的方式保持锁定
  • 整个页面设置块:页边距、方向、纸张大小、缩放与适应页面、打印区域、打印标题、页眉页脚,以及打印网格线和打印标题开关
  • 自动筛选范围、标签颜色和工作表可见性

结果是一张在打印、筛选和呈现上都与源表一致的工作表。而且单元格、合并区域和维度清单是在新表上物理重建的,不是别名引用,所以副本完全独立。往副本的单元格里写 999,源表保持原值;对要并行出多区域报表的克隆来说,这种独立性是唯一最重要的性质,随库附带的 SheetCopy 示例对此有显式断言

保持浅复制的内容及其原因

这条边界同样刻意。图表、内嵌图片、XLSX 表格、数据验证和条件格式规则都不会被复制。这是有文档记载的设计决策,理解其理由,才能围绕它做规划而不是被它吓一跳

这些集合每一个都带着身份和引用,天真的字段复制带不走它们。图表指向源数据区域,并在 OOXML 包里持有一段绘图关系;克隆对象时若不重映射关系和系列引用,得到的图表要么对着错误的数据渲染,要么产出一个被 Excel 标记需要修复的包。表格的名字必须在工作簿内唯一,表头行绑定特定列,还有自己的自动生成关系。条件格式和数据验证附着在坐标范围上,验证还可能用公式引用其他范围。要把其中任何一个正确深复制,就得重写引用、铸造新身份,这是带着真实失败模式的真实工作量。做一半——复制对象却不复制引用——比不复制更糟:产出的是一个打开就弹修复提示并悄悄丢内容的文件。所以引擎把它能干净复制的东西复制走,把带引用的集合留给调用者,因为只有调用者知道目标应该指向哪里

落到实践上,更丰富的模板工作流是:先复制工作表拿到单元格、版式和打印设置,再用第一次创建它们时的同一套 API,在副本上重建图表、表格、验证或条件格式。因为你是对着副本自己的范围重建,引用天生就是对的。对读取 A1:C10 的图表,在副本上新增一个指向副本 A1:C10 的图表;想让自动筛选继续生效,注意筛选范围是会带过来的,你只需重新套用列条件。条件格式和数据验证规则则按合并单元格与报表模板版式一文描述的同一批调用重新添加,那篇文章讲解了副本继承的合并表与范围模型

HotXLS 在 Delphi 中复制 XLSX 工作表的分工示意图:版式状态由 CopyFrom 深复制,带引用的图表、表格和规则留给调用者重建
版式、打印设置和保护可以干净深复制;图表、表格和规则带着必须重建的引用

复制在报表管线中的位置

工作表复制是占位符驱动生成的天然搭档。Delphi 模板驱动报表生成指南里的标记锚定方法解决的是把数据写进别人要编辑的版式这一问题;复制解决的是在同一工作簿里需要这份版式很多次的问题。两者结合,模式很干净:保留一张原封未动、带着标记、合并和打印设置的 Template 工作表,然后每个区域或每个周期调用一次 Duplicate,把该切片的数据填进副本的标记,继续下一张。原模板从不被改动,因此始终是下一张克隆的可靠来源,每张输出表都从逐字节相同的版式出发

一个顺序上的注意事项能省掉一类困惑:先把工作表复制出来,再往里灌数据,而不是反过来。模板应该保存结构和格式,而不是上个季度的数字;克隆一张空的带样式工作表,意味着每张副本都从干净状态开始。如果你复制的是已经带数据的工作表,数据会跟着走,因为 CopyFrom 会忠实复制已用区域;偶尔这正是你想要的,但对扇出式报表通常不是

HotXLS 在 Delphi 中的报表管线示意图:把一张原封未动的带样式 XLSX 模板工作表复制成各区域副本,每张副本只在克隆之后才填入自己的数据
模板保持原封未动,按区域复制,克隆之后才灌数据

一个快速验证习惯

深复制与浅复制的分界在你主动去找之前是看不见的,所以别默认一切都复制过来了,而是在作业里内置一个五行的检查。复制完成后,读回副本理应继承的结构信号,断言它们与源表一致

Copy := Book.Sheets.Duplicate(1, 'Region-North');
WriteLn(Format('merged=%d  colA=%.1f  freezeRow=%d  tabAuto=%d',
  [Copy.MergedCells.Count, Copy.ColWidth[1],
   Copy.FreezeRow, Integer(Copy.TabColorIsAuto)]));
// Prove independence: mutate the copy, confirm the source is untouched.
Copy.Cells[2, 2].Value := 999;
// Template.Cells[2, 2].Value is still whatever it was.

合并数量、某一列的列宽、冻结行和标签颜色旗标,会告诉你确实被复制的那一层真的到位了。另外,在任何原本带图表、表格、验证或条件格式的工作表上,把这些当作副本上的待重建清单:缺了是设计使然,重建只需几个调用。该深的地方深、引用会断的地方保持浅——这一心智模型就是用好这个特性的全部关键

本文描述的工作表复制与 CopyFrom 工作表状态复制随原生 HotXLS Delphi 电子表格组件的 v2.91.0 发布,同批还附带一个可运行的 SheetCopy 示例,端到端演练克隆加修改的完整周期