Lazarus модуль работы с excel

│




Deutsch (de) │
English (en) │

español (es) │


français (fr) │







polski (pl) │


русский (ru) │

FpSpreadsheet библиотека предоставляет удобный способ создания и чтения табличных документов в различных форматах. Библиотека написана на очень гибкой основе, и поэтому её можно легко расширять поддержкой любого количества форматов.

Скриншот демонстрационной программы spready, предоставляемой с fpspreadsheet, показывающим файл XLS:

Документация

Эта страница вики включает последнюю версию FPSpreadsheet, доступную через subversion. Пожалуйста, см. раздел Стабильные версии для [получения] документации по стабильной версии, которую вы можете скачать.

Документация по API

Ссылка на API

Файл справки в формате CHM можно найти в папке установки FPSpreadsheet docs. Если вы еще не установили пакет, тогда следуйте сюда https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/components/fpspreadsheet/docs

Второй файл CHM, доступный в папке docs, fpspreadsheet-wiki.chm, представляет собой снимок связанных с FPSpreadsheet страниц вики, объединенных в один файл справки.

Основы

Наименьшими объектами в электронной таблице являются «ячейки», содержащие данные. Ячейки могут содержать различные типы данных, такие как строки, числа, даты, время, логические значения или формулы. Кроме того, ячейки могут содержать информацию о форматировании, то есть стиль шрифта, цвет фона, выравнивание текста и т.д.

Ячейки расположены в сетке, называемой «рабочей таблицей», или «электронной таблицей», состоящей из «строк» и «столбцов». Каждая ячейка имеет уникальный адрес, заданный индексом строки и столбца.

Рабочие листы связаны вместе, формируя «книгу», которая представляет собой документ электронной таблицы приложения. В книге также хранится информация, необходимая для всех листов, то есть список шрифтов, списки сотовых и числовых форматов и т.д.

FPSpreadsheet следует этой же структуре — существует TCell, TsWorksheet и TsWorkbook .

Рабочая книга

Класс TsWorkbook является основным классом, видимым для пользователя. Он предоставляет методы для чтения данных и записи в файлы. Универсальная структура библиотеки обеспечивает доступ к различным популярным форматам файлов, таким как Excel .xls или .xlsx, или OpenOffice/LibreOffice .ods.

Формат файла определяется типом TsSpreadsheetFormat, определенным в модуле fpstypes

type
  TsSpreadsheetFormat = (sfExcel2, sfExcel5, sfExcel8, sfExcelXML, sfOOXML, 
    sfOpenDocument, sfCSV, sfHTML, sfWikiTable_Pipes, sfWikiTable_WikiMedia, sfUser);

где

• sfExcel2, sfExcel5, sfExcel8 означает версии бинарного формата xls, используемые Excel («BIFF» = «Формат файла двоичного обмена»), причем sfExcel8 является самым современным.
• sfOOXML соответствует новому формату xlsx, представленному Excel2007
• sfExcelXML — это xml-формат, который был представлен Microsoft для Office XP и 2003. Не очень популярен.
• sfOpenDocument — формат электронных таблиц, используемый OpenOffice/LibreOffice; по умолчанию файлы имеют расширение .ods.
• sfCSV относится к текстовым файлам с разделителями-запятыми (расширение по умолчанию .csv); они могут быть поняты любым текстовым редактором и всеми программами электронных таблиц, но не содержат информации о форматировании.
• sfHTML обозначает стандартный формат HTML, используемый в веб-браузерах.
• sfWikiTable_Pipes и sfWikiTable_WikiMedia — это формат, используемый таблицами в вики-сайтах.
• sfUser необходим для регистрации пользовательского формата. Планируется внедрение «древних» форматов файлов, таких как Excel3.0/4.0 или Lotus. Тем не менее, вы можете предоставить свои собственные классы чтения и письма для расширения функциональности FPSpreadsheet — см. ниже раздел Добавление новых форматов файлов

При применении fpspreadsheet первая задача — создать экземпляр рабочей книги:

var
  MyWorkbook: TsWorkbook;
begin
  MyWorkbook := TsWorkbook.Create;
  ...

Чтение файлов электронных таблиц выполняется (среди прочего) методами рабочей книги

• procedure ReadFromFile (AFileName: string):
  Читает файл с заданным именем и автоматически определяет правильный формат файла.
• procedure ReadFromFile (AFileName: string; AFormat: TsSpreadsheetFormat):
  Читает файл, но предполагает, что формат файла соответствует AFormat .

Для сохранения файла можно использовать следующие методы работы с книгой:

• procedure WriteToFile (const AFileName: string; const AFormat: TsSpreadsheetFormat; const AOverwriteExisting: Boolean = False):
  Записывает книгу в данный файл с использованием заданного формата электронной таблицы. Если файл уже существует, он автоматически перезаписывается, если AOverwriteExisting — true :
• procedure WriteToFile (const AFileName: String; const AOverwriteExisting: Boolean = False):
  так же, но формат файла определяется из предоставленного расширения файла (в случае Excel больше xls используется последняя версия, sfExcel8).

После вызова этих методов полезно посмотреть на свойство рабочей книги ErrorMsg, в котором собраны сообщения из-за ошибок или предупреждений, которые могли возникнуть во время чтения/записи. Это свойство возвращает многострочную строку, которая лучше всего отображается в компоненте memo; если все в порядке, это пустая строка.

Примечание. FPSpreadsheets предоставляет специализированные блоки для чтения и записи в каждый формат файла. Эти блоки недоступны автоматически, вы должны явно добавить их в предложение uses. FPSpreadsheet будет жаловаться на «неподдерживаемый формат файла», если запрошенный читатель/писатель не найден. Ниже приведен список названий устройств:

• xlsbiff2, xlsbiff5 и xlsbiff8 для двоичных форматов файлов xls sfExcel2, sfExcel5 и sfExcel8 , соответственно,
• xlsOOXML для формата xlsx sfOOXML для Excel 2007 и более поздних версий,
• xlsXML для XML-формата Excel XP и 2003,
• fpsopendocument для формата файла sfOpenDocument OpenOffice/LibreOffice,
• fpsCSV для текстовых файлов с разделенными запятыми значениями (csv),
• fpsHTML для файлов HTML,
• wikitables для sfWikiTable_Pipes и sfWikiTable_WikiMedia,
• или просто добавьте fpsallformats, чтобы получить поддержку чтения/записи для всех поддерживаемых форматов файлов.

Рабочий лист

В книге содержится список экземпляров TsWorksheet. Они соответствуют вкладкам, которые вы видите в Excel или Open/LibreOffice. При чтении файла электронной таблицы рабочие листы создаются автоматически в соответствии с содержимым файла. Когда электронная таблица создается вручную для хранения в файле, рабочий лист должен быть создан путем «добавления» в рабочую книгу:

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
begin
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My_Table');  
    // 'My_Table' - это «имя» рабочего листа
  ...

Доступ к уже имеющимся рабочим листам можно получить с помощью методов TsWorkbook

• function GetFirstWorksheet: TsWorksheet: извлекает первый рабочий лист книги.
• Функция GetWorksheetByIndex (AIndex: Cardinal): TsWorksheet: возвращает рабочий лист с заданным индексом (начиная с 0).
• function GetWorksheetByName (AName: String): TsWorksheet: возвращает рабочий лист с заданным именем, которое было использовано при добавлении рабочего листа.

Количество уже существующих рабочих листов можно запросить, вызвав GetWorksheetCount.

Ячейка

Рабочий лист, наконец, дает доступ к ячейкам. Недавно созданный рабочий лист, как в приведенном выше примере, пуст и не содержит никаких ячеек. Клетки добавляются путем присвоения им данных или атрибутов одним из методов WriteXXXX рабочего листа. Как уже упоминалось, ячейка адресуется индексом строки и столбца, к которой она принадлежит. Как обычно, индексы строк и столбцов начинаются с 0. Поэтому ячейка «A1» относится к строке 0 и столбцу 0. Следует отметить, что индекс строки и столбца всегда указывается в этом порядке, это отличается от соглашения TStringGrid. В следующем примере создается ячейка по адресу A1 и помещается в нее число 1.0.

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
begin
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My_Table');
  MyWorksheet.WriteNumber(0, 0, 1.0);  // "A1" имеет строку = 0 и столбец = 0
  ...

Также можно напрямую обращаться к ячейкам с помощью методов FindCell(ARow, ACol) или GetCell(ARow, ACol) рабочей книги. Обе функции существуют также в перегруженной версии, к которой адрес ячейки может быть передан в нотации Excel: FindCell(ACellStr: String) или GetCell(ACellStr: String). Имейте в виду, что эти функции возвращают указатель pointer к данным ячейки (тип PCell). Не забудьте разыменовать указатели! Разница между FindCell и GetCell заключается в том, что первая возвращает nil, если ячейка еще не существует, а вторая создает пустую ячейки в этом случае.

if MyWorksheet.FindCell('A1') = nil then
  WriteLn('Ячейка A1 не существует.');

Основной тип TCell record

Это объявление типа данных ячейки:

type
  TCell = record
    { Location of the cell }
    Worksheet: TsWorksheet;
    Col: Cardinal; // zero-based
    Row: Cardinal; // zero-based

    { Index of format record }
    FormatIndex: Integer;

    { Status flags }
    Flags: TsCellFlags;        // (cfHasComment, cfMerged, cfHyperlink, ...)

    { Cell content }
    UTF8StringValue: String;   // строки не могут быть частью варианта записи 
    case ContentType: TCellContentType of  // должно быть в конце объявления
      cctEmpty      : ();      // не имеет данных вообще
      cctFormula    : ();      // UTF8StringValue находится вне варианта записи
      cctNumber     : (Numbervalue: Double);
      cctUTF8String : ();      // FormulaValue находится вне варианта записи 
      cctDateTime   : (DateTimevalue: TDateTime);
      cctBool       : (BoolValue: boolean);
      cctError      : (ErrorValue: TsErrorValue);
  end;
  PCell = ^TCell;

Поле ContentType указывает, какой тип данных хранится в ячейке:

type
  TCellContentType = (cctEmpty, cctFormula, cctNumber, cctUTF8String, cctDateTime, cctBool, cctError);

Согласно этому полю соответствующие данные можно найти в полях

• NumberValue (для ContentType = cctNumber), или
• UTF8StringValue (для ContentType = cctUTF8String), или
• DateTimeValue (для ContentType = cctDateTime) или
• BoolValue (для ContentType = cctBool), то есть TRUE или FALSE, или
• ErrorValue (для ContentType = cctError).

Из-за использования варианта записи большинство из этих значений перекрываются, то есть модификация NumberValue влияет также на другие значения. Поэтому всегда обращайте внимание на ContentType при непосредственном доступе к записи TCell (описанные ниже методы рабочего листа рассматривают это автоматически).

Поле Flags указывает, связаны ли дополнительные данные с ячейкой, которые не включены в запись ячейки, как правило, для сохранения памяти:

type 
  TsCellFlag = (cfHasComment, cfHyperlink, cfMerged, cfHasFormula, cf3dFormula);
  TsCellFlags = set of TsCellFlag;

• cfHasComment: комментарий записи находится в comments рабочего листа.
• cfHyperlink: ячейка содержит гиперссылку, хранящуюся в Hyperlinks рабочего листа.
• cfMerged: ячейка принадлежит блоку объединенные ячейки и распространяется через несколько ячеек.
• cfHasFormula: ячейка связана с формулой, которая хранится в Formulas рабочего листа.
• cf3dFormula: Формула, связанная с ячейкой, содержит элементы, ссылающиеся на другие листы той же книги.

Как добавлять и считывать данные в/из ячейки

Добавление значений в ячейку наиболее легко сопровождается использованием одного из методов WriteXXXX рабочего листа. Наиболее важными являются:

type
  TsWorksheet = class
    ...
    { Запись денежных значений }
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = 2;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = -1;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1); overload;
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String); overload;

    {Запись значений дата/время }
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      ANumFormat: TsNumberFormat; ANumFormatStr: String = ''): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      ANumFormat: TsNumberFormat; ANumFormatStr: String = ''); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      ANumFormatStr: String): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      ANumFormatStr: String); overload;

    { Запись числовых значений } 
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      ANumFormat: TsNumberFormat; ADecimals: Byte = 2): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      ANumFormat: TsNumberFormat; ADecimals: Byte = 2); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String); overload;

    { Запись строковых значений }
    function WriteText(ARow, ACol: Cardinal; AText: ansistring;
      ARichTextParams: TsRichTextParams = nil): PCell; overload;
    procedure WriteText(ACell: PCell; AText: String;
      ARichTextparams: TsRichTextParams = nil); overload;

    // старые методы строк «WriteUTF8Text» сейчас устарели
    ...

Некоторые из этих методов существуют в перегруженных версиях, в которых параметры форматирования ячейки могут быть добавлены вместе со значением ячейки. Соответственно, для записи также существует несколько методов worksheet для чтения значений ячеек:

type
  TsWorksheet = class
    ...
    { Чтение содержимого ячейки как строки }
    function  ReadAsText(ARow, ACol: Cardinal): string; overload;
    function  ReadAsText(ACell: PCell): string; overload;
    function  ReadAsText(ACell: PCell; AFormatSettings: TFormatSettings): string; overload;

    { Чтение содержимого ячейки как числа }
    function  ReadAsNumber(ARow, ACol: Cardinal): Double; overload;
    function  ReadAsNumber(ACell: PCell): Double; overload;
    function  ReadNumericValue(ACell: PCell; out AValue: Double): Boolean;

    { Чтение содержимого ячейки как значения дата/время }
    function  ReadAsDateTime(ARow, ACol: Cardinal; out AResult: TDateTime): Boolean; overload;
    function  ReadAsDateTime(ACell: PCell; out AResult: TDateTime): Boolean; overload;
    ...

Индексирование формата ячейки

FormatIndex является индексом записи формата ячейки cell format record. Он описывает атрибуты форматирования ячейки. Эти записи собираются по внутреннему списку рабочей книги и определяются следующим образом:

type
  TsCellFormat = record
    FontIndex: Integer;
    TextRotation: TsTextRotation;
    HorAlignment: TsHorAlignment;
    VertAlignment: TsVertAlignment;
    Border: TsCellBorders;
    BorderStyles: TsCellBorderStyles;
    Background: TsFillPattern;
    NumberFormatIndex: Integer;
    NumberFormat: TsNumberFormat;
    NumberFormatStr: String;
    BiDiMode: TsBiDiMode;           // bdDefault, bdLTR {left-to-right}, bdRTL {right-to-left)
    Protection: TsCellProtection;   // cpLockCell, cpHideFormulas
    UsedFormattingFields: TsUsedFormattingFields;
      //uffTextRotation, uffFont, uffBold, uffBorder, uffBackground, uffNumberFormat, uffWordWrap, uffHorAlign, uffVertAlign, uffBiDi
  end;

