Один лист у вас уже доведен до идеала. Полоса заголовка объединена, ширины столбцов соответствуют данным, верхние две строки закреплены, область печати и поля настроены под аккуратный экспорт на A4, а вкладка окрашена так, чтобы отдел финансов быстро ее находил. Теперь отчету нужно двенадцать таких листов, по одному на регион, и каждый должен начинаться с одинакового макета. Пересобирать этот лист в коде двенадцать раз означает приглашать медленное расхождение: для региона 7 один столбец станет на point уже, регион 11 потеряет закрепление, и никто не заметит этого, пока PDF не окажется на столе у менеджера. На деле вам нужна программная версия правого клика Excel, Move or Copy, Create a copy: взять готовый лист и штамповать из него независимые дубликаты
XLSX-движок в HotXLS, нативной Delphi и C++Builder библиотеке, которая читает и пишет Excel-файлы без автоматизации самого Excel, умеет перемещать листы, удалять листы и копировать диапазоны ячеек между листами, а с версии v2.91.0 он ещё и клонирует целый worksheet одним вызовом. Работу делают две точки входа: TXLSXWorksheet.CopyFrom, копирующая состояние уровня листа с одного worksheet на другой, и TXLSXSheets.Duplicate, которая добавляет новый лист и сама запускает CopyFrom. Интересно тут не то, что что-то копируется. Интересна проведённая граница между тем, что копируется глубоко, а что нет, и почему она проходит именно там
Один вызов для клонирования готового листа
Операция верхнего уровня это Duplicate . Передайте ей 1-based индекс исходного листа, и она вернет совершенно новый worksheet, повторяющий исходный layout и данные. Соглашение об индексах совпадает с Items[] на стороне XLSX, поэтому первый лист имеет индекс 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); // закрепить верхнюю строку + первый столбец
Template.TabColorIsAuto := False;
Template.TabColor := $FF1F4E79;
// Клонировать с явным именем...
Copy := Book.Sheets.Duplicate(1, 'Region-North');
// ...или пусть выберет имя по умолчанию в стиле Excel.
Copy := Book.Sheets.Duplicate(1); // -> "Template (2)"
Book.SaveAs('regions.xlsx');
finally
Book.Free;
end;
end;
В этом фрагменте стоит замедлиться на двух вещах. Во-первых, FreezePanes принимает аргументы в порядке row-first, FreezePanes(ARow, ACol) , поэтому он выровнен с индексацией Cells[Row, Col] . Дубликат наследует точную границу закрепления. Во-вторых, метод называется Duplicate , а не более очевидно Copy , и это не stylistic preference. Copy является стандартной процедурой в модуле System и постоянно используется для строк и dynamic array. Метод с именем Copy в классе затенял бы его внутри тел методов и создавал бы именно ту неоднозначность разрешения имен, которая бьет по вам через полгода. Duplicate обходит эту проблему целиком и при этом читается правильно в точке вызова
Имя по умолчанию следует правилу самого Excel
Когда вы вызываете overload с одним аргументом или передаете пустую строку имени, новый лист получает имя исходного с суффиксом (2) , и суффикс повышается до тех пор, пока имя не станет уникальным. Продублируйте лист Template один раз и получите Template (2) . Продублируйте его еще раз и получите Template (3) , потому что Template (2) уже занято. Это повторяет имена, которые Excel генерирует в своей команде Create a copy, поэтому workbook, созданный вашим кодом, выглядит так, как пользователь ожидает от ручного дублирования. Проверка уникальности идет по живой коллекции листов, а значит, она обходит и имена, которые вы создавали вручную, а не только результаты предыдущих дублирований
Если вы генерируете один лист на регион или месяц, лучше опирайтесь на overload с явным именем. Предсказуемая схема Region-North , Region-South удобнее для последующего обращения, чем цепочка суффиксов (2) , (3) , и она делает defined names и cross-sheet formulas более читаемыми
Что CopyFrom копирует глубоко
Под капотом Duplicate добавляет лист, а затем вызывает CopyFrom(ASource) , который вы можете вызывать и напрямую, когда хотите клонировать содержимое на лист, уже созданный заранее. CopyFrom сразу закрывает два вырожденных случая: копирование из nil или копирование листа в самого себя, в обоих случаях метод просто сразу выходит и ничего не делает. Все, что идет дальше, это собственно копирование, и оно намеренно широкое
Сначала идут данные ячеек. CopyFrom запрашивает у источника его UsedRange , компактную ограничивающую рамку заполненных ячеек и merged regions, а затем повторно использует имеющуюся механику CopyRangeTo , чтобы перенести в target каждое значение, формулу и индекс стиля ячейки, начиная с A1 . Поверх ячеек он воспроизводит полный слой состояния уровня листа, который и делает шаблон завершенным:
- Merged ranges, пересоздаваемые по координатам, чтобы заголовочная полоса перекрывала тот же прямоугольник
- Ширины столбцов и высоты строк, а также списки hidden, collapsed и outline-level, копируются дословно, чтобы нестандартные строки и столбцы выравнивались точно
- Freeze panes и view state: zoom level, отображение gridline и zero-value, направление right-to-left и тип view
- Состояние protection с его опциями разрешений для отдельных действий, чтобы заблокированный шаблон оставался заблокированным тем же способом
- Весь блок page setup: margins, orientation, paper size, scaling и fit-to-page, print area, print titles, headers и footers, а также флаги print-gridlines и print-headings
- Диапазон AutoFilter, цвет вкладки и видимость листа
Результат состоит в том, что лист печатается, фильтруется и выглядит идентично источнику. А поскольку ячейки, merged ranges и списки размеров физически пересоздаются на новом листе, а не получают общие ссылки, дубликат полностью независим. Запишите 999 в ячейку на копии, и источник сохранит исходное значение. Эта независимость является самым важным свойством клона, предназначенного для параллельных региональных отчетов, и поставляемый demo SheetCopy проверяет это явно
Что остается поверхностным и почему
Граница проведена столь же намеренно. Charts, встроенные изображения, таблицы XLSX, data validations и правила conditional formatting не копируются. Это задокументированное проектное решение, и стоит понять его мотивацию, чтобы планировать работу с оглядкой на него, а не удивляться постфактум
Каждая из этих коллекций несёт идентичность и ссылки, которые не переживают наивное копирование в лоб. Chart указывает на исходный диапазон данных и владеет drawing relationship в OOXML-пакете; клонировать объект без перемапа relationship и ссылок series — значит получить диаграмму, рендерящуюся по чужим данным, или пакет, который Excel пометит как требующий ремонта. У table есть имя, уникальное в пределах workbook, строка заголовка, привязанная к конкретным столбцам, и собственная автосгенерированная relationship. Conditional formats и data validations привязываются к диапазонам координат, а validations могут ещё и ссылаться на другие диапазоны по формуле. Корректный deep-copy любой из этих коллекций означает переписывание ссылок и выдачу свежих идентификаторов — это настоящая работа с настоящими режимами отказа. Полумера — скопировать объект, но не его ссылки — хуже, чем не копировать вовсе: получается файл, который открывается с предложением ремонта и молча теряет содержимое. Поэтому движок копирует то, что копируется чисто, а коллекции, несущие ссылки, оставляет вызывающему — он-то знает, на что должен указывать target
На практике это означает такой workflow для более богатого шаблона: продублировать лист, чтобы получить ячейки, layout и print setup, а затем заново построить chart, table, validations или conditional formats на копии тем же API, который вы использовали при первом создании. Поскольку вы пересоздаете их уже относительно собственных диапазонов дубликата, ссылки по построению получаются корректными. Для chart, который читает A1:C10 , добавьте на копии новый chart, указывающий на A1:C10 этой копии. Для AutoFilter, который должен остаться рабочим, помните, что диапазон фильтра переносится, поэтому вам нужно лишь заново применить критерии по столбцам. Правила conditional formatting и data validation вы добавляете теми же вызовами, что описаны в статье об объединенных ячейках и layout шаблонов отчетов , где разбираются merge table и range model, которые копия унаследует
Где дублирование вписывается в reporting pipeline
Дублирование worksheet является естественным дополнением к генерации, основанной на placeholder. Подход с токенами в руководстве по template-driven генерации отчетов в Delphi решает задачу записи данных в layout, который редактируют другие люди. Дублирование решает задачу, когда такой layout нужен много раз в одном workbook. Вместе шаблон получается чистым: храните один безупречный лист Template с его токенами, merged ranges и print setup, затем для каждого региона или периода вызывайте Duplicate , заполняйте токены клона соответствующим срезом данных и переходите к следующему. Исходный template никогда не мутируется, поэтому он остается надежным источником для следующего клона, а каждый выходной лист начинается с побайтно идентичного layout
Одна заметка о порядке операций избавляет от целого класса недоразумений. Дублируйте лист до того, как начнете заливать в него данные, а не после. Template должен хранить структуру и оформление, а не цифры за прошлый квартал, и клонирование пустого, но оформленного листа означает, что каждый дубликат начинается чистым. Если продублировать лист, который уже содержит данные, эти данные перейдут вместе с ним, потому что CopyFrom копирует used range честно и полностью. Иногда именно это вам и нужно, но для fan-out отчета обычно нет
Быстрая привычка проверки
Поскольку разделение на deep-copy и shallow-copy незаметно, пока вы специально его не проверите, лучше встроить в задание пятирядную проверку, чем просто верить, что все перенеслось как надо. После дублирования прочитайте назад структурные сигналы, которые клон обязан унаследовать, и зафиксируйте, что они совпадают с источником
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)]));
// Докажите независимость: измените копию, подтвердите, что источник не тронут.
Copy.Cells[2, 2].Value := 999;
// Значение Template.Cells[2, 2].Value всё ещё то, каким было.
Количество merge, ширина одного столбца, номер freeze row и флаг tab colour показывают, что слой, который должен копироваться, действительно доехал. Отдельно: в любом листе, где были chart, table, validations или conditional formats, считайте их списком к пересборке на копии — их отсутствие задумано, а пересборка стоит нескольких вызовов. Эта ментальная модель — deep там, где безопасно, и shallow там, где сломались бы ссылки, — и есть вся история того, как правильно пользоваться этой возможностью
Дублирование worksheet и копирование состояния листа через CopyFrom поставляются в v2.91.0 нативного табличного компонента HotXLS для Delphi вместе с запускаемым примером SheetCopy, который прогоняет цикл клонирования и мутации от начала до конца