Программно добавляет
лист диаграммы BIFF8 в рабочую книгу, возвращая новую вкладку
TXLSWorksheet. Ранее листы диаграмм можно было только непрозрачно сохранять при загрузке-сохранении через
TXLSCustomChart; данный метод записывает полный подпоток диаграммы непосредственно в
SaveAs(xlExcel97). Excel открывает результат как вкладку диаграммы запрошенного типа. Доступно с версии v2.41.0 (Дорожная карта #10, Фаза 1); перегрузка с массивом серий следует в v2.42.0
Перечисление TXLSChartType
Выбирает тип диаграммы. Реэкспортируется из lxHandle, чтобы пользовательский код не нуждался в импорте модуля построителя диаграмм напрямую
type
TXLSChartType = (
xlsChartTypeColumn,
xlsChartTypeBar,
xlsChartTypeLine,
xlsChartTypePie);
Запись TXLSChartSeriesInfo
Содержит одно объявление серии для перегрузки с 6 параметрами. Categories и Values — строки диапазонов в стиле A1 (например, 'Sheet1!$B$2:$B$5')
type
TXLSChartSeriesInfo = record
Name : WideString;
Categories : WideString;
Values : WideString;
end;
Синтаксис
Пять перегрузок охватывают всё более расширенные определения листа диаграммы
// 1) v2.41.0 — name only; default column chart, no titles, no series.
function AddChartSheet(const Name: WideString): TXLSWorksheet;
// 2) v2.41.0 — name + chart type.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType): TXLSWorksheet;
// 3) v2.41.0 — + chart title.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title: WideString): TXLSWorksheet;
// 4) v2.41.0 — + category-axis title + value-axis title.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title : WideString;
const CatAxisTitle: WideString;
const ValAxisTitle: WideString): TXLSWorksheet;
// 5) v2.42.0 — + array of series (Name + Categories range + Values range).
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title : WideString;
const CatAxisTitle: WideString;
const ValAxisTitle: WideString;
const Series : array of TXLSChartSeriesInfo): TXLSWorksheet;
Примечания
Выпускаемый подпоток диаграммы охватывает структуру BIFF8, предусмотренную спецификацией: BOF (dt=$0020), Chart / PlotGrowth / Frame / Series / SheetProperties / AxesUsed / AxisParent (POS + ось категорий + ось значений + PlotArea + Frame + ChartFormat + запись типа диаграммы + ChartFormatLink + Legend), EOF. Существующий механизм round-trip листов диаграмм через TXLSCustomChart не изменён
Привязка имён серий (v2.42.0): каждое непустое значение Series[i].Name записывается в подпоток диаграммы как литеральная метка серии посредством PTG-токена tStr в BRAI имени серии (id=2). Excel использует эту метку в легенде и выборщике серий, поэтому многосерийные диаграммы отображают корректные подписи вместо стандартных заполнителей "Series1 / Series2"
Привязка диапазонов серий (v2.47.0): начиная с версии v2.47.0, строки диапазонов A1 Categories и Values компилируются в реальные ссылки на диапазоны ячеек tArea3D внутри BRAI, проходя через компилятор формул и таблицу ссылок EXTERNSHEET рабочей книги. До v2.47.0 эти два поля принимались в API, но записывались как заполнители cce=0, из-за чего отображаемая диаграмма была пустой. Существующие вызовы v2.42.0, оставляющие Categories / Values пустыми, не затрагиваются
Возвращённый объект TXLSWorksheet появляется в коллекции Sheets и при сохранении получает запись boundsheet листа диаграммы. Методы уровня ячейки на результате не поддерживаются — лист-хост является контейнером диаграммы, а не листом данных
Пример
Данный пример создаёт рабочую книгу с листом данных и столбчатой диаграммой, привязанной к двум столбцам этого листа
var
Series: array of TXLSChartSeriesInfo;
begin
// Populate cells on Sheet1.
Workbook.Sheets[1].Name := 'Data';
// ... fill A1:B5 with categories + values ...
SetLength(Series, 1);
Series[0].Name := 'Quarterly Revenue';
Series[0].Categories := 'Data!$A$2:$A$5';
Series[0].Values := 'Data!$B$2:$B$5';
Workbook.Sheets.AddChartSheet(
'Revenue',
xlsChartTypeColumn,
'Quarterly Revenue',
'Quarter',
'USD',
Series);
Workbook.SaveAs('Revenue.xls', xlExcel97);
end;
Ограничения
Детали форматирования для конкретных типов диаграмм (ширина зазора, перекрытие полосок, размер отверстия круговой диаграммы, стиль маркера) по-прежнему задаются в соответствии с настройками построителя диаграмм по умолчанию и пока не доступны через API. Сохранение и повторное открытие в Excel сохраняет наличие листа диаграммы, тип, заголовок, подписи осей, подписи серий и (начиная с v2.47.0) привязку данных серий
См. также