• FontIndex: текстовый шрифт, указывает индекс в списке шрифтов книги
• TextRotation: указывает, будет ли текст ячейки написан горизонтально или вертикально
• HorAlignment: выравнивание по левому краю, по горизонтали или по правому краю
• VertAlignment: верхний, нижний или вертикально центрированный текст
• Border: набор флагов, указывающий, что — если установлено — линия границы нарисована в левом, верхнем, правом или нижнем краях ячеек. Линии рисуются в соответствии с BorderStyles, которые определяют линейность и цвет границы.
• Фон: запись, определяющая фоновое заполнение ячейки (стиль паттерна, цвет паттерна и цвет фона — см. главу фон ячейки ниже).
• NumberFormat и NumberFormatStr указывает способ форматирования числа или даты/времени (например, числа десятичных знаков, длинного или короткого формата даты и т.д.).
• При форматировании ячейки учитываются только те атрибуты формата, для которых установлен флаг в UsedFormattingFields. Если флаг не включен, соответствующий атрибут игнорируется и заменяется значением по умолчанию.

Для указания формата для данной ячейки вызывается соответствующий метод рабочего листа WriteXXXX, для получения вызова формата ReadXXXX. Эти методы обычно получают указатель на ячейку в качестве параметра, но также есть перегруженные версии, которые принимают индекс строки и столбца. Более того, стили форматирования также могут быть применены непосредственно к ячейке с помощью вспомогательного средства записи, реализованного в модуле fpsCell.

См. форматирование ячейки ниже для [получения] более подробного описания.

Столбцы и строки

Записи столбцов и строк добавляются для каждого столбца и строки с размером, отличным от значения по умолчанию:

type
  TCol = record
    Col: Cardinal;
    Width: Single;
    ColWidthType: TsColWidthType;     // = (cwtDefault, cwtCustom)
    FormatIndex: Integer;
  end;
  PCol = ^TCol;

  TRow = record
    Row: Cardinal;
    Height: Single;
    RowHeightType: TsRowHeightType;   // = (rhtDefault, rhtCustom, rhtAuto)
    FormatIndex: Integer;
  end;
  PRow = ^TRow;

[Свойства] Column widths и row heights могут быть указаны в различных единицах, определенных типом TsSizeUnits = (suChars, suLines, suMillimeters, suCentimeters, suPoints, suInches). suChars относится к счету символов 0, вписывающихся в ширину столбца, — таким образом Excel определяет ширину столбца. suLines — количество линий, вписывающихся в высоту строки. Оба устройства основаны на размере символа шрифта по умолчанию для книги. Другие единицы — условные физические единицы длины (1 см = 10 мм, 1 дюйм = 25,4 мм = 72 пт). Принимаются дробные значения. Рабочая книга и рабочие листы хранят длины внутри в миллиметрах (MyWorkbook.Units).

Приложения Office обычно настраивают высоту строки автоматически в соответствии с шрифтом или вращением текста [внутри] содержимого ячейки. Этот случай идентифицируется с помощью RowHeightType, имеющего значение rhtAuto. Поскольку рабочий лист не может рассчитывать размер текста очень точно, автоматические высоты строк не записываются в FPSpreadsheet; они заменяются на default row height. Высота строки по умолчанию также используется, если строка пуста, т.е. не содержит никаких ячеек данных. Его значение можно изменить, вызвав WriteDefaultRowHeight() или используя свойство DefaultRowHeight. В WriteDefaultRowHeight единицы должны быть указаны в DefaultRowHeight, [где] они считаются линиями. Аналогично, default column width может быть задана с помощью WriteDefaultColWidth() или свойством DefaultColWidth (в символах).

Для того, чтобы перехватить [установку] высоты строк автоматически и по умолчанию, вызовите метод WriteRowHeight(). Эти записи строк идентифицируются с помощью RowHeightType, имеющего значение rhtCustom. Точно так же ширина столбцов может быть установлена на определенное значение вызовом WriteColWidth(). ColWidthType этих столбцов cwtCustom.

Высоту/ширину конкретной строки/столбца можно получить с помощью методов GetRowHeight или GetColHeight. Обратите внимание, что эти методы возвращают ширину строк/столбцов по умолчанию, если нет записей TRow/TCol.

type TsWorksheet = class
  ...
  { Установка высоты строки }
  procedure WriteRowHeight(ARowIndex: Cardinal; AHeight: Single; AUnits: TsSizeUnits);
  { Установка ширины столбца }
  procedure WriteColWidth(AColIndex: Cardinal; AWidth: Single; AUnits: TsSizeUnits);
  { Установка высоты строки по умолчанию }
  procedure WriteDefaultRowHeight(AHeight: Single; AUnits: TsSizeUnits);
  {Установка ширины столбца по умолчанию }
  procedure WriteDefaultColWidth(AWidth: Single; AUnits: TsSizeUnits);

  { Возврат высоты строки }
  function GetRowHeight(ARowIndex: Cardinal; AUnits: TsSizeUnits): Single;
  { Возврат ширины столбца }
  function GetColWidth(AColIndex: Cardinal; AUnits: TsSizeUnits): Single;
  { Возврат высоты строки по умолчанию }
  function ReadDefaultRowHeight(AUnits: TsSizeUnits): Single;
  { Возврат ширины столбца по умолчанию }
  function ReadDefaultColWidth(AUnits: TsSizeUnits): Single;

  property DefaultRowHeight: Single;  // в линиях
  property DefaultColWidht: Single;   // в символах

Существуют также перегруженные версии этих методов, для которых не требуется параметр AUnits. В этом случае высота строк определяются в терминах количества строк, а ширина столбцов определяется в терминах количества символов. Обратите внимание, что эти варианты из предыдущих версий и теперь устарели.

Элемент FormatIndex формата строк и столбцов применяется ко всей строке или столбцу. Как и в ячейках, эти форматы хранятся в виде записей TsCellFormat во внутреннем списке книг. Row and column formats в основном применяются к пустым ячейкам, но если добавлена новая ячейка, она автоматически получит формат строки или столбца. (Если обе строки и столбец имеют разные форматы, тогда будет использоваться формат строки).

Формулы

Два вида формул поддерживаются FPSpreadsheet:

• Строковые формулы: написаны в строковом [формате], как в офисных приложениях, например «=ROUND(A1+B1,0)». Используются внутри файлов Open/LibreOffice и Excel .xlsx.
• Формулы RPN [(польской нотации)] используются внутри [приложения] двоичными файлами Excel .xls. Они написаны в Reverse Polish Notation (RPN)[«Обратной польской нотации»], например: A1, B1, Add, 0, ROUND. Если электронная таблица, содержащая формулы, должна быть сохранена в двоичном формате Excel, необходимые формулы RPN генерируются автоматически.

FPSpreadsheet может [производить] преобразования между формулами строк и RPN. Формулы в обоих типах могут быть рассчитаны.

В более старых версиях FPSpreadsheet формулы сохранялись непосредственно в записи ячейки. Это было сделано, чтобы получить анализируемые формулы для более быстрого вычисления. Формулы хранятся в дереве Formulas рабочего листа. Запись формулы содержит индекс строки и столбца ячейки, к которой относится формула, строковое представление формулы, а также дерево парсера для быстрой оценки.

FPSpreadsheet поддерживает большинство формул, предоставляемых обычными приложениями электронных таблиц. Однако при чтении файла, созданного этими приложениями, всегда существует вероятность того, что [в нем] содержится не поддерживаемая формула. Чтобы избежать сбоев fpspreadsheet, чтение формул по умолчанию отключено; ячейка отображает только результат формулы, написанной приложением Office. Чтобы активировать чтение формул, перед открытием файла добавьте элемент boReadformulas в [свойстве] Options книги. Если в этом случае возникает ошибка, читатель [(парсер)] обычно обходит исключение, записывает сообщение об исключении в журнал ошибок книги и продолжает чтение. Если вы хотите, чтобы чтение останавливалось, вы должны добавить boAbortReadingOnFormulaError в Options книги.

Формулы могут ссылаться на данные в других листах той же книги («3d формулы»), применяя синтаксис Excel (см. ниже). Внешние ссылки на электронные таблицы в других файлах не поддерживаются.

Вычисление формул обычно не требуется, когда файл написан [при помощи] FPSpreadsheet для открытия в приложении Office, потому что он автоматически вычисляет результаты формулы. Однако, если один и тот же файл открывается в приложении, основанном на FPSpreadsheet, вычисленные ячейки будут пустыми, потому что формулы по умолчанию автоматически не вычисляются. Чтобы активировать вычисление формул перед написанием электронной таблицы в файл, вы должны добавить опцию boCalcBeforeSaving в [свойство] Options книги.

Если FPSpreadshet используется в интерактивном приложении (таком, как демка «spready», расположенной в папке examples в [корневом каталоге] установки FPSpreadsheet), желательно автоматически вычислять формулы, когда пользовательские строки или значения ячеек изменяются пользователем. Этого можно достичь с помощью опции boAutoCalc в [свойстве] Options книги.

Таким образом, наиболее общая установка в отношении формул [такова]

  MyWorkbook.Options := MyWorkbook.Options + [boReadFormulas, boCalcBeforeSaving, boAutoCalc];

Вычисление формул можно запускать вручную, вызывая метод CalcFormulas рабочего листа или рабочей книги. Последнее абсолютно необходимо, когда книга содержит 3d формулы, где результат одной ячейки может влиять на ячейки в других листах. Если есть формулы [, используемые] только внутри рабочего листа, то достаточно [использование свойства] CalcFormulas рабочего листа.

Строковые формулы

Строковые формулы записываются так же, как и в приложениях Office. Метод рабочей таблицы для создания строковой формулы WriteFormula:

var
  MyWorksheet: TsWorksheet;
//...
  MyWorksheet.WriteFormula(0, 1, '=ROUND(A1+B2+1.215,0)');
  // По умолчанию используйте десятичную точку и запятую как разделитель списков!

Несколько замечаний по syntax:

• Ведущий символ =, который идентифицирует формулы в приложениях Office, здесь не является абсолютно необходимым и может быть удален. Формула хранится в записи ячейки без нее.
• Случай с именем формулы игнорируется.
• Пробелы могут быть добавлены для лучшей читаемости, но при сохранении они будут потеряны.
• Строки должны быть заключены в двойные кавычки.
• Угловые точки диапазона ячеек должны быть разделены двоеточием («:»), напр. A1:C3. Неопределенные диапазоны будут переупорядочены при анализе формулы, т.е. C3:A1 станет A1:C3.
• Ссылки на другие рабочие листы должны следовать синтаксису Excel, который разделяет имя листа и адрес ячейки на «!». Например, одну ячейку можно связать с помощью Sheet1!A1. Ряд листов должен быть помещен перед ячейкой или диапазоном ячейки, напр. Sheet1:Sheet2!A1:C3. Обратите внимание, что синтаксис Open/LibreOffice с разделителем и ссылкой на угловые точки 3d-блока (т.е. Sheet1.A1:Sheet2.C3) не поддерживается. Также обратите внимание на то, что рабочий(-ие) лист(-ы), на которые ссылается [добавляемая] формула, должна(-ы) существовать на момент добавления формулы; в противном случае ссылка будет заменена кодом ошибки #REF!, и формула не будет использоваться, даже если недостающий лист будет добавлен позже.
• Обычно числа с плавающей запятой должны вводиться с точкой в качестве десятичного разделителя, а запятая должна использоваться для разделения аргументов функции.
• Установка параметра ALocalized метода рабочего листа WriteFormula в TRUE не является обязательной, однако позволяет использовать локализованные десятичные [разделители] и разделители списков, взятые из FormatSettings рабочего листа — см. демо spready.

var
  MyWorksheet: TsWorksheet;
//...
  MyWorksheet.WriteFormula(0, 1, '=ROUND(A1+B2+1,215;0)', true);
  // Из-за "true" парсер формулы воспринимает запятую как десятичный разделитель и
  // точку с запятой в качестве разделителя списков, если формат FormatSettings книги yстановлен как здесь.

Use the worksheet methods ReadFormula or ReadFormulaAsString to retrieve the string formula assigned to the cell. The pointer to the cell must be given as a parameter. The latter function accepts an additional (boolean) parameter ALocalized to use the decimal and list separators of the workbook’s FormatSettings for creation of the formula string.

Используйте методы ReadFormula или ReadFormulaAsString рабочего листа для получения строковой формулы, присвоенной ячейке. Указатель на ячейку должен быть определен как параметр. Последняя функция принимает дополнительный (логический) параметр ALocalized для использования десятичных [разделителей] и разделителей списков свойства FormatSettings рабочей книги для создания строки формулы.

var
  MyWorksheet: TsWorksheet;
  cell: PCell;
//...
  cell := MyWorksheet.FindCell(0, 1);
  WriteLn('Формула во внутреннем формате - ', MyworkSheet.ReadFormula(cell));
  WriteLn('Локализованная формула - ', MyWorksheet.ReadFormulaAsString(cell, true));
//-------------------------------------------------------------------
// Предыдущий пример приведет к следующему результату
Формула во внутреннем формате - ROUND(A1+B2+1.215,0)
Локализованная формула - ROUND(A1+B2+1,215;0)

Формулы RPN (Обратной польской нотации)

На уровне приложения в основном используются строковые формулы, а формулы RPN имеют мало практического значения. Поэтому документация формул RPN была удалена из этой основной вики FPSpreadsheet и может быть найдена в статье «Формулы RPN в FPSpreadsheet».

Общие формулы и формулы массива

• Общие формулы поддерживаются только для чтения (из файлов Excel).
• Формулы массива в настоящее время не поддерживаются.

Список встроенных формул

FPSpreadsheet поддерживает более 80 встроенных формул. Чтобы не взорвать эту страницу вики, большая часть документации по этим формулам была перенесена в отдельный документ «Список формул».

Чтобы узнать больше о доступных функциях, посмотрите файл testcases_calcrpnformula.inc в папке tests [в корневом каталоге] установки FPSpreadsheet, где каждая функция включена с хотя бы одним примером.

Расширение FPSpreadsheet по пользовательским формулам

Хотя встроенные формулы охватывают большинство приложений, может потребоваться доступ к формуле, доступной в приложении Office, но не в таблице FPSpreadsheet. По этой причине библиотека поддерживает механизм регистрации, который позволяет добавлять пользовательские функции к электронным таблицам. Это можно сделать, вызвав процедуру RegisterFunction из модуля fpsExprParser:

procedure RegisterFunction(const AName: ShortString; const AResultType: Char;
  const AParamTypes: String; const AExcelCode: Integer; ACallBack: TsExprFunctionCallBack); overload;

procedure RegisterFunction(const AName: ShortString; const AResultType: Char;
  const AParamTypes: String; const AExcelCode: Integer; ACallBack: TsExprEventCallBack); overload;

• AName указывает имя, под которым функция будет вызываться в электронной таблице. Он должен соответствовать имени формулы в приложении Office.
• AResultType — это символ, который идентифицирует тип данных результата функции:
  • ‘F’ — число с плавающей запятой
  • ‘I’ — целое число
  • ‘D’ — дата / время
  • ‘B’ — boolean
  • ‘S’ — строка
• AParamTypes — это строка, в которой каждый символ идентифицирует тип данных соответствующего аргумента. В дополнение к приведенному выше списку могут использоваться следующие символы:
  • ‘?’ — любой тип
  • ‘+’ — должен быть последний символ. Это означает, что предыдущий символ повторяется бесконечно. Это позволяет подсчитать произвольный аргумент. Обратите внимание, однако, что Excel поддерживает только до 30 аргументов.
  • нижний регистр ‘f’, ‘i’, ‘d’, ‘b’, ‘s’ указывают необязательные параметры описанного выше типа. Конечно, символы верхнего регистра не могут следовать за строчными символами.
• AExcelCode — это идентификатор функции в файлах xls. См. «Документация OpenOffice формата файлов Microsoft Excel», раздел 3.11, для списка.
• ACallback определяет, какую функцию вызывает FPSpreadsheet для вычисления формулы. Это может быть процедура или обработчик событий.

type
  TsExprFunctionCallBack = procedure (var Result: TsExpressionResult; const Args: TsExprParameterArray);
  TsExprFunctionEvent = procedure (var Result: TsExpressionResult; const Args: TsExprParameterArray) of object;

TsExpressionResult — это вариантная запись, содержащая данные результата или аргумента нескольких типов:

type
  TsResultType = (rtEmpty, rtBoolean, rtInteger, rtFloat, rtDateTime, rtString,
    rtCell, rtCellRange, rtError, rtAny);

  TsExpressionResult = record
    Worksheet       : TsWorksheet;
    ResString       : String;
    case ResultType : TsResultType of
      rtEmpty       : ();
      rtError       : (ResError       : TsErrorValue);
      rtBoolean     : (ResBoolean     : Boolean);
      rtInteger     : (ResInteger     : Int64);
      rtFloat       : (ResFloat       : TsExprFloat);
      rtDateTime    : (ResDateTime    : TDatetime);
      rtCell        : (ResRow, ResCol : Cardinal);
      rtCellRange   : (ResCellRange   : TsCellRange);
      rtString      : ();
  end;

  TsExprParameterArray = array of TsExpressionResult;

В качестве примера мы приводим здесь код для формулы CONCATENATE(), которая объединяет две или более строки:

const
  INT_EXCEL_SHEET_FUNC_CONCATENATE = 336;  
...
  RegisterFunction('CONCATENATE', 'S', 'S+', INT_EXCEL_SHEET_FUNC_CONCATENATE, @fpsCONCATENATE);

procedure fpsCONCATENATE(var Result: TsExpressionResult; const Args: TsExprParameterArray);
// CONCATENATE( text1, text2, ... text_n )
var
  s: String;
  i: Integer;
begin
  s := '';
  for i:=0 to Length(Args)-1 do
  begin
    if Args[i].ResultType = rtError then
    begin
      Result := ErrorResult(Args[i].ResError);
      exit;
    end;
    s := s + ArgToString(Args[i]);
    // "ArgToString" упрощает получение строки из TsExpressionResult, 
    // поскольку строка может содержаться в ResString и в полях ResCell.
    // Такая функция существует для каждого базового типа данных.
  end;
  Result := StringResult(s);
  //"StringResult" хранит строку s в поле ResString объекта 
  // TsExpressionResult и устанавливает для ResultType значение rtString.
  // Такая функция существует для каждого базового типа данных.
end;

В папке examples/other в [корневом каталоге] установки FPSpreadsheet имеется разработанный пример (demo_formula_func.pas). В этой демке добавлены четыре финансовые функции (FV(), PV(), PMT(), RATE()) в FPSpreadsheet.

Неподдерживаемые формулы

Иногда требуется создавать файлы для приложений Office с формулами, не поддерживаемыми [компонентом] FPSpreadsheet. Это возможно в некоторой степени, когда опция boIgnoreFormulas рабочей книги активна. Тогда любая произвольная формула может быть записана в ячейку, а формула не проверяется и не оценивается. [Рабочая] книга может быть записана в файл .ods или .xlsx. Старый формат файла xls не может быть использован, потому что формулу необходимо проанализировать для создания необходимой формулы RPN.

В папке examples/other вы можете найти образец проекта demo_ignore_formula, который создает файл ods со ссылками на другой файл данных. Внешние ссылки обычно не поддерживаются FPSpreadsheet, поэтому должны быть использованы обходные методы [их] игнорирования. Обратите внимание, что этот пример не работает с xlsx, потому что Excel записывает информацию о внешних ссылках для разделения XML-файлов в контейнере xlsx.

Форматирование ячеек

Форматы числа и даты/времени

Значения чисел и даты/времени могут отображаться в различных форматах. В FPSpreadsheet это может быть достигнуто двумя способами:

• использование встроенных форматов чисел путем указания значения для NumberFormat ячейки
• используя пользовательскую строку format.

Форматы чисел могут быть указаны с помощью этих методов [рабочего] листа:

type
  TsWorksheet = class
  public
    // Установка только числовых форматов
    function WriteNumberFormat(ARow, ACol: Cardinal; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''): PCell; overload;
    procedure WriteNumberFormat(ACell: PCell; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''); overload;  

    function WriteNumberFormat(ARow, ACol: Cardinal; ANumFormat: TsNumberFormat;
      ADecimals: Integer; ACurrencySymbol: String = ''; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteNumberFormat(ACell: PCell; ANumFormat: TsNumberFormat;
      ADecimals: Integer; ACurrencySymbol: String = '';
      APosCurrFormat: Integer = -1; ANegCurrFormat: Integer = -1); overload;

    function WriteFractionFormat(ARow, ACol: Cardinal; AMixedFraction: Boolean;
      ANumeratorDigits, ADenominatorDigits: Integer): PCell; overload;
    procedure WriteFractionFormat(ACell: PCell; AMixedFraction: Boolean;
      ANumeratorDigits, ADenominatorDigits: Integer); overload;

    // Установка только формата дата/время  
    function WriteDateTimeFormat(ARow, ACol: Cardinal; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''): PCell; overload;
    procedure WriteDateTimeFormat(ACell: PCell; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''); overload;


    // Установка значений ячеек и числовых форматов за один вызов

    // числовые значения
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      AFormat: TsNumberFormat = nfGeneral; ADecimals: Byte = 2;
      ACurrencySymbol: String = ''): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double; AFormat: TsNumberFormat = nfGeneral;
      ADecimals: Byte = 2; ACurrencySymbol: String = ''); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      AFormat: TsNumberFormat; AFormatString: String): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      AFormat: TsNumberFormat; AFormatString: String); overload;   

    // значения дата/время
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      AFormat: TsNumberFormat = nfShortDateTime; AFormatStr: String = ''): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      AFormat: TsNumberFormat = nfShortDateTime; AFormatStr: String = ''); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      AFormatStr: String): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      AFormatStr: String); overload;  

    // значения денежной валюты
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      AFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = 2;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      AFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = -1;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1); overload;
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      AFormat: TsNumberFormat; AFormatString: String): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      AFormat: TsNumberFormat; AFormatString: String); overload;     
  ...

Встроенные форматы чисел

Встроенные форматы определяются перечислением TsNumberFormat. Несмотря на свое название, элементы охватывают как числа, так и дату/время:

type
  TsNumberFormat = (
    // универсальный для всех номеров
    nfGeneral,
    // числа
    nfFixed, nfFixedTh, nfExp, nfPercentage, nfFraction,
    // денежная валюта
    nfCurrency, nfCurrencyRed, 
    // дата и время
    nfShortDateTime, nfShortDate, nfLongDate, nfShortTime, nfLongTime,
    nfShortTimeAM, nfLongTimeAM, nfDayMonth, nfMonthYear, nfTimeInterval,
    // другие (использующие строку формата)
    nfCustom);

• nfGeneral соответствует форматированию по умолчанию, показывающему как можно больше десятичных знаков [после запятой] (число 3.141592654 не изменится.)
• nfFixed ограничивает десятичные знаки. Число знаков после запятой должно быть указано при вызове WriteNumber. Пример: с 2 десятичными знаками число 3.141592654 становится 3.14.
• nfFixedTh: аналогично nfFixed , но добавляет разделитель тысячных [разрядов], когда число отображается как строка: число 3.141592654 останется таким же, как и в предыдущем примере, потому что оно слишком мало, чтобы показать разделитель тысячных [разрядов]. Но число 314159.2654 станет 314,159.26, для 2 десятичных знаков.
• nfExp выбирает экспоненциальное представление, т.е. разделяет экспоненту. Параметр ADecimals в WriteNumber определяет, сколько десятичных знаков используется. (Число 3.141592654 становится 3.14E+00 в случае двух десятичных знаков).
• nfPercentage отображает число в процентах. Это означает, что значение умножается на 100, а знак процента добавляется. Опять же, укажите в ADecimals, сколько десятичных знаков должно быть показано. (Число 3.141592654 отображается как 314.92%, в случае 2 десятичных знаков).
• nfFraction представляет число в виде доли. Подробности (смешанная фракция?, максимальное количество цифр для числителя или знаменателя) для могут быть указаны в методе рабочего листа WriteFractionFormat.
• nfCurrency отображает номер вместе с символом валюты, и существуют специальные правила, как отображать отрицательные значения (в скобках или знак минус до или после номера). Формат форматирования рабочей книги используется для определения знака валюты и способа отображения номеров (FormatSettings.CurrencyString для символа валюты, FormatSettings.CurrencyFormat для положительных, FormatSettings.NegCurrFormat для отрицательных значений). Эти настройки можно переопределить, указав их непосредственно в вызове WriteCurrency.
• nfCurrendyRed аналогично nfCurrency, кроме того, отрицательные значения отображаются красным цветом.
• nfShortDateTime представляет DateTimeValue ячейки в ‘коротком формате даты/времени», т.е. дни + двухзначный [номер] месяца + двухзначный год + часы + минуты, без секунд. Порядок частей даты берется из FormatSettings рабочей книги. Это относится также к другим форматам даты и времени.
• nfShortDate создает строку даты, показывающую день + двухзначный [номер] месяца + двузначный год
• nfShortTime создает строку времени, показывающую часы + минуты.
• nfLongTime, аналогично [nfShortTime], но включает и секунды
• nfShortTimeAM, аналогично nfShortTime, но использует формат времени AM/PM, т.е. часы идут до 12, а AM или PM добавляются для указания [половины дня] утром или вечером/пополудни.
• nfLongTimeAM, аналогично nfShortTimeAM, но включает секунды
• nfTimeInterval, аналогично nfLongTime, но может быть больше 24 часов. Интервал может также выражаться в минутах или секундах, если используются строки формата [n]:ss или [s], соответственно.
• nfCustom позволяет указать выделенную строку форматирования.

Как уже отмечалось, в рабочей книге есть свойство FormatSettings, которое предоставляет дополнительную информацию для управления окончательным форматированием. Это, по существу, копия DefaultFormatSettings, объявленная в модуле sysutils (элементы LongDateFormat и ShortDateFormat слегка изменены для лучшего соответствия настройки по умолчанию в основных приложениях электронных таблиц). Основная цель FormatSettings — добавить простой способ локализации в числовые форматы.

Строки формата чисел

В дополнение к этим заранее определенным форматам более специализированное форматирование может быть достигнуто с использованием константы формата nfCustom вместе со специальной строкой формата. Строка формата построена в соответствии с синтаксисом Excel, который близок к синтаксису команд FormatFloat и FormatDateTime команды fpc (см. интерактивную справку для этих функций).

Вот основной список используемых символов:

Цвета

FPSpreadsheet поддерживает цвета для текста, фона ячейки и границ ячеек. Основные цвета EGA объявлены в модуле fpstypes как константы:

type
  TsColor = DWORD;

const
  scBlack       = $00000000;
  scWhite       = $00FFFFFF;
  scRed         = $000000FF;
  scGreen       = $0000FF00;
  scBlue        = $00FF0000;
  scYellow      = $0000FFFF;
  scMagenta     = $00FF00FF;
  scCyan        = $00FFFF00;
  scDarkRed     = $00000080;
  scDarkGreen   = $00008000;
  scDarkBlue    = $00800000;
  scOlive       = $00008080;
  scPurple      = $00800080;
  scTeal        = $00808000;
  scSilver      = $00C0C0C0;
  scGray        = $00808080;
  scGrey        = scGray; // переопределить, чтобы разрешить различное правописание

  // Идентификатор неопределенного цвета 
  scNotDefined  = $40000000;

  // Идентификатор прозрачного цвета 
  scTransparent = $20000000;

[Свойство] TsColor представляет значение rgb [значение] цвета, а для красных, зеленых и синих компонентов используется один байт. Результирующее число представлено обратным порядком байт (Little Endian Notation), т. е. сначала в памяти появляется значение красного [цвета]: $00BBGGRR. (Это напрямую совместимо с значениями цвета, как [оно] определено в модуле graphics.)

Старший байт обычно равен нулю, но используется внутри для определения специальных значений цвета, например, для неопределенных или прозрачных цветов.

Модуль fpsutils содержит некоторые полезные функции для модификации цветов:

• function GetColorName(AColor: TsColor): String;
  возвращает имя цветов, определенных выше, или строку, показывающую компоненты rgb для других цветов.
• function HighContrastColor(AColor: TsColor): TsColor;
  возвращает scBlack для «яркого», scWhite для «темного» входного цвета.
• function TintedColor(AColor: TsColor; tint: Double): TsColor;
  осветляет или затемняет цвет, применяя коэффициент tint = -1 .. + 1, где -1 означает «100% затемнение», +1 означает «100% осветление», а 0 означает «без изменений». Цветовой оттенок сохраняется.

Фон ячейки

Фон ячейки может быть заполнен предопределенными шаблонами, которые идентифицируются записью TsFillPattern::

type
  TsFillPattern = record
    Style: TsFillStyle;   // заполняет шаблон стиля, как определено ниже
    FgColor: TsColor;     // цвет переднего плана заливки шаблона
    BgColor: TsColor;     // цвет фона заливки шаблона
  end;

  TsFillStyle = (fsNoFill, fsSolidFill, fsGray75, fsGray50, fsGray25, fsGray12, fsGray6,
    fsStripeHor, fsStripeVert, fsStripeDiagUp, fsStripeDiagDown,
    fsThinStripeHor, fsThinStripeVert, fsThinStripeDiagUp, fsThinStripeDiagDown,
    fsHatchDiag, fsThinHatchDiag, fsThickHatchDiag, fsThinHatchHor);

• Используйте метод WriteBackground рабочего листа, чтобы назначить шаблон заполнения конкретной ячейке. Помимо адреса ячейки, этот метод требует тип заполнения шаблона (TsFillStyle) и цвета переднего плана и фона, значения [которых] указаны [свойством] TsColor.
• Шаблон заполнения конкретной ячейки можно получить, вызвав метод ReadBackground рабочей книги.
• Для достижения однородного цвета фона можно использовать упрощенный метод WriteBackgroundColor.
• Ограничения:
  • Файлы OpenDocument поддерживают только однородные заливки. Цвет фона представляет собой смешивание переднего плана и фона rgb компонентов в соотношении, определяемом шаблоном заполнения.
  • Файлы BIFF2 поддерживают только 12,5% черно-белый затененный шаблон.

type
  TsWorksheet = class
  public
    function WriteBackground(ARow, ACol: Cardinal; AStyle: TsFillStyle; APatternColor, ABackgroundColor: TsColor): PCell; overload;
    procedure WriteBackground(ACell: PCell; AStyle: TsFillStyle; APatternColor, ABackgroundColor: TsColor); overload;

    function WriteBackgroundColor(ARow, ACol: Cardinal; AColor: TsColor): PCell; overload;
    procedure WriteBackgroundColor(ACell: PCell; AColor: TsColor); overload;

    function ReadBackground(ACell: PCell): TsFillPattern;
    function ReadBackgroundColor(ACell: PCell): TsColor; overload;
    // ...
  end;

var
  cell: PCell;
...
  // Пример 1: Присваивает шаблон тонких, горизонтальных, желтых полос на синем фоне, пустой ячейке A1 (строка 0, столбец 0)
  MyWorksheet.WriteBackground(0, 0, fsThinStripeHor, scYellow, scBlue);

  // Пример 2: Равномерный серый цвет фона ячейки B1 (строка 0, столбец 1), содержащий номер 3.14
  cell := MyWorksheet.WriteNumber(0, 1, 3.14);
  MyWorksheet.WriteBackgroundColor(cell, clSilver);

Границы ячеек

Ячейки можно обвести, рисуя границы вдоль их краев или диагональных линий. Существует четыре границы плюс две диагонали, перечисленные в типе данных TsCellBorder:

type
  TsCellBorder = (cbNorth, cbWest, cbEast, cbSouth, dbDiagUp, dbDiagDown);
  TsCellBorders = set of TsCellBorder;

Чтобы показать линию края, добавьте соответствующую границу к ячейке Borders (тип TsCellBorders, см. выше). Таким образом, каждый край ячейки может обрабатываться отдельно. Для этого используйте метод рабочего листа WriteBorders. Этот пример добавляет верхнюю и нижнюю границы к краям A1 и B1:

  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]);  // A1: строка 0, столбец 0
  MyWorksheet.WriteBorders(0, 1, [cbNorth, cbSourth]); // B1: строка 0, столбец 1

Линии обычно рисуются как тонкие, сплошные черные линии. Но можно изменить стиль линии и цвет каждой строки. Для этой цели ячейка предоставляет массив записей TsCellBorderStyle:

type
  TsLineStyle = (lsThin, lsMedium, lsDashed, lsDotted, lsThick, lsDouble, lsHair,
    lsMediumDash, lsDashDot, lsMediumDashDot, lsDashDotDot, lsMediumDashDotDot, lsSlantDashDot); 

  TsCellBorderStyle = record
    LineStyle: TsLineStyle;   
    Color: TsColor;
  end;

  TsCellBorderStyles = array[TsCellBorder] of TsCellBorderStyle;   

  TsWorksheet = class
  public
    function WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; AStyle: TsCellBorderStyle): PCell; overload;
    procedure WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; AStyle: TsCellBorderStyle); overload;

    function WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor): PCell; overload;
    procedure WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor); overload;

    function WriteBorderColor(ARow, ACol: Cardinal; ABorder: TsCellBorder; AColor: TsColor): PCell; overload;
    proceure WriteBorderColor(ACell: PCell; ABorder: TsCellBorder; AColor: TsColor): PCell; overload;

    function WriteBorderLineStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle): PCell; overload;
    procedure WriteBorderLineStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle): PCell; overload;

    function WriteBorderStyles(ARow, ACol: Cardinal; const AStyles: TsCellBorderStyles): PCell; overload;      
    procedure WriteBorderStyles(ACell: PCell; const AStyles: TsCellBorderStyles); overload;

    function WriteBorders(ARow, ACol: Cardinal; ABorders: TsCellBorders): PCell; overload
    procedure WriteBorders(ACell: PCell; ABorders: TsCellBorders); overload

    function ReadCellBorders(ACell: PCell): TsCellBorders;
    function ReadCellBorderStyle(ACell: PCell; ABorder: TsCellBorder): TsCellBorderStyle;
    function ReadCellBorderStyles(ACell: PCell): TsCellBorderStyles;
    ...
  end;

Стиль границы данной ячейки может быть задан следующими способами, представленными в рабочем листе:

• WriteBorderStyle присваивает запись стиля границы ячейки одной границе ячейки. Есть две перегруженные версии этого метода: одна занимает целую запись TsCellBorderStyle, другая — отдельные элементы записи.
• WriteBorderColor изменяет цвет данной границы, не затрагивая стиль линии этой границы.
• WriteBorderLineStyle устанавливает стиль линии только границы, но оставляет цвет неизменным.
• WriteBorderStyles устанавливает стиль границы всех границ данной ячейки сразу. Полезно для копирования стилей границ из одной ячейки в другие ячейки.

Этот пример добавляет тонкую черную границу к вершине [ячейки] и толстую синюю границу по нижней [кромке] ячеек A1 и B1:

var
  cellA1, cellB1: PCell;
...
  cellA1 := MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]);    // ячейка A1: строка 0, столбец 0
  MyWorksheet.WriteBorderStyle(cellA1, cbNorth, lsThin, scBlack);  
  MyWorksheet.WriteBorderStyle(cellA1, cbSouth, lsThick, scBlue);

  cellB1 := MyWorksheet.WriteBorders(0, 1, [cbNorth, cbSouth]);    // ячейка B1: строка 0, столбец 1
  MyWorksheet.WriteBorderStyles(cellB1, cellA1^.BorderStyles);     // копируем все стили границ из ячейки A1 в B1

Шрифты

Текст ячейки может отображаться в разных шрифтах. С этой целью в книге содержится список элементов TsFont:

type
  TsFont = class
    FontName: String;
    Size: Single;   
    Style: TsFontStyles;
    Color: TsColor;
    Position: TsFontPosition;
  end;

• FontName [имя шрифта] соответствует имени шрифта, используемому операционной системой. В Windows примером будет «Times New Roman».
• FontSize [размер шрифта] указывается в «точках», т.е. в единицах 1/72 дюйма, которые обычно используются в приложениях Office.
• FontStyle [стиль шрифта] представляет собой набор элементов [списка со значениями] fssBold, fssItalic, fssStrikeout и fssUnderline [(соответственно жирный, наклонный, зачеркнутый и подчеркнутый)], перечислимого типа TsFontStyle. «Нормальный» шрифт соответствует пустому набору.
• Color [цвет] определяет цвет переднего плана текстовых символов, указанных в представлении rgb, как обсуждалось выше.
• Position [положение] один из двух [параметров свойства] fpNormal — fpSuperscript или fpSubscript указывает, должен ли размер шрифта уменьшаться примерно на 1/3 со смещением символов вверх (верхний [регистр]) или вниз (нижний [регистр]).

Каждая ячейка снабжается индексом в списке шрифтов.

Чтобы назначить конкретный шрифт ячейке, используйте один из следующих методов TsSpreadsheet:

type
  TsSpreadsheet = class
  public
    function  WriteFont(ARow, ACol: Cardinal; const AFontName: String;
      AFontSize: Single; AFontStyle: TsFontStyles; AFontColor: TsColor): Integer; overload;
    procedure WriteFont(ARow, ACol: Cardinal; AFontIndex: Integer); overload;
    function WriteFontColor(ARow, ACol: Cardinal; AFontColor: TsColor): Integer;
    function WriteFontSize(ARow, ACol: Cardinal; ASize: Integer): Integer;
    function WriteFontStyle(ARow, ACol: Cardinal; AStyle: TsFontStyles): Integer; 
    // плюс: перегруженные версии, принимающие указатель на ячейку записи, а не индекс строки и столбца в качестве параметра
    // ...
  end;

• WriteFont назначает шрифт ячейке. Если шрифт еще не существует в списке шрифтов, создается новая запись. Функция возвращает индекс шрифта в списке шрифтов. Кроме того, есть перегруженная версия, которая учитывает только индекс шрифта в качестве параметра.
• WriteFontColor заменяет цвет шрифта, который в настоящее время назначается ячейке новым [цветом]. Опять же, новый элемент списка шрифтов создается, если шрифт с новым цветом еще не существует. Функция возвращает индекс шрифта в списке.
• WriteFontSize заменяет размер используемого в настоящее время шрифта ячейки.
• WriteFontStyle заменяет стиль (обычный, полужирный, курсив и т. д.) используемого в настоящее время шрифта ячейки.

Список шрифтов рабочей книги содержит по крайней мере один элемент, который является шрифтом по умолчанию для ячеек с немодифицированными шрифтами. По умолчанию это [шрифт] «Arial» [размером] 10pt. Используйте метод SetDefaultFont рабочей книги, чтобы назначить другой шрифт первому элементу списка.

Шрифт в указанном индексе списка шрифтов можно просмотреть, вызвав функцию рабочей книги GetFont. Количество доступных шрифтов возвращается [свойством] GetFontCount.

Вот пример, который уменьшает размер всех 10pt-овых шрифтов Arial до 9pt:

var
  i: Integer;
  font: TsFont;
begin
  for i := 0 to MyWorkbook.GetFontCount-1 do
  begin
    font := MyWorkbook.GetFont(i);
    if (font.FontName = 'Arial') and (font.Size = 10.0) then
      font.Size := 9.0;
  end;
end;

Форматирование Rich-text

В дополнение к использованию конкретного шрифта для каждой ячейки также можно указать конкретные атрибуты шрифта для отдельных символов или групп символов в каждом тексте ячейки. Следуя нотации Excel, мы называем эту функцию «форматированием Rich-text» (хотя это не имеет ничего общего с форматом файла *.rtf).

С этой целью модуль fpstypes объявляет тип TsRichTextParams, который представляет собой массив записей TsRichTextParam:

type
  TsRichTextParam = record
    FontIndex: Integer;
    FirstIndex: Integer;
  end;

  TsRichTextParams = array of TsRichTextParam;

FontIndex ссылается на индекс шрифта в FontList рабочей книги, который будет использоваться для форматирования символов, начинающихся с индекса FirstIndex. Нумерация индекса строковых символов FirstIndex начинается с 1.

Существует два способа добавления форматирования «rich-text» в ячейке:

• Вставка соответствующих HTML-кодов в текст ячейки. Это можно сделать, используя метод WriteTextAsHTML рабочего листа. Чтобы добавить в ячейку A1 текст «Area (m²)», передайте следующую HTML-кодированную строку для этой функции

  MyWorksheet.WriteTextAsHTML(0, 0, 'Area (m<sup>2</sup>');

• Альтернативно, стандартный метод текстовой записи WriteText может быть вызван с дополнительным параметром, определяющим параметры форматирования rich-text, которые будут использоваться напрямую:

var
  richTextParams: TsRichTextParams;
  fnt: TsFont;
begin
  SetLength(rtp, 2);
  fnt := MyWorksheet.ReadCellFont(0, 0);
  richTextParams[0].FirstIndex := 8; // Группа верхнего индекса начинается с «2», который является символом #8 текста ячейки.
  richTextParams[0].FontIndex := MyWorkbook.AddFont(fnt.FontName, fnt.Size, fnt.Style, fnt.Color, fpSuperscript);
  richTextParams[1].FirstIndex := 9; // Обычный шрифт снова начинается с символа # 9.
  richTextParams[1].FontIndex := MyWorksheet.ReadCellFontIndex(0, 0);
  MyWorksheet.WriteUTF8Text(0, 0, 'Area (m2)', richTextParams);
end;

Используйте метод рабочего листа DeleteRichTextParams, чтобы удалить форматирование rich-text из ранее отформатированной ячейки.

Вращение текста

Обычно текст отображается в ячейках по горизонтали. Тем не менее, можно также поворачивать его на 90 градусов по часовой стрелке или против часовой стрелки. Кроме того, существует возможность установки горизонтальных символов вертикально друг над другом.

Если вам нужна эта функция, используйте метод рабочего листа WriteTextRotation и укажите направление текста элементом [свойства] перечислимого типа TsTextRotation:

type
  TsTextRotation = (trHorizontal, rt90DegreeClockwiseRotation,
    rt90DegreeCounterClockwiseRotation, rtStacked);

  TsWorksheet = class
  public
    function WriteTextRotation(ARow, ACol: Cardinal; ARotation: TsTextRotation): PCell; overload;
    procedure WriteTextRotation(ACell: PCell; ARotation: TsTextRotation); overload;

    function ReadTextRotation(ACell: PCell): TsTextRotation;
    // ...
  end;

  // пример для повернутого против часовой стрелки текста в ячейке A1:
  WriteTextRotation(0, 0, rt90DegreeCounterClockwizeRotation);

Выравнивание текста

По умолчанию текст ячейки выровнен по левому и нижнему краям ячейки, за исключением чисел, выровненных по правому краю. Это поведение можно изменить, используя методы рабочего листа WriteHorAlignment и WriteVertAlignment:

type
  TsHorAlignment = (haDefault, haLeft, haCenter, haRight);
  TsVertAlignment = (vaDefault, vaTop, vaCenter, vaBottom);    

  TsWorkbook = class
  public
    function WriteHorAlignment(ARow, ACol: Cardinal; AValue: TsHorAlignment): PCell; overload;
    procedure WriteHorAlignment(ACell: PCell; AValue: TsHorAlignment); overload;
    function ReadHorAlignment(ACell: PCell): TsHorAlignment;

    function WriteVertAlignment(ARow, ACol: Cardinal; AValue: TsVertAlignment): PCell; overload; 
    procedure WriteVertAlignment(ACell: PCell; AValue: TsVertAlignment); overload;
    function ReadVertAlignment(ACell: PCell): TsVertAlignment;
    // ...
  end;

  // Пример: [так] центрируется текст в ячейке А1 как по горизонтали, так и по вертикали
  MyWorkbook.WriteHorAlignment(0, 0, haCenter);
  MyWorkbook.WriteVertAlignment(0, 0, vaCenter);

Перенос слов

Текст, длина которого превышает ширину ячейки, может быть перенесен на несколько строк вызовом метода WriteWordwrap электронной таблицы:

type
  TsWorksheet = class
  public
    function WriteWordwrap(ARow, ACol: Cardinal; AValue: Boolean): PCell; overload;
    procedure WriteWordwrap(ACell: PCell; AValue: Boolean); overload;
    function ReadWordwrap(ACell: PCell): Boolean;
    //...
  end;

  // Пример: активация переноса слов в ячейке А1
  MyWorksheet.WriteWordwrap(0, 0, true);

Объединенные ячейки

Подобно приложениям Office, FPSpreadsheet поддерживает также возможность слияния ячеек в одну большую ячейку, которая часто используется как общий заголовок выше аналогичных столбцов. Просто вызовите MergeCells и передайте параметр, чтобы указать диапазон ячеек, которые нужно объединить, либо строку диапазона Excel (например, A1:D5), либо первую и последнюю строку и столбец:

  MyWorksheet.MergeCells('A1:D5');
  // или: MyWorksheet.MergeCells(0, 0, 4, 3);  // первая строка, первый столбец, последняя строка, последний столбец

Содержимое и формат, отображаемые для объединенного диапазона, берутся из верхнего левого угла диапазона ячейки A1 в приведенном выше примере. Эта ячейка вызывается [свойством] MergeBase в библиотеке. За исключением этой угловой ячейки, [там] не должно быть никаких других ячеек в диапазоне. Если [они там окажутся], их содержимое и формат будут скрыты.

Чтобы разбить объединенный диапазон на отдельные ячейки, используйте команду Unmerge и передайте любую ячейку, находящуюся в объединенном диапазоне:

  MyWorksheet.UnmergeCells('B1');
  // или: MyWorksheet.UnmergeCells(0, 1);   // строка, столбец любой ячейки в пределах диапазона

Объединенные ячейки могут быть прочитаны/записаны во все форматы файлов, за исключением sfCSV, sfExcel2 и sfExcel5, которые не поддерживают эту функцию изначально.

Информация, с которой объединены ячейки, хранится во внутреннем списке. В отличие от предыдущих версий, больше невозможно получить доступ к MergeBase из ячейки напрямую. Используйте следующие функции для извлечения информации об объединенных ячейках:

var
  cell, base: PCell;
  r1,c1,r2,c2: Cardinal;
...
  cell := MyWorksheet.FindCell('B1');
  if MyWorksheet.IsMerged(cell) then
  begin
    WriteLn('Ячейка B1 объединена.');

    MyWorksheet.FindMergedRange(cell, r1, c1, r2, c2);
    WriteLn('Объединенный диапазон - ' + GetCellRangeString(r1, c1, r2, c2));

    base := MyWorksheet.FindMergeBase(cell);
    WriteLn('Основная ячейка для слияния - ' + GetCellString(base^.Row, base^.Col));
  end;

Защита ячейки

Это описано в отдельном разделе ниже.

Дополнительная информация

Комментарии к ячейке

Комментарии могут быть прикреплены к любой ячейке путем вызова

  MyWorksheet.WriteComment(0, 0, 'Это комментарий для ячейки A1');

Они хранятся во внутреннем списке рабочего листа. Используйте соответствующие методы рабочего листа для доступа к комментариям:

• Если вы хотите узнать, содержит ли конкретная ячейка комментарий, вызовите метод рабочего листа HasComment(cell).
• Для получения комментария ячейки используйте метод ReadComment(cell) или его перегруженный вариант ReadComment(ARow, ACol).
• Общее количество комментариев может быть получено из worksheet.Comments.Count.

Гиперссылки

Гиперссылки могут быть прикреплены к ячейкам, чтобы связать ячейки с другими документами или другими ячейками в одной книге. Общий синтаксис для создания гиперссылок

  procedure TWorksheet.WriteHyperlink(ARow, ACol: Cardinal; ATarget: String; ATooltip: String = '');

• Целью гиперссылки, переданной как параметр ATarget, должна быть полностью квалифицированной (Унифицированный идентификатор ресурса), состоящей из [определенных] фраз протокола [в определенной последовательности](например, http://, file:///, mailto: и т. д.), за которой следует определенная информация, такая как веб-адрес, имя файла или e-mail адрес и необязательный идентификатор закладки, разделенный символом ‘#’.
• Необязательный параметр Tooltip [(подсказка)] расценивается Excel для отображения его в окне подсказки, если мышь находится над гиперссылкой.

Примеры:

  // Открытие веб-сайта www.google.com
  MyWorksheet.WriteText(0, 0, 'Открыть google');
  MyWorksheet.WriteHyperlink(0, 0, 'http://www.google.com');

  // Открытие локального файла с абсолютным путем "C:readme.txt" (предполагается, [что это] Windows)
  MyWorksheet.WriteHyperlink(1, 0, 'file:///c:readme.txt');

  // Открытие почтового клиента для отправки почты
  MyWorksheet.WriteText('Отправить письмо');
  MyWorksheet.WriteHyperlink(3, 0, 'mailto:somebody@gmail.com?subject=Test');

  // Переход к определенной ячейке 
  MyWorksheet.WriteText(5, 0, 'Переход к ячейке A10 на листе2');
  MyWorksheet.WriteHyperlink(5, 0, '#Sheet2!A10');

  // Переход в ячейку A10 на текущем листе и отображение всплывающей подсказки
  MyWorksheet.WriteHyperlink(5, 0, '#A10', 'Переход к ячейке A10');

Изображения

FPSpreadsheet поддерживает встраивание изображений в рабочие листы. Используйте один из методов рабочего листа WriteImage(), чтобы добавить изображение на рабочий лист:

  MyWorksheet.WriteImage(row, col, filename, offsetX, offsetY, scaleX, scaleY);
  MyWorksheet.WriteImage(row, col, stream, offsetX, offsetY, scaleX, scaleY);
  MyWorksheet.WriteImage(row, col, imageindex, offsetX, offsetY, scaleX, scaleY);

Верхний/левый угол изображения помещается в верхний/левый угол ячейки в указанной строке и столбце. Параметры плавающей запятой offsetX, offsetY, scaleX и scaleY являются необязательными: они определяют смещение точки привязки этого изображения от угла ячейки и коэффициент увеличения. Путь к файлу изображения указывается как параметр filename. В качестве альтернативы можно использовать перегруженные версии, которые принимают поток [данных] вместо имени файла или индекса изображения в списке EmbeddedObj рабочей книги — используйте MyWorkbook.FindEmbeddedObj(имя файла), чтобы получить этот индекс для ранее загруженного изображения файл.

Обратите внимание, что FPSpreadsheet должен знать тип изображения для успешного импорта картинок. В настоящее время поддерживаются типы png, jpg, tiff, bmp, gif, svg, wmf, emf и pcx (Excel2007 не может читать импортированные изображения svg and pcx). Другие форматы могут быть зарегистрированы путем записи функции, которая определяет размер изображения и плотность пикселей, а также путем регистрации нового формата с помощью процедуры RegisterImageType — см. модуль fpsImages для [получения] примеров:

type
  TsImageType = integer;
  TGetImageSizeFunc = function (AStream: TStream; out AWidth, AHeight: DWord; out dpiX, dpiY: Double): Boolean;

function RegisterImageType(AMimeType, AExtension: String; AGetImageSize: TGetImageSizeFunc): TsImageType;

Из-за различий в расчете высоты строки и ширины столбцов между приложениями FPSpreadsheet и Office невозможно правильно позиционировать изображения. Если точное положение изображения важно, вы должны соблюдать следующие правила:

• Предопределите ширину всех столбцов, по крайней мере, до той, которая содержит правый край изображения.
• Предопределите высоты всех строк, по крайней мере, до той, которая содержит нижний край изображения.
• Если рабочая книга должна быть сохранена в формате OpenDocument, добавьте изображение после изменения ширины столбцов и высоты строк, поскольку ods привязывает изображение к листу, а не к ячейке (как Excel и FPSpreadsheet).
• Если точный размер изображения важен, убедитесь, что он помещается в одну ячейку.

Сортировка

Ячейки на рабочем листе можно сортировать по множеству критериев, вызывая метод Sort рабочего листа. Этот метод принимает запись TsSortParams, и края прямоугольника ячейки сортируются как параметры; в перегруженной версии прямоугольник ячейки также может быть задан с помощью строки диапазона типа Excel (например, ‘A1:G10’):

type
  TsWorksheet = class
    // ...
    procedure Sort(const ASortParams: TsSortParams;
      ARowFrom, AColFrom, ARowTo, AColTo: Cardinal); overload;
    procedure Sort(ASortParams: TsSortParams; ARange: String); overload;
    // ...
  end;

Критерии сортировки определяются записью типа TsSortParams:

type
  TsSortParams = record
    SortByCols: Boolean;
    Priority: TsSortPriority;  // spNumAlpha ("Сначала числа") или spAlphaNum ("Сначала текст")
    Keys: TsSortKeys;
  end;    

  TsSortKey = record
    ColRowIndex: Integer;
    Options: TsSortOptions;    // set of [spDescending, spCaseInsensitive]
  end;

• Логическое значение SortByCols определяет, что сортировка выполняется вдоль столбцов (true) или строк (false). Соответственно, ColRowIndex, указанный в ключах сортировки, соответствует индексу столбца или строки (см. ниже).
• [Свойство] Priority определяет в диапазонах ячеек смешанного содержимого, будет ли возрастающий тип ставить числовые значения перед текстовыми значениями или нет. Пустые ячейки всегда перемещаются в конец отсортированного столбца или строки. В Excel приоритетом является [флаг] «сначала числа» (spNumAlpha).
• Массив Keys указывает несколько параметров сортировки. Они состоят из индекса отсортированного столбца или строки (ColRowIndex) и набора [свойств] Options для [указания] направления сортировки (spoDescending) и РЕГИСТРОзависимости (spCaseInsensitive). Если [набор свойств] Options пуст, сравнение ячеек чувствительно к регистру, а ячейки упорядочены в порядке возрастания. Если две ячейки считаются «равными» на основе первого ключа (sortParams.Keys[0]), сравнение выполняется со следующими условиями в массиве Keys до тех пор, пока [не будет] обнаружена разница [между ячейками] или все условия [не будут] исчерпаны.

InitSortParams — это удобная утилита для инициализации параметров сортировки:

function InitSortParams(ASortByCols: Boolean = true; ANumSortKeys: Integer = 1;
  ASortPriority: TsSortPriority = spNumAlpha): TsSortParams;

Следующий фрагмент кода показывает типичный вызов сортировки:

var
  sortParams: TsSortParams;
begin
  sortParams := InitSortParams(true, 2);  // сортировка по столбцам, 2 сортировочных ключа

  // первичный ключ сортировки: столбец 3, восходящая [сортировка], нечувствительный к регистру
  sortParams.Keys[0].ColRowIndex := 3;
  sortParams.Keys[0].Options := [ssoCaseInsensitive];

  // вторичный ключ сортировки: столбец 1, нисходящая [сортировка]
  sortParams.Keys[1].ColRowIndex := 1;
  sortParams.Keys[1].Options := [ssoDescending];

  // Блок сортировки распространяется между ячейкой A1 (строка=0, столбец=0) и F10 (строка=9, столбец=5)
  MyWorksheet.Sort(sortParams, 0, 0, 9, 5);
  // или: MyWorksheet.Sort(sortParams, 'A1:F10');
end;

Поиск и замена

Модуль fpsSearch реализует поисковую систему, которая может использоваться для поиска определенного содержимого ячейки в рабочей книге или для замены найденного содержимого ячейки какой-либо другой строкой.

Например:

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyRow, MyCol: Cardinal;
  MySearchParams: TsSearchParams;
begin
  MyWorkbook := TsWorkbook.Create;
  try
    MyWorkbook.ReadFromFile(AFileName);

    // Specify search criteria
    MySearchParams.SearchText := 'Привет';
    MySearchParams.Options := [soEntireDocument];
    MySearchParams.Within := swWorkbook;

    // или: MySearchParaams := InitSearchParams('Привет', [soEntireDocument], swWorkbook);

    // Создать поисковую систему и выполнить поиск
    with TSearchEngine.Create(MyWorkbook) do begin
      if FindFirst(MySearchParams, MyWorksheet, MyRow, MyCol) then begin
        WriteLn('Первый [искомый текст] "', MySearchparams.SearchText, '" найден в ячейке ', GetCellString(MyRow, MyCol));
        while FindNext(MySeachParams, MyWorksheet, myRow, MyCol) do
          WriteLn('Следующий [искомый текст] "', MySearchParams.SearchText, '" найден в ячейке ', GetCellString(MyRow, MyCol));
      end;
      Free;
    end;
  finally
    MyWorkbook.Free;
  end;
end;

Поисковая система предоставляет два метода для поиска: FindFirst иFindNext. Они очень похожи, но различаются только местом, где начинается поиск. В случае FindFirst начальная ячейка определяется [набором опций] из списка Options, описанных ниже. В случае FindNext поиск начинается в ячейке, следующей за предыдущей найденной ячейкой. Оба метода возвращают рабочий лист, [а также] индексы строк и столбцов ячейки, в которой найден искомый текст. Если поиск безуспешен, результат функции FALSE.

Запись TsSearchParams указывает критерии, используемые для поиска:

type
  TsSearchParams = record
    SearchText: String;
    Options: TsSearchOptions;
    Within: TsSearchWithin;
  end;

Помимо текста для поиска (SearchText), она предоставляет набор опций для сужения поиска:

• soCompareEntireCell: сравнивает SearchText со всем содержимым ячейки. Если [эта опция] не содержится в Options, текст ячейки сравнивается только частично.
• soMatchCase: [позволяет] выполнить поиск с учетом регистр
• soRegularExpr: [здесь] SearchText рассматривается как регулярное выражение
• soAlongRows: Поисковая система осуществляет поиск сначала вдоль строк. Если [эта опция] не содержится в Options, поиск продолжается по столбцам.
• soBackward: Поиск начинается с конца документа или выполняется назад из активной ячейки [(к началу документа)]. Если [эта опция] не содержится в Options, поиск начинается с начала документа или выполняется вперед из активной ячейки [(к концу документа)].
• soWrapDocument: Если поиск достиг конца документа, поиск возобновляется с самого начала (или наоборот, если используется soBackward).
• soEntireDocument: Поиск начинается с первой ячейки (или последней ячейки, если используется soBackward). Если [эта опция] не содержится в Options, поиск начинается с активной ячейки рабочего листа. [При этом] игнорируется [опция] FindNext.

Поле записи Within идентифицирует часть электронной таблицы для поиска:

• swWorkbook: Идет поиск по всей рабочей книге. Если поисковая фраза не найдена на первом листе (или последнем листе, если используется soBackward), поиск продолжается со следующего (предыдущего) листа.
• swWorksheet: Поиск ограничен текущим активным рабочим листом
• swColumn: Поиск ограничен столбцом активной ячейки
• swRow: Поиск ограничен строкой активной ячейки

Запись параметров поиска может быть инициализирована вызовом InitSearchParams (в модуле fpsutils) с элементами записи в качестве необязательных параметров.

В дополнение к поиску поисковая система также может использоваться для замены найденного текста другой строкой. Для этого вызовите функции ReplaceFirst или ReplaceNext. Они действуют как аналог [функции] FindXXXX, поэтому для определения критериев поиска требуется запись TsSearchParams. Но в дополнение к поиску эти функции также выполняют замену текста в соответствии со спецификацией в записи TsReplaceParams:

type
  TsReplaceParams = record
    ReplaceText: String;
    Options: TsReplaceOptions;
  end;

ReplaceText идентифицирует строку, которая заменит найденный шаблон текста. Параметры Options определяют набор критериев, по которым выполняется замена:

• roReplaceEntirecell: Заменяет весь текст ячейки текстом ReplaceText. Если [эта опция] не содержится в Options, тогда заменяется только часть, соответствующая SearchText.
• roReplaceAll: Выполняет замену во всех найденных ячейках (т.е. просто вызывает ReplaceFirst, чтобы автоматически заменить все).
• roConfirm: Вызывает обработчик для события OnConfirmReplacement, в котором пользователь должен указать, должна ли выполняться замена или нет. Обратите внимание, что этот обработчик событий является обязательным, если установлен roConfirm.

Используйте функцию InitReplaceParams (в модуле fpsutils) для инициализации записи параметров замены с предопределенными (но необязательными) значениями.

Операции со столбцами и строками

Рабочий лист предоставляет эти методы для вставки, удаления, скрытия или отображения столбцов и строк:

type
  TsWorksheet = class
  ...
    procedure DeleteCol(ACol: Cardinal);
    procedure DeleteRow(ARow: Cardinal);

    procedure InsertCol(ACol: Cardinal);
    procedure InsertRow(ARow: Cardinal);

    procedure RemoveCol(ACol: Cardinal);
    procedure RemoveRow(ARow: Cardinal);

    procedure RemoveAllCols;
    procedure RemoveAllRows

    procedure HideCol(ACol: Cardinal);
    procedure HideRow(ARow: Cardinal);
    
    procedure ShowCol(ACol: Cardinal);
    procedure ShowRow(ARow: Cardinal);

    function ColHidden(ACol: Cardinal): Boolean;
    function RowHidden(ARow: Cardinal): Boolean;

• Когда столбец или строка удалены [методом] DeleteCol или DeleteRow, любые данные, назначенные этому столбцу или строке, т.е. ячейки, комментарии, гиперссылки, записи TCol или TRow, удаляются. Данные справа или ниже удаленной колонки/строки перемещаются [соответственно] влево или вверх.

• RemoveCol и RemoveRow по соглашению удаляют только запись столбца или строки, т.е. сбрасывают ширину столбца и высоту строки до значений по умолчанию. Данные ячейки, комментариев и гиперссылок не затрагиваются.

• RemoveAllCols удаляет все записи столбцов, т.е. сбрасывает ширину всех столбцов; RemoveAllRows делает то же самое с записями строки и высотой строк.

• Столбец или строка вставляются перед индексом, указанным в качестве параметра метода InsertXXX.

Макет страницы

Общие сведения

Пока что FPSpreadsheet не поддерживает печать рабочих листов, но приложения Office делают [это], и они предоставляют секцию информации в своих файлах для этой цели. В FPSpreadsheets эта информация доступна в классе TsPageLayout, который принадлежит структуре данных TsWorksheet. Его свойства и методы сочетают в себе самые важные функции из мира Excel и OpenDocument.

type 
  TsPageOrientation = (spoPortrait, spoLandscape);

  TsPrintOption = (poPrintGridLines, poPrintHeaders, poPrintPagesByRows,
    poMonochrome, poDraftQuality, poPrintCellComments, poDefaultOrientation,
    poUseStartPageNumber, poCommentsAtEnd, poHorCentered, poVertCentered,
    poDifferentOddEven, poDifferentFirst, poFitPages);

  TsPrintOptions = set of TsPrintOption;  

  TsHeaderFooterSectionIndex = (hfsLeft, hfsCenter, hfsRight);

  TsCellRange = record
    Row1, Col1, Row2, Col2: Cardinal;
  end;

  TsPageLayout = class
  ...
  public
    ...
    { Methods }
    // встроенные изображения заголовка/нижнего колонтитула
    procedure AddHeaderImage(AHeaderIndex: Integer;
      ASection: TsHeaderFooterSectionIndex; const AFilename: String);
    procedure AddFooterImage(AFooterIndex: Integer;
      ASection: TsHeaderFooterSectionIndex; const AFilename: String);
    procedure GetImageSections(out AHeaderTags, AFooterTags: String);
    function HasHeaderFooterImages: Boolean;

    // Повторитель строк и столбцов 
    function HasRepeatedCols: Boolean;
    function HasRepeatedRows: Boolean;
    procedure SetRepeatedCols(AFirstCol, ALastCol: Cardinal);
    procedure SetRepeatedRows(AFirstRow, ALastRow: Cardinal);

    // диапазоны печати 
    function AddPrintRange(ARow1, ACol1, ARow2, ACol2: Cardinal): Integer; overload;
    function AddPrintRange(const ARange: TsCellRange): Integer; overload;
    function GetPrintRange(AIndex: Integer): TsCellRange;
    function NumPrintRanges: Integer;
    procedure RemovePrintRange(AIndex: Integer);

    { Properties }
    property Orientation: TsPageOrientation read FOrientation write FOrientation;
    property PageWidth: Double read FPageWidth write FPageWidth;
    property PageHeight: Double read FPageHeight write FPageHeight;
    property LeftMargin: Double read FLeftMargin write FLeftMargin;
    property RightMargin: Double read FRightMargin write FRightMargin;
    property TopMargin: Double read FTopMargin write FTopMargin;
    property BottomMargin: Double read FBottomMargin write FBottomMargin;
    property HeaderMargin: Double read FHeaderMargin write FHeaderMargin;
    property FooterMargin: Double read FFooterMargin write FFooterMargin;
    property StartPageNumber: Integer read FStartPageNumber write SetStartPageNumber;
    property ScalingFactor: Integer read FScalingFactor write SetScalingFactor;
    property FitHeightToPages: Integer read FFitHeightToPages write SetFitHeightToPages;
    property FitWidthToPages: Integer read FFitWidthToPages write SetFitWidthToPages;
    property Copies: Integer read FCopies write FCopies;
    property Options: TsPrintOptions read FOptions write FOptions;
    property Headers[AIndex: Integer]: String read GetHeaders write SetHeaders;
    property Footers[AIndex: Integer]: String read GetFooters write SetFooters;
    property RepeatedCols: TsRowColRange read FRepeatedCols;
    property RepeatedRows: TsRowColRange read FRepeatedRows;
    property PrintRange[AIndex: Integer]: TsCellRange read GetPrintRange;
    property FooterImages[ASection: TsHeaderFooterSectionIndex]: TsHeaderFooterImage read GetFooterImages;
    property HeaderImages[ASection: TsHeaderFooterSectionIndex]: TsHeaderFooterImage read GetHeaderImages;
  end;

  TsWorksheet = class
  ...
  public
    property PageLayout: TsPageLayout;
    ...
  end;

• Orientation [(ориентация)] определяет ориентацию печатной бумаги, как портретной, так и альбомной.

• Page width [(ширина страницы)] и page height [(высота страницы)] ссылаются на стандартную ориентацию бумаги, обычно портретную.

• Left, top, right and bottom margins не требуют пояснений и приведены в миллиметрах.

• HeaderMargin [(отступ заголовка)] понимается — как и в Excel — как расстояние между верхним краем бумаги и верхней частью заголовка, и TopMargin [(отступ сверху)] — соответственно, как расстояние между верхним краем бумаги и верхней частью первой строки таблицы, т.е. если заголовок содержит несколько разрывов строк, он может располагаться в части таблицы вне печати. Это отличается от файлов OpenDocument, где заголовок может соответственно расти [по высоте].

• StartPageNumber [(номер начальной страницы)] должен быть изменен, если печать [документа] не должна начинаться со страницы 1. Для этого параметра [вручную] необходимо добавить опцию poUseStartPageNumber в Options макета страницы, но обычно это делается автоматически.

• ScalingFactor [(коэффициент масштабирования)] указывается в процентах и может использоваться для уменьшения количества печатаемых страниц. Изменение этого свойства очищает опцию poFitToPages [свойства] Options макета страницы.

• В качестве альтернативы ScalingFactor вы также можете использовать FitHeightToPages ([подгонять высоту до страниц]) или FitWidthToPages ([подгонять ширину до страниц]). Опция poFitToPages должна быть активной, чтобы переопределить параметр ScalingFactor. FitHeightToPages указывает целое количество страниц, на которых должна уместиться вся высота рабочего листа. Соответственно, FitWidthToPages может использоваться для определения целого количества страниц, которым должна соответствовать вся ширина рабочего листа. Значение 0 определяет специальное понятие «использовать столько страниц, сколько необходимо». Таким образом, этот вариант может быть установлен для параметра Excel «Устанавливать все столбцы на одной странице», например:

  MyWorksheet.PageLayout.Options := MyWorksheet.PageLayout.Options + [poFitPages];
  MyWorksheet.PageLayout.FitWidthToPages := 1;     // все столбцы на ширине одной страницы
  MyWorksheet.PageLayout.FitHeightToPages := 0;    // использовать как можно больше страниц

• Header rows and columns repeated on every printed page [(заголовки строк и столбцов повторяются на каждой печатной странице)] может быть определена [свойствами] RepeatedCols и RepeatedRows записей; для повтора [на каждой странице] их элементы FirstIndex и LastIndex ссылаются на индексы первого и последнего столбца или строки, соответственно. Для определения этих чисел используйте методы SetRepeatedCols и SetRepeatedRows. Обратите внимание, что второй параметр для последнего индекса может быть опущен при использовании только одной строки или столбца заголовка.

• Print ranges [(диапазон печати)] или print areas [(область печати)] (пользуясь терминологией Excel) может использоваться для ограничения печати только в диапазоне ячеек. Используйте методы AddPrintRange для определения диапазона ячеек для печати: укажите индексы левого столбца, верхней строки, правого столбца и нижней строки диапазона для печати. Рабочий лист может содержать несколько диапазонов печати.

• Copies [(копии)] определяет, как часто печатается рабочий лист.

• Options [(опции)] определяет дополнительные свойства печати, их имена являются самообучающимися. Они были определены в соответствии с [спецификацией] файлов Excel, некоторые из них не существуют в файлах ODS и там игнорируются.

Заголовки и колонтитулы

Текст заголовков и колонтитулов может состоять из выровненных по левому краю, центрированных и выровненных по правому краю строк. Добавьте символ &L, чтобы указать, что следующая строка должна быть напечатана с выравниванием слева; используйте &C соответственно для центрируемых [строк] и &R для [строк] с выравниванием по правому краю. Существуют другие символы, которые во время печати будут дополнять [действие символов]:

• &L: начинает описание раздела с выравниванием по левому краю текста заголовка или нижнего колонтитула
• &C: начинает описание раздела с выравниванием по центру текста заголовка или нижнего колонтитула
• &R: начинает описание раздела с выравниванием по правому краю текста заголовка или нижнего колонтитула
• &P: номер страницы
• &N: количество страниц
• &D: текущая дата печати
• &T: текущее время печати
• &A: имя рабочего листа
• &F: имя файла без пути [к файлу]
• &P: путь к файлу без имени файла
• &G: встроенное изображение — используйте методы AddHeaderImage или AddFooterImage, чтобы указать файл изображения; это также добавляет [символ] &G к другим кодам текущего раздела header/footer. Обратите внимание, что не все типы изображений, известные в приложении Office, могут быть приняты. В настоящее время изображение может быть [с расширением] jpeg, png, gif, bmp, tiff, pcx, svg, wmf или emf.
• &B: жирный вкл/выкл
• &I: курсив вкл/выкл
• &U: подчеркивание вкл/выкл
• &E: двойное подчеркивание вкл/выкл
• &S: зачеркнутый вкл/выкл
• &H: тень вкл/выкл
• &O: контур вкл/выкл
• &X: верхний индекс вкл/выкл
• &Y: нижний индекс вкл/выкл
• &»font»: начинает использовать шрифт с определенным именем, напр., &»Arial»
• &number: начинает использовать определенный размер шрифта (в точках), напр., &16
• &Krrggbb: переключает цвет шрифта в определенное двоичное значение указанного цвета, напр., используйте &KFF0000 для [переключения] в красный.

Массивы Headers[]/Footers[] предоставляют пространство для использования трех разных верхних и нижних колонтитулов:

• Headers[0] относится к заголовку, используемому только на первой странице, [также] аналогично для Footers[0]. Вместо индекса 0 вы можете использовать константу HEADER_FOOTER_INDEX_FIRST. Оставьте эту строку пустой, если на первой странице нет специального заголовка/нижнего колонтитула.
• Headers[1] относится к заголовку на страницах с нечетными номерами страниц, [также] аналогично для Footers[1]. Вместо индекса 1 вы можете использовать константу HEADER_FOOTER_INDEX_ODD .
• Headers[2] относится к заголовку на страницах с четными номерами страниц, [также] аналогично для Footers[2]. Вместо индекса 2 вы можете использовать константу HEADER_FOOTER_INDEX_EVEN.

Оставьте строки с индексом 0 и 2 пустыми, если в распечатке всегда должен быть один и тот же верхний/нижний колонтитул. Для большей ясности вы можете использовать константу HEADER_FOOTER_INDEX_ALL. Например:

  MyWorksheet.PageLayout.Headers[HEADER_FOOTER_INDEX_ALL] := '&C&D &T';           // выровненный по центру заголовок "дата время" на всех страницах 
  MyWorksheet.PageLayout.Footers[HEADER_FOOTER_INDEX_ODD] := '&RPage &P of &N';   // выровненный  по правому краю нижний колонтитул на нечетных страницах "Страница .. из .." 
  MyWorksheet.PageLayout.Footers[HEADER_FOOTER_INDEX_EVEN] := '&LPage &P of &N';  // то же, но на четных страницах с выравниванием слева

Защита

В приложениях Office книги могут быть защищены от непреднамеренных изменений пользователем. fpspreadsheet способен читать и записывать структуры данных, связанные с защитой, но не применяет их. Это означает, например, что ячейки могут быть изменены пользователем, хотя рабочий лист указан как заблокированный.

Защита осуществляется на трех уровнях: защита рабочей книги, защита рабочего листа и защита элементов.

Защита рабочей книги

TsWorkbook содержит набор параметров защиты рабочей книги или документов:

• bpLockRevision: указывает, что книга заблокирована для ревизии
• bpLockStructure: если этот параметр установлен, рабочие листы в книге нельзя перемещать, удалять, скрывать, скрывать или переименовывать, а новые рабочие листы не могут быть вставлены.
• bpLockWindows: указывает, что окна книги в приложении Office заблокированы. Окна имеют одинаковый размер и положение каждый раз, когда рабочая книга открывается приложением Office.

В отношении защиты рабочей книги используется опция рабочего листа soPanesProtection, которая предотвращает изменение панелей рабочего листа, если рабочая книга защищена.

В зависимости от формата файла могут поддерживаться только некоторые из этих параметров. В этих случаях не поддерживаемые параметры являются общепринятыми значениями по умолчанию.

Защита рабочего листа

TsWorksheet содержит аналогичный набор параметров защиты. Всякий раз, когда опция включена в набор Protection рабочей книги, соответствующее действие не разрешено и заблокировано:

• spCells: ячейки в листе защищены. Это зависит от уровня защиты ячейки, может ли конкретная ячейка быть изменена или нет. По умолчанию ни одна ячейка не может быть изменена.
• spDeleteColumns: удаление столбцов не допускается
• spDeleteRows: удалить строки невозможно
• spFormatCells: форматирование ячеек не допускается
• spFormatColumns: столбцы не могут быть отформатированы
• spFormatRows: строки не могут быть отформатированы
• spInsertColumns: не допускается вставка столбцов
• spInsertRows: строки не могут быть вставлены
• spInsertHyperlinks: невозможно вставить новые гиперссылки
• spSort: рабочий лист не может быть отсортирован
• spSelectLockedCells: ячейки, которые заблокированы, больше не могут быть выбраны
• spSelectUnlockedCells: невозможно выбрать даже [те] ячейки, которые разблокированы. Вместе с spSelectLockedCells это означает, что выбор на листе заморожен.

Эти уровни защиты становятся активными, если опция soProtected добавлена в [набор] Options рабочего листа или [посредством] вызова метода Protect(true) рабочего листа.

Защита ячейки

Защита ячеек становится активной, когда включена защита рабочего листа. Он управляется набором элементов TsCellProtection, которые принадлежат к формату ячейки:

• cpLockCell: этот параметр определяет, может ли содержимое ячейки быть изменено пользователем. Поскольку по умолчанию ячейки защищенного рабочего листа обычно не могут редактироваться. Чтобы разблокировать некоторые ячейки для пользовательского ввода, опция cpLockCell должна быть удалена из защиты этих ячеек.
• cpHideFormulas: предотвращает отображение формул в приложении Office.

Защита ячейки может быть изменена путем вызова метода WriteCellProtection рабочего листа. И наоборот, [свойство] ReadCellProtection может использоваться для извлечения состояния защиты конкретной ячейки:

// запрос и изменение состояния защиты ячейки A1 (строка=0, столбец=0)
var
  cell: PCell;
  cellprot: TsCellProtections;
...
  // Находим ячейку
  cell := worksheet.FindCell(0, 0);
  // запрос защиты ячейки
  cellprot := worksheet.ReadCellProtection(cell);
  // Разблокировка ячейки для редактирования без изменения видимости формул
  worksheet.WriteCellProtection(cell, cellprot - [cpLockCell]);
  // Сокрытие формулы ячейки и разблокировка ячейки.
  worksheet.WriteCellProtection(cell, [cpHideFormulas]);

Защита

Защита рабочей книги и рабочего листа может быть обеспечена паролем. Обратите внимание, что эти пароли не шифруют файл (кроме защиты рабочей книги в Excel 2007). В приложениях Office пользователь должен ввести этот пароль, чтобы отключить защиту или изменить элементы защиты. Зашифрованный пароль хранится в записи CryptoInfo рабочей книги и рабочих листов соответственно:

type
  TsCryptoInfo = record
    PasswordHash: String;
    Algorithm: TsCryptoAlgorithm;  // caExcel, caSHA1, caSHA256, etc.
    SaltValue: String;
    SpinCount: Integer;
  end;

Загрузка и сохранение

Добавление новых форматов файлов

FPSpreadsheet открыт для любого формата файлов электронных таблиц. В дополнение к встроенным форматам файлов, которые указаны одной из деклараций sfXXXX, можно предоставить выделенные блоки чтения и записи для доступа к специальным форматам файлов.

• Напишите модуль, реализующий читателя и писателя для нового формата файла. Они должны наследоваться от базовых [типов] TsCustomSpreadReader и TsCustomWriter соответственно, — оба [типа] реализованы в модуле fpsReaderWriter — или из одного из более продвинутых, принадлежащих к встроенным форматов файлов.
• Зарегистрируйте новый читатель/писатель, вызвав функцию RegisterSpreadFileFormat в разделе initialization этого модуля (реализованной в модуле fpsRegFileFormats):

function RegisterSpreadFormat(AFormat: TsSpreadsheetFormat; AReaderClass: TsSpreadReaderClass; AWriterClass: TsSpreadWriterClass;
  AFormatName, ATechnicalName: String; const AFileExtensions: array of String): TsSpreadFormatID;

• AFormat должно иметь значение sfUser для регистрации внешнего формата файла.
• AReaderClass является классом читателя (или nil, если функция чтения не реализована).
• AWriterClass является классом писателя (или nil, если функция записи не реализована).
• AFormatName определяет имя формата, используемого, например, в списке фильтров диалогов открытия файла.
• ATechnicalName определяет более короткое имя формата.
• AFileExtensions представляет собой массив файловых расширений, используемых в файлах. Первый элемент массива обозначает расширение по умолчанию. Расширения должны начинаться с периода, [такого] как в .xls.
• Функция регистрации возвращает числовое значение (TsSpreadFormatID), которое может использоваться как идентификатор формата в функциях чтения и записи рабочей книги, которые существуют в перегруженной версии, принимая числовое значение для спецификатора формата. В соглашении со встроенными форматами FormatID отрицательный.
• Наконец, в вашем приложении добавьте новый модуль в секцию uses. Это вызовет функцию регистрации при загрузке устройства и сделает новый формат файла доступным для таблицы FPSpreadsheet.

Выбор потока

Рабочие книги загружаются и сохраняются с помощью методов ReadFromFile и WriteToFile, соответственно (или их потоковыми аналогами, ReadFromStream и WriteToStream).

По умолчанию доступ к файлам данных осуществляется с помощью «потока в памяти», что обеспечивает быстрый доступ к файлам. Однако в случае очень больших файлов (например, десятков тысяч строк) в системе может случиться нехватка памяти. Существует два способа отложить переполнение памяти в некоторой степени.

• Добавьте элемент boBufStream в Options рабочей книги. В этом случае для доступа к данным используется буферизированный поток. Этот вид потока содержит буфер памяти заданного размера и свопирует (сбрасывает на диск) данные в файл, если буфер становится слишком маленьким.
• Добавьте элемент boFileStream в Options рабочей книги. Эта опция позволяет избежать [создания] потоков в памяти целиком и создает временные файлы, если это необходимо. Это, однако, самый медленный способ доступа к данным.
• Если оба параметра установлены, то boBufStream игнорируется.
• Однако на практике эффект выбранных потоков невелик, если память должна быть сохранена.

Виртуальный режим

Помимо использования временной памяти при чтении/записи потребление основной памяти происходит во внутренней структуре FPSpreadsheet, которая хранит все данные в памяти. Чтобы преодолеть это ограничение, был введен «виртуальный режим». В этом режиме данные принимаются из источника данных (например, таблицы базы данных) и передаются писателю без сбора на рабочем листе. Понятно, что данные, загруженные в виртуальный режим, не могут отображаться в визуальных элементах управления. Виртуальный режим хорош для преобразования между различными форматами данных.

Ряд шагов, необходимых для использования этого режима:

• Активируйте виртуальный режим, добавив опцию boVirtualMode в Options рабочей книги.
• Сообщите писателю таблицы, сколько строк и столбцов должно быть записано. Соответствующими свойствами рабочего листа являются VirtualRowCount и VirtualColCount.
• Напишите обработчик для события OnWriteCellData рабочего листа. Этот обработчик получает индекс строки и столбца сохраняемой ячейки. Вы должны вернуть значение, которое будет сохранено в этой ячейке. Вы также можете указать ячейку шаблона, которая физически существует в рабочей книге, с которой стиль форматирования копируется в ячейку назначения. Имейте в виду, что при экспорте базы данных вы несете ответственность за продвижение указателя набора данных к следующей записи базы данных при заполнении строки.
• Вызовите метод WriteToFile рабочей книги.

Виртуальный режим также работает для чтения файлов электронных таблиц.

В папке example/other содержится разработанный образец проекта, демонстрирующий виртуальный режим с использованием случайных данных. Более реалистичные примеры баз данных приведены в example/db_import_export и в главе преобразование большой таблицы базы данных с использованием виртуального режима.

Экспорт данных

FPC содержит набор модулей, которые позволяют экспортировать наборы данных в различные форматы (XML, SQL-запросы, DBF-файлы, …). Существует основной пакет, который позволяет вам выбирать формат экспорта во время разработки или времени выполнения (пакет lazdbexport для Lazarus).

FPSpreadsheet имеет [свойство] TFPSExport, которое подключается к этой системе. Он позволяет экспортировать содержимое набора данных в файл новой электронной таблицы (.xls, .xlsx, .ods, формат wiki) с таблицей на первом листе по умолчанию. Кроме того, если MultipleSheets установлено значение TRUE, можно скомпоновать несколько листов в отдельные рабочие листы в том же файле. Вы можете дополнительно указать имена полей в качестве ячеек заголовка в первой строке, используя свойство HeaderRow в настройках экспорта. Компонент экспорта пытается найти формат номера ячеек в соответствии с типами полей набора данных.

Для более сложного экспорта вам необходимо вручную запрограммировать решение (см. примеры ниже), но для простой передачи данных/динамического экспорта по запросу пользователя этого модуля, вероятно, будет достаточно.

Простой пример того, как это работает:

uses
...
fpsexport
...
var
  Exp: TFPSExport;
  ExpSettings: TFPSExportFormatSettings;
  TheDate: TDateTime;
begin
  FDataset.First; //предположим, что у нас есть набор данных FDataset
  Exp := TFPSExport.Create(nil);
  ExpSettings := TFPSExportFormatSettings.Create(true);
  try
    ExpSettings.ExportFormat := efXLS; // выбираем формат файла
    ExpSettings.HeaderRow := true; // включаем строку заголовка с именами полей
    Exp.FormatSettings := ExpSettings; // применяем настройки для экспорта объекта
    Exp.Dataset:=FDataset; // указываем источник
    Exp.FileName := 'c:tempdatadump.xls';
    Exp.Execute; // запускаем экспорт
  finally
    Exp.Free;
    ExpSettings.Free;
  end;

Экспорт в DBF

Вы можете легко сохранить информацию из Excel в dbf. Вот пример из форума.
Обратите внимание, что этот пример должен работать с кодировкой Win1251 по умолчанию. Чтобы получить дополнительную информацию, обратитесь к этой теме [1]

procedure TForm1.ExportToDBF(AWorksheet: TsWorksheet; AFileName: String);
var
  i: Integer;
  f: TField;
  r, c: Cardinal;
  cell: PCell;
begin
  DbfGlobals.DefaultCreateCodePage := 1251; //кодировка по умолчанию dbf
  DbfGlobals.DefaultOpenCodePage := 1251; //кодировка по умолчанию dbf
  if Dbf1.Active then Dbf1.Close;
  if FileExists(AFileName) then DeleteFile(AFileName);

  Dbf1.FilePathFull := ExtractFilePath(AFileName);
  Dbf1.TableName := ExtractFileName(AFileName);
  Dbf1.TableLevel := 25;  // DBase IV: 4 - наиболее широко используется; или 25 = FoxPro поддерживает nfCurrency
  Dbf1.LanguageID := $C9; //русский язык по умолчанию
  Dbf1.FieldDefs.Clear;
  //ниже находятся поля в excel
  Dbf1.FieldDefs.Add('fam', ftString);
  //добавляем другие поля, которые вы хотите сохранить

  Dbf1.CreateTable;
  Dbf1.Open;

  for f in Dbf1.Fields do
    f.OnGetText := @DbfGetTextHandler;

  // Пропускаем строку 0, которая содержит заголовки
  for r := 1 to AWorksheet.GetLastRowIndex do begin
    Dbf1.Append;
    for c := 0 to Dbf1.FieldDefs.Count-1 do begin
      f := Dbf1.Fields[c];
      cell := AWorksheet.FindCell(r, c);
      if cell = nil then
        f.Value := NULL
      else
        case cell^.ContentType of
          cctUTF8String: f.AsString := UTF8ToCP1251(cell^.UTF8StringValue);
          cctNumber: f.AsFloat := cell^.NumberValue;
          cctDateTime: f.AsDateTime := cell^.DateTimeValue;
          else f.AsString := UTF8ToCP1251(AWorksheet.ReadAsText(cell));
        end;
    end;
    Dbf1.Post;
  end;
end;

//Эта процедура вызывается так, чтобы текст в ячейках мог корректно отображаться в сетке рабочего листа на форме, иначе отобразятся симовлы '?'
procedure TForm1.DbfGetTextHandler(Sender: TField; var AText: string; DisplayText: Boolean);
begin
  if DisplayText then
    AText := CP1251ToUTF8(Sender.AsString);
end;

Визуальные элементы управления для FPSpreadsheet

Пакет ‘laz_fpspreadsheet_visual’ реализует серию элементов управления, которые имитируют создание визуальных графических приложений:

• TsWorkwookSource связывает элементы управления с рабочей книгой и уведомляет элементы управления об изменениях в рабочей книге.
• TsWorksheetGrid реализует управление сеткой с возможностями редактирования и форматирования; он может применяться аналогично TStringGrid.
• TsWorkbookTabControl предоставляет набор вкладок для каждого листа рабочей книги. Это идеальный контейнер для TsWorksheetGrid.
• TsCellEdit соответствует строке редактирования в Excel или Open/LibreOffice. Однако возможно прямое редактирование в сетке.
• TsCellIndicator отображает имя текущей выбранной ячейки; его можно использовать с целью навигации [посредством] ввода строки адреса ячейки.
• TsCellCombobox предлагает выбрать свойства ячейки для определения атрибутов форматирования: имя шрифта, размера шрифта, цвета шрифта, цвета фона.
• TsSpreadsheetInspector является инструментом, главным образом, для отладки; он отображает различные свойства рабочей книги, рабочего листа, значения ячейки и форматирования ячеек, [компонент] аналогичен ObjectInspector Lazarus’а. Однако он доступен только для чтения.
• В модуле fpsActions предусмотрены различные стандартные действия. Примененные к меню или панели инструментов, они упрощают типичные задачи форматирования и редактирования без необходимости писать строки кода.
• TsWorkbookChartSource связывает рабочую книгу с библиотекой TAChart. Он определяет диапазоны ячеек, из которых диаграмма может получить свои данные. Существует также старый компонент TsWorksheetChartSource, который требует, чтобы все ячейки были на одном листе. По этой причине он не был полностью интегрирован в среду элементов управления FPSpreadsheet и будет удален из библиотеки в будущем.

См. Учебник FPSpreadsheet: написание приложения для мини-таблиц для получения дополнительной информации и обучения, а также см. demo projects [, чтобы посмотреть] примеры применения этих компонентов.

Примеры

Чтобы создать проект, который использует библиотеку fpspreadsheet, добавьте пакет fpspreadsheet_pkg в проект Lazarus или добавьте корневой каталог fpspreadsheet к вашим параметрам компилятора, если используете другую IDE.

Модули

Весь пакет FPSpreadsheet состоит из нескольких модулей. Приложение электронной таблицы обычно «использует» следующие модули:

• fpspreadsheet: реализует TsWorkbook и TsWorksheet, а также Основные методы чтения/записи файлов
• fpstypes: объявляет большинство типов данных и констант, используемых во всех пакетах. Примечание: в старых версиях эти объявления содержались в файле fpspreadsheet.pas.
• модули, реализующие [возможность] чтения/записи для заданного формата файла, напр. xlsbiff8 для двоичных файлов Excel. Если приложение будет в состоянии обрабатывать все форматы, «используйте» модуль fpsallformats.

Следующие модули необходимы только изредка:

• fpsutils: набор полезных функций, которые иногда [бывают] необходимы (напр., преобразование индексов col/row в Excel-подобную строку адреса ячейки).
• fpscell: этот модуль требуется, если вы используете форматирование ячеек напрямую (например, cell^.BackgroundColor := scYellow) вместо вызова соответствующего метода рабочего листа MyWorksheet.WriteBackgroundColor(cell, scYellow) в этом примере).
• fpsnumformat: сосредотачивает все служебные функции, связанные с форматированием чисел.

Все остальные модули, вероятно, не нужны на уровне приложений. В случае визуальных элементов управления spreadsheet необходимые модули обычно вставляются во время разработки автоматически.

Примеры Excel 5

Примечание: этот пример требует [наличия модулей] avglvltree.pas, lazutf8.pas, asiancodepagefunctions.inc, asiancodepages.inc и lconvencoding.pas ([расположенных] в $(LazarusDir)componentslazutils ), по крайней мере для fpspreadsheet транковой (для разработчиков) версии Лазаруса

{
excel5demo.dpr

Демонстрирует, как написать файл Excel 5.x, используя библиотеку fpspreadsheet

Вы можете изменить выходной формат, изменив константу OUTPUT_FORMAT

АВТОР: Felipe Monteiro de Carvalho
}
program excel5demo;

{$mode delphi}{$H+}

uses
  Classes, SysUtils, fpstypes, fpspreadsheet, fpsallformats, laz_fpspreadsheet;

const 
  OUTPUT_FORMAT = sfExcel5;

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyFormula: TsRPNFormula;
  MyDir: string;
begin
  // Инициализация
  MyDir := ExtractFilePath(ParamStr(0));

  // Создание рабочей книги
  MyWorkbook := TsWorkbook.Create;
  try
    MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet');

    // Записываем некоторые номера ячеек
    MyWorksheet.WriteNumber(0, 0, 1.0);
    MyWorksheet.WriteNumber(0, 1, 2.0);
    MyWorksheet.WriteNumber(0, 2, 3.0);
    MyWorksheet.WriteNumber(0, 3, 4.0);

    // Записываем формулу E1 = A1 + B1
    MyWorksheet.WriteFormula(0, 4, 'A1+B1');

    // Создаем новый рабочий лист
    MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet 2');

    // Записываем некоторые строки ячеек
    MyWorksheet.WriteText(0, 0, 'First');
    MyWorksheet.WriteText(0, 1, 'Second');
    MyWorksheet.WriteText(0, 2, 'Third');
    MyWorksheet.WriteText(0, 3, 'Fourth');

    // Сохраняем электронную таблицу в файл
    MyWorkbook.WriteToFile(MyDir + 'test' + STR_EXCEL_EXTENSION, OUTPUT_FORMAT);
  finally
    MyWorkbook.Free;
  end;
end.

Открытие существующей таблицы

Чтобы открыть таблицу, указав конкретный формат для использования, задействуйте [процедуру] ReadFromFile с двумя параметрами:

MyWorkbook.ReadFromFile(AFileName, sfExcel5);

Также можно вызвать ReadFromFile только с одним параметром — именем файла. Тогда в книге будет использоваться расширение [на основе] автоматического определения формата файла. В случае неоднозначного расширения .xls (Excel 2-8) [механизм автодетектирования] просто попробует различные возможности до тех пор, пока не сработает. Хотя типичные шаблоны байтов отпечатков пальцев теперь проверяются, все же возможно, что исключение будет поднято для каждого неправильного формата, если он запускается из среды IDE во время разработки; это не происходит во время выполнения.

MyWorkbook.ReadFromFile(AFileName);

Запись электронной таблицы в файл на основе расширения

Подобно процедуре ReadFromFile, также существует процедура WriteToFile для определения типа электронной таблицы на основе суффикса имени файла. Она использует процедуру GetFormatFromFileName в коде предыдущего раздела, поэтому фактический код прост. Тем не менее, она всегда будет записывать файлы с заданным расширением, используя последний формат, который использует это расширение (например, файлы Excel .xls будут записаны как sfExcel8), поэтому, если вы хотите их записать в более раннем формате, то должны использовать базовую процедуру.

Как и выше, этот код исправляет модуль fpspreadsheet.pas.

procedure TsWorkbook.WriteToFile(const AFileName: string; const AOverwriteExisting: Boolean = False); overload;
var SheetType: TsSpreadsheetFormat;
begin
  if getFormatFromFileName(AFileName, SheetType) then
    WriteToFile(AFileName, SheetType, AOverwriteExisting)
  else raise Exception.Create(Format(
    '[TsWorkbook.WriteToFile] [Сделана] попытка сохранить электронную таблицу по расширению, но расширение %s недействительно.', [ExtractFileExt(AFileName)]));
end;

Итерация по всем рабочим листам

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  i: Integer;
begin
  // Здесь загружаем MyWorkbook из файла или создаем его
 
  for i := 0 to MyWorkbook.GetWorksheetCount() - 1 do
  begin
    MyWorksheet := MyWorkbook.GetWorksheetByIndex(i);
    // Делаем что-нибудь с MyWorksheet
  end;

Итерация через ячейки

Первая идея — использовать простой цикл for-to:

var
  MyWorksheet: TsWorksheet;
  col, row: Cardinal;
  cell: PCell;
begin
  for row:=0 to MyWorksheet.GetLastRowIndex do
    for col := 0 to MyWorksheet.GetLastColIndex do
    begin
      cell := MyWorksheet.FindCell(row, col);
      WriteLn(MyWorksheet.ReadAsUTF8Text(cell));
    end;
end;

FindCell инициирует поиск ячейки независимо от ранее найденной ячейки. Ячейки, однако, организованы между собой в отсортированной древовидной структуре, и каждая ячейка «знает» своих предыдущих и следующих соседей. Более того, FindCell тратит время на поиск несуществующих ячеек в случае редко занятых рабочих листов. В общем, более эффективно использовать синтаксис for-in, который использует внутреннюю древовидную структуру с помощью специальных счетчиков. Обратите внимание, что существуют также специализированные счетчики для поиска по строкам, столбцам или диапазонам ячеек:

var
  MyWorksheet: TsWorksheet;
  cell: PCell;
begin
  // Поиск по всем ячейкам
  for cell in Myworksheet.Cells do
    WriteLn(MyWorksheet.ReadAsText(cell));

  // Поиск только в столбце 0
  for cell in MyWorksheet.Cells.GetColEnumerator(0) do
    WriteLn(MyWorksheet.ReadAsText(cell));

  // Поиск только в строке 2
  for cell in MyWorksheet.Cells.GetRowEnumerator(2) do
    WriteLn(MyWorksheet.ReadAsText(cell));

  //Поиск только в диапазоне A1:C2 (строки 0..1, столбцы 0..2)
  for cell in MyWorksheet.Cells.GetRangeEnumerator(0, 0, 1, 2) do
    WriteLn(MyWorksheet.ReadAsText(cell));
end;

Преобразование базы данных в электронную таблицу

Самое простое решение — использовать DatasetExport component (прим.перев: ссылка на компонент не корректна).

Если вам нужно больше контролировать процесс, используйте что-то вроде:

program db5xls;
 
{$mode delphi}{$H+}
 
uses
  Classes, SysUtils, 
  // добавить модули базы данных
  fpstypes, fpspreadsheet, fpsallformats;
 
const OUTPUT_FORMAT = sfExcel5;
 
var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyDatabase: TSdfDataset;
  MyDir: string;
  i, j: Integer;
begin
  // Инициализация
  MyDir := ExtractFilePath(ParamStr(0));
 
  // Открываем базу данных
  MyDatabase := TSdfDataset.Create;
  MyDatabase.Filename := 'test.dat';
  // Добавляем здесь описание таблицы
  MyDatabase.Active := True;

  // Создаем электронную таблицу
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet');
 
  // Записываем имена полей
  for i := 0 to MyDatabase.Fields.Count - 1 do
    MyWorksheet.WriteText(0, i, MyDatabase.Fields[i].FieldName);

  // Записываем все ячейки в рабочий лист
  MyDatabase.First;
  j := 0;
  while not MyDatabase.EOF do
  begin
    for i := 0 to MyDatabase.Fields.Count - 1 do
      MyWorksheet.WriteText(j + 1, i, MyDatabase.Fields[i].AsString);

    MyDatabase.Next;
    Inc(j);
  end;

  // Закрываем базу данных
  MyDatabase.Active := False;
  MyDatabase.Free;

  // Сохраняем электронную таблицу в файл
  MyWorkbook.WriteToFile(MyDir + 'test' + STR_EXCEL_EXTENSION, OUTPUT_FORMAT);
  MyWorkbook.Free;
end.

Преобразование большой таблицы базы данных в электронную таблицу с использованием виртуального режима

Мы хотим записать большую таблицу базы данных в файл электронной таблицы. Первая строка электронной таблицы — это отображение названий полей жирным шрифтом и серым фоном.

Обычно FPSpreadsheet загружает полное представление электронной таблицы в память, поэтому мы будем использовать виртуальный режим для минимизации использования памяти.

type
  TDataProvider = class;

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyDatabase: TSdfDataset;
  MyDir: string;
  MyHeaderTemplateCell: PCell;
  DataProvider: TDataProvider;

// Внедрите TDataProvider здесь - см. ниже ...

begin
  // Инициализация
  MyDir := ExtractFilePath(ParamStr(0));
 
  // Открываем базу данных
  MyDatabase := TSdfDataset.Create;
  try
    MyDatabase.Filename := 'test.dat';
    // Добавляем описание таблицы здесь
    MyDatabase.Active := True;

    // Создаем электронную таблицу
    MyWorkbook := TsWorkbook.Create;
    try
      MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet');

      // Создаем шаблон ячейки для строки заголовка, мы хотим, 
      // чтобы заголовок [был начертан] жирным и на сером фоне
      // Шаблон ячейки может быть, где угодно, в рабочей книге, просто выберите ячейку A1.
      MyWorksheet.WriteFontStyle(0, 0, [fssBold]);
      MyWorksheet.WriteBackgroundColor(0, 0, scGray);
      // Нам понадобится эта ячейка снова и снова, поэтому давайте сохраним указатель на нее в переменной
      MyHeaderTemplateCell := MyWorksheet.Find(0, 0);
 
      // Входим в виртуальный режим
      MyWorkbook.Options := MyWorkbook.Options + [boVirtualMode];

      // Определяем количество столбцов - нам нужен столбец для каждого поля
      MyWorksheet.VirtualColCount := MyDatabase.FieldCount;

      // Определяем количество строк - нам нужна каждая запись, плюс 1 строка для заголовка
      MyWorksheet.VirtualRowCount := MyDatabase.RecordCount + 1;

      // Связываем обработчик событий, который передает данные из базы данных в "писатель" электронной таблицы
      MyWorksheet.OnWriteCellData := @DataProvider.WriteCellData;

      // Записываем все ячейки в файл Excel8
      // Данные, которые должны быть записаны, указаны в обработчике событий OnWriteCellData.
      MyWorkbook.WriteToFile(MyDir + 'test.xls', sfExcel8);

    finally
      // Освобождаем
      MyWorkbook.Free;
    end;

  finally
    // Закрываем базу данных и освобождаем ее
    MyDatabase.Active := False;
    MyDatabase.Free;
  end;

end.

Осталось написать обработчик событий для OnWriteCellData. Для консольной программы выше мы устанавливаем конкретный класс поставщика данных (в визуальной программе обработчик событий также может быть методом любой формы):

type
  TDataProvider = class
    procedure WriteCellData(Sender: TsWorksheet; ARow, ACol: Cardinal; var AValue: variant; var AStyleCell: PCell);
  end;

procedure TDataProvider.WriteCellData(Sender: TsWorksheet; ARow, ACol: Cardinal; AValue: variant; var: AStyleCell: PCell);
begin
  // Сначала обработаем строку заголовка:
  if ARow = 0 then begin
    // Значение, которое должно быть записано в электронную таблицу, - это имя поля.
    AValue := MyDatabase.Fields[ACol].FieldName;
    // Форматирование определено в HeaderTemplateCell.
    AStyleCell := MyHeaderTemplateCell;
    //Перемещаемся на первую запись
    MyDatabase.First;
  end else begin
    // Значение, которое должно быть записано в электронную таблицу, является значением записи в поле, соответствующем столбцу.
    // Никаких особых требований к форматированию --> оставляем AStyleCell по умолчанию (nil).
    AValue := MyDatabase.Fields[ACol].AsVariant;
    // Передвигаем курсор базы данных, если было записано последнее поле записи
    if ACol = MyDatabase.FieldCount-1 then MyDatabase.Next;
  end;
end;

Преобразование между двумя форматами электронных таблиц

program ods2xls;
 
{$mode delphi}{$H+}
 
uses
  Classes, SysUtils, 
  fpstypes, fpspreadsheet, fpsallformats, fpspreadsheet_pkg;
 
const 
  INPUT_FORMAT = sfOpenDocument;
  OUTPUT_FORMAT = sfExcel8;
 
var
  MyWorkbook: TsWorkbook;
  MyDir: string;
begin
  // Инициализация
  MyDir := ExtractFilePath(ParamStr(0));
 
  // Преобразование электронной таблицы
  MyWorkbook := TsWorkbook.Create;
  try
    MyWorkbook.ReadFromFile(MyDir + 'test.ods', INPUT_FORMAT);
    MyWorkbook.WriteToFile(MyDir + 'test.xls', OUTPUT_FORMAT);
  finally
    MyWorkbook.Free;
  end;
end.

Чтение и запись CSV-файлов

CSV-файлы (CSV = значения, разделенные запятыми) — это текстовые файлы без метаданных. Поэтому требуется дополнительная информация для правильного чтения записи из/в рабочий лист. Глобальная записьCSVParams предоставляет основные настройки для этой цели:

type
  CSVParams: TsCSVParams = record    // W = запись, R = чтение, RW = чтение/запись
    SheetIndex: Integer;             // W: Индекс листа, который должен быть записан
    LineEnding: TsCSVLineEnding;     // W: Спецификация для конца строки, который должен быть записан
    Delimiter: Char;                 // RW: Разделитель столбцов
    QuoteChar: Char;                 // RW: Символ для квотированного ([заключенного в двойные кавычки]) текста
    Encoding: String;                // RW: Кодировка файла
    DetectContentType: Boolean;      // R: попытка конвертации строк в типы контента 
    NumberFormat: String;            // W: если пустые записи чисел, как на листе; в противном случае используется этот формат
    AutoDetectNumberFormat: Boolean; // R: автоматически определяет десятичный/тысячный разделитель, используемый в числах
    TrueText: String;                // RW: Строка для логического TRUE
    FalseText: String;               // RW: Строка для логического FALSE
    FormatSettings: TFormatSettings; // RW: добавляет параметры для преобразования
  end;