FPSpreadsheet/ru

From Free Pascal wiki
Revision as of 10:06, 13 September 2018 by Zoltanleo (talk | contribs)
Jump to navigationJump to search

│ Deutsch (de) │ English (en) │ español (es) │ français (fr) │ polski (pl) │ русский (ru) │

ENG: AT THE MOMENT THIS PAGE IS UNDER CONSTRUSTION. PLEASE USE THE ENGLISH PAGE.
RUS: В НАСТОЯЩИЙ МОМЕНТ СТРАНИЦА НАХОДИТСЯ В ПРОЦЕССЕ РЕКОНСТРУКЦИИ И ПЕРЕВОДА. ПОЖАЛУЙСТА, ВРЕМЕННО ИСПОЛЬЗУЙТЕ АНГЛОЯЗЫЧНУЮ ВЕРСИЮ


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

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


fpsgrid.png


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

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

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

Ссылка на API

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


--Zoltanleo (talk) 16:53, 10 September 2018 (CEST) В англоязычном оригинале ссылка на мануал битая. Контроллер внешних ссылок wiki не дает корректно вставить исправленную ссылку


Второй файл 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</ tt> относится к текстовым файлам с разделителями-запятыми (расширение по умолчанию .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):
    dto., но формат файла определяется из предоставленного расширения файла (в случае 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</ tt>, если ячейка еще не существует, а вторая создает пустую ячейки в этом случае. 

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


Основа записи TCell

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

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: запись комментарий находится в Комментарии рабочего листа.
  • cfHyperlink: ячейка содержит гиперссылку гиперссылка, хранящуюся в Hyperlinks рабочего листа.
  • cfMerged: ячейка принадлежит блоку объединенные блоки и распространяется через несколько ячеек.
  • cfHasFormula: ячейка связана с формулой, которая хранится в Formulas рабочего листа.
  • cf3dFormula: Формула, связанная с ячейкой, содержит элементы, ссылающиеся на другие листы той же книги.
Light bulb  Примечание: После вычисления формулы или после прочтения файла ContentType ячейки формулы преобразуется в формулу результата. Тогда наличие формулы может быть обнаружено только путем вызова функции HasFormula(cell) для запрашиваемой ячейки (cell: PCell) в модуле fpsUtils ; эта функция проверяет наличие элемента cfHasFormula в флажках ячейки.


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

Добавление значений в ячейку наиболее легко сопровождается использованием одного из методов 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;
    ...
Формат Index to Cell

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</ tt>: выравнивание по левому краю, по горизонтали или по правому краю
  • VertAlignment: верхний, нижний или вертикально центрированный текст
  • Border</ tt>: набор флагов, указывающий, что - если установлено - линия границы нарисована в левом, верхнем, правом или нижнем краях ячеек. Линии рисуются в соответствии с 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</ tt>, сколько десятичных знаков должно быть показано. (Число 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 (см. интерактивную справку для этих функций).

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

Символ Определение Строка формата: число --> Выходная строка
General Отображает все десятичные знаки числа 'General':
1.2345678 --> '1.2345678'
0 Отображает не значащие нули, если число имеет меньше знаков, чем [количество] нулей в формате. Если [строка формата] используется для десятичных знаков, то число округляется до такого количества знаков после запятой, что и 0. '000': 1 --> '001'
'0.0': 1 --> '1.0'
'0.0': 1.2345678 --> '1.2'
* Как [и для] "0" выше, но не отображает не значащие нули. '0.*': 1 --> '1.'
'0.*': 1.2345678 --> '1.2'
? Как [и для] "0" выше, но не существенные нули заменяются пробелами. Хорошо для выравнивания десятичных точек и фракций

'??0': 1 --> ' 1'
'0.0??': 1 --> '1.0 '

. Десятичный разделитель; будет заменено значением, используемым в DecimalSeparator [параметра] FormatSettings рабочей книги '0.00': 8.9 --> '8.90'
, Разделитель тысячных [разрядов]; будет заменено значением, используемым в ThousandSeparator [параметра] FormatSettings рабочей книги. Если [сепаратор указан] в конце последовательности форматирования числа, [то] отображаемое значение делится на 1000. '#,##0.00': 1200 --> '1,200.00'
'0.00,': 1200 --> '1.20'
E+, e+ Отображает число в экспоненциальном формате. Цифры, используемые для показателя, определяются числом нулей, добавленным этим символом. Знак экспонента показан для положительных и отрицательных показателей. '0.00E+00': 1200 --> 1.20E+03
E-, e- Отображает число в экспоненциальном формате. Цифры, используемые для показателя, определяются числом нулей, добавленным этим символом. Знак экспонента показан только для отрицательных показателей. '0.00e-000': 1200 --> 1.20e003
% Отображает число как «процент», т.е. число умножается на 100 и добавляется знак %. '0.0%': 0.75 --> 75.0%
/ Этот символ имеет два значения: если ячейка представляет собой "число", то косая черта означает форматирование как дробь, числитель и знаменатель должны следовать зарезервированному месту. Если ячейка представляет "дату/время", то косая черта обозначает разделитель даты, который будет заменен на DateSeparator в [параметре] FormatSettings рабочего листа '#/#': 1.5 --> '3/2'
'# #/#': 1.5 --> '1 1/2'
'# #/16': 1.5 --> '1 8/16'
также: см. примеры даты/времени ниже
: Разделитель между часами, минутами и секундами значения даты/времени. Будет заменен [на] TimeSeparator [параметра] FormatSettings рабочей книги. смотри пример ниже
yyyy Зарезервированное место для года значения даты/времени. Год отображается как четырехзначное число. 'yyyy/mm/dd':
Jan 3, 2012 --> '2012-01-03'
В этом примере DateSeparator является символом тире (-).
yy Зарезервированное место для года значения даты/времени. Год отображается как двузначное число. 'yy/mm/dd':
Jan 3, 2012 --> '12-01-03'
m Зарезервированное место для месяца значения даты/времени. Месяц отображается как число без дополнительных цифр.
Обратите внимание, что код m также можно интерпретировать как «минуты» значения времени (см. ниже).		 'yyyy/m/dd':
Jan 3, 2012 --> '2012-1-03'
mm Зарезервированное место для месяца значения даты/времени. Месяц отображается как двузначное число, то есть начальный ноль добавляется с января по сентябрь.
Обратите внимание, что код mm также может быть интерпретирован как "минуты" (см. ниже).		 'yyyy/mm/dd':
Jan 3, 2012 --> '2012-01-03'
mmm Зарезервированное место для месяца значения даты/времени. Месяц отображается [в виде] аббревиатуры. 'yyyy/mmm/dd':
Jan 3, 2012 --> '2012-Jan-03'
mmmm Зарезервированное место для месяца значения даты/времени. Месяц отображается полным именем.
'yyyy/mmm/dd':
Jan 3, 2012 --> '2012-January-03'
d Зарезервированное место дня значения даты/времени, которое будет отображаться в виде числа. День отображается как простое число без добавления начального нуля. 'yyyy/mm/d':
Jan 3, 2012 --> '2012-01-3'
dd Зарезервированное место дня значения даты/времени, которое будет отображаться в виде числа. dd добавляет [лидирующий] ноль в однозначные числа. 'yyyy/mm/dd':
Jan 3, 2012 --> '2012-01-03'
ddd Зарезервированное место дня значения даты/времени. День отображается в виде аббревиатуры. 'dddd, yyyy/mm/ddd':
Jan 03, 2012 --> 'Tue 2012-01-03'
dddd Зарезервированное место дня значения даты/времени. День отображается полным именем. 'dddd, yyyy/mmmm/dd':
Jan 03, 2012 --> 'Tuesday 2012-01-03'
h Зарезервированное место часовой части значения даты/времени. Час отображается как простое число без добавления начального нуля. 'h:mm':
0.25 --> '6:00'
hh Зарезервированное место часовой части значения даты/времени. Час отображается с начальным нулем, если час меньше 10. 'hh:mm':
0.25 --> '06:00'
[hh], или [h] Отображает прошедшее время, так что часовая часть может стать больше 23 '[h]:mm':
1.25 --> '30:00'
m Зарезервированное место минутной части значения даты/времени. Минуты показаны как простое число без добавления начального нуля. Заметим, что если коды m окружены символами даты (y, d), то они интерпретируются как "месяц". 'h:m':
0.25 --> '6:0'
mm Зарезервированное место минутной части значения даты/времени. Минуты с одной цифрой отображаются с начальным нулем. Заметим, что если код mm окружен символами даты (y, d), то он интерпретируется как "месяц". 'h:mm':
0.25 --> '6:00'
[mm], или [m] Отображает прошедшее время так, что минутная часть может стать больше 59 '[mm]:ss':
1.25 --> '1800:00'
s Зарезервированное место секундной части значения даты/времени. Секунды отображаются как простое число без добавления начального нуля. 'hh:mm:s':
0.25 --> '06:00:0'
ss Зарезервированное место секундной части значения даты/времени. Секунды с одной цифрой отображаются с начальным нулем. 'hh:mm:ss':
0.25 --> '06:00:00'
[ss], или [s] Отображает прошедшее время так, что секундная часть может стать больше, чем 59 '[ss]':
1.25 --> '108000'
AM/PM, am/pm, A/P, или a/p Отображает время в 12-часовом формате. 'hh:mm:ss AM/PM':
0.25 --> '6:00:00 AM'
" Текст, заключенный в кавычки, вставляется в форматированные строки буквально. 'yyyy"/"mm"/"dd':
Jan 3, 2012 --> '2012/01/03' (т. е. / не заменяется свойством DateSeparator рабочей книги).
\ Следующий символ строки формата отображается в строке результата буквально. Сам \ не отображается.

'yyyy\/mm\/dd':
Jan 3, 2012 --> '2012/01/03'

; Строка формата может содержать до трех разделов, разделенных точкой с запятой. Первый раздел используется для положительных чисел, второй - для отрицательных чисел, а третий - для нулевых чисел. Если третий раздел отсутствует, то нулевое значение форматируется, как указано в первом разделе. Если второй раздел также отсутствует, то все значения форматируются в соответствии с первым разделом. '"#,##0"$"';-#,##0"$";"-"':
1200 --> '1,200$'
-1200 --> '1,200$'
0 --> '-'
(, и ) Иногда используется для значений валюты, указывающих отрицательные числа, вместо знака "минус" '#,##0"$";(#,##0)"$"':
-1200 --> '(1200)$'
[red] Отформатированная строка отображается в указанном цвете. Вместо [red] вы можете использовать соответственно [black], [white], [green], [blue], [magenta], [yellow], или [cyan]. Часто используется для выделения отрицательных значений валюты. '"$" #,##0.00;[red]("$" #,##0.00)':
-1200 --> '($ 1200.00)'

Цвета

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

Predefined colors
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.)

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

Light bulb  Примечание: В более старых версиях цвета библиотеки были определены как индексы в цветовой палитре. ЭТО НЕ БОЛЬШЕ РАБОТАЕТ.

Модуль 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);

Cell borders

Cells can be emphasized by drawing border lines along their edges or diagonal lines. There are four borders plus two diagonals enumerated in the data type TsCellBorder: 

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

In order to show a border line add the corresponding border to the cell's set Borders (type TsCellBorders, see above). In this way, each cell edge can be handled separately. Use the worksheet method WriteBorders for this purpose. This example adds top and bottom borders to the edges A1 and B1: 

  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]);  // A1: row 0, column 0
  MyWorksheet.WriteBorders(0, 1, [cbNorth, cbSourth]); // B1: row 0, column 1

Lines usually are drawn as thin, solid, black lines. But it is possible to modify line style and color of each line. For this purpose, the cell provides an array of TsCellBorderStyle records: 

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;

The style of a given cell border can be specified by the following methods provided by the worksheet:

  • WriteBorderStyle assigns a cell border style record to one border of the cell. There are two overloaded versions of this method: one takes an entire TsCellBorderStyle record, the other one takes the individual record elements.
  • WriteBorderColor changes the color of a given border without affecting the line style of this border.
  • WriteBorderLineStyle sets the line style of the border only, but leaves the color unchanged.
  • WriteBorderStyles sets the border style of all borders of a given cell at once. Useful for copying border styles from one cell to other cells.

This example adds a thin black border to the top, and a thick blue border to the bottom of cells A1 and B1: 

var
  cellA1, cellB1: PCell;
...
  cellA1 := MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]);    // cell A1: row 0, column 0
  MyWorksheet.WriteBorderStyle(cellA1, cbNorth, lsThin, scBlack);  
  MyWorksheet.WriteBorderStyle(cellA1, cbSouth, lsThick, scBlue);

  cellB1 := MyWorksheet.WriteBorders(0, 1, [cbNorth, cbSouth]);    // cell B1: row 0, column 1
  MyWorksheet.WriteBorderStyles(cellB1, cellA1^.BorderStyles);     // copy all border styles from cell A1 to B1
Light bulb  Примечание: Diagonal lines are not supported by sfExcel2 and sfExcel5 - they are just omitted. sfExcel8 and sfOOXML use the same linestyle and color for both diagonals; when writing the border style of the diagonal-up line is assumed to be valid also for the diagonal-down line. Some writers do not support all the line styles of the TsLineStyle enumeration. In this case, appropriate replacement line styles are used.

Fonts

The cell text can displayed in various fonts. For this purpose, the workbook provides a list of TsFont items: 

type
  TsFont = class
    FontName: String;
    Size: Single;   
    Style: TsFontStyles;
    Color: TsColor;
    Position: TsFontPosition;
  end;
  • The FontName corresponds to the name of the font as used by the operational system. In Windows, an example would be "Times New Roman".
  • The FontSize is given in "points", i.e. units 1/72 inch which are commonly used in Office applications.
  • The FontStyle is a set of the items fssBold, fssItalic, fssStrikeout, and fssUnderline which form the enumeration type TsFontStyle. The "normal" font corresponds to an empty set.
  • The Color determines the foreground color of the text characters given in rgb presentation as discussed above.
  • The Position is either fpNormal, fpSuperscript, or fpSubscript and indicates whether the font size should be decreased by about 1/3 and the characters should be displaced up (superscript) or down (subscript).

Every cell is provided with an index into the font list.

In order to assign a particular font to a cell, use one of the following methods of 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; 
    // plus: overloaded versions accepting a pointer to a cell record instead of the row and column index as parameter
    // ...
  end;
  • WriteFont assigns a font to the cell. If the font does not yet exist in the font list a new entry is created. The function returns the index of the font in the font list. In addition, there is an overloaded version which only takes the font index as a parameter.
  • WriteFontColor replaces the color of the font that is currently assigned to the cell by a new one. Again, a new font list item is created if the font with the new color does not yet exist. The function returns the index of the font in the list.
  • WriteFontSize replaces the size of the currently used font of the cell.
  • WriteFontStyle replaces the style (normal, bold, italic, etc.) of the currently used cell font.

The workbook's font list contains at least one item which is the default font for cells with unmodified fonts. By default, this is 10-point "Arial". Use the workbook method SetDefaultFont to assign a different font to the first list item.

The font at a given index of the font list can be looked up by calling the workbook function GetFont. The count of available fonts is returned by GetFontCount.

Here is an example which decreases the size of all 10-point "Arial" fonts to 9-point: 

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 formatting

In addition to using a specific font for each cell it is also possible to specify particular font attributes for individual characters or groups of characters in each cell text. Following the Excel notation, we call this feature Rich-text formatting (although is has nothing in common with the "rich-text" file format).

For this purpose, unit fpstypes declares the type TsRichTextParams which is an array of TsRichTextParam records: 

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

  TsRichTextParams = array of TsRichTextParam;

FontIndex refers to the index of the font in the workbook's FontList to be used for formatting of the characters beginning at the index FirstIndex. Being a string character index the FirstIndex is 1-based.

There are two ways to add "rich-text" formatting to a cell text:

  • Embed corresponding HTML format codes into the cell text. This can be done using the method WriteTextAsHTML of the worksheet. In order to add the text "Area (m2)" to cell A1, pass the following HTML-coded string to this function
  MyWorksheet.WriteTextAsHTML(0, 0, 'Area (m<sup>2</sup>');
  • Alternatively, the standard text writing method, WriteText can be called with an additional parameter specifiying the rich-text formatting parameters to be used directly:
var
  richTextParams: TsRichTextParams;
  fnt: TsFont;
begin
  SetLength(rtp, 2);
  fnt := MyWorksheet.ReadCellFont(0, 0);
  richTextParams[0].FirstIndex := 8; // The superscript groups begins with "2" which is the (1-based) character #8 of the cell text.
  richTextParams[0].FontIndex := MyWorkbook.AddFont(fnt.FontName, fnt.Size, fnt.Style, fnt.Color, fpSuperscript);
  richTextParams[1].FirstIndex := 9; // Normal font again beginning with character #9.
  richTextParams[1].FontIndex := MyWorksheet.ReadCellFontIndex(0, 0);
  MyWorksheet.WriteUTF8Text(0, 0, 'Area (m2)', richTextParams);
end;

Use the worksheet method DeleteRichTextParams to remove rich-text formatting from a previously formatted cell.

Light bulb  Примечание: If the cell is supposed to have a font different from the worksheet's default font then this font must be written to the cell before writing the rich-text formatted text. Otherwise the font in the unformatted regions will not be up-to-date.

Text rotation

Usually text is displayed in the cells horizontally. However, it is also possible to rotate it by 90 degrees in clockwise or counterclockwise directions. In addition, there is also an option to stack horizontal characters vertically above each other.

If you need this feature use the worksheet method WriteTextRotation and specify the text direction by an element of the enumeration type 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;

  // example for counter-clockwise rotated text in cell A1:
  WriteTextRotation(0, 0, rt90DegreeCounterClockwizeRotation);
Warning-icon.png

Предупреждение: Finer degrees of rotation which may be supported by some spreadsheet file formats are ignored.

Text alignment

By default, cell texts are aligned to the left and bottom edges of the cell, except for numbers which are right-aligned. This behavior can be changed by using the worksheet methods WriteHorAlignment and 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;

  // Example: Center the text in cell A1 both horizontally and vertically
  MyWorkbook.WriteHorAlignment(0, 0, haCenter);
  MyWorkbook.WriteVertAlignment(0, 0, vaCenter);

Word wrap

Text which is longer than the width of a cell can wrap into several lines by calling the method WriteWordwrap of the spreadsheet: 

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;

  // Example: activate wordwrap in cell A1
  MyWorksheet.WriteWordwrap(0, 0, true);

Merged cells

Like the Office applications, FPSpreadsheet supports also to feature of merging cells to a single large cell which is often used as a common header above simlar columns. Simply call MergeCells and pass a parameter to specify the cell range to be merged, either an Excel range string (such as A1:D5), or the first and last rows and columns: 

  MyWorksheet.MergeCells('A1:D5');
  // or: MyWorksheet.MergeCells(0, 0, 4, 3);  // first row, first column, last row, last column

The content and format displayed for a merged range is taken from the upper left corner of the range, cell A1 in above example. This cell is called the MergeBase in the library. Except for this corner cell, there must not be any other cells in the range. If there are their contents and format will be hidden.

In order to break up a merged range back up into individual cells, use the command Unmerge and pass any cell that is within the merged range: 

  MyWorksheet.UnmergeCells('B1');
  // or: MyWorksheet.UnmergeCells(0, 1);   // row, column of any cell within the range

Merged cells can be read from/written to all file formats except for sfCSV, sfExcel2 and sfExcel5 which do not support this feature natively.

The information which cells are merged is stored in an internal list. Unlike in earlier versions it is no longer possible to access the MergeBase from the cell directly. Use the following functions to extract information on merged cells: 

var
  cell, base: PCell;
  r1,c1,r2,c2: Cardinal;
...
  cell := MyWorksheet.FindCell('B1');
  if MyWorksheet.IsMerged(cell) then
  begin
    WriteLn('Cell B1 is merged.');

    MyWorksheet.FindMergedRange(cell, r1, c1, r2, c2);
    WriteLn('The merged range is ' + GetCellRangeString(r1, c1, r2, c2));

    base := MyWorksheet.FindMergeBase(cell);
    WriteLn('The merge base is cell ' + GetCellString(base^.Row, base^.Col));
  end;

Cell protection

This is described in a separate section below.


--Zoltanleo (talk) 16:50, 10 September 2018 (CEST) Все ниже описанное требует правки и приведения текста в соответствии с англоязычным оригиналом

Формулы

В FPSpreadsheet поддерживаются два вида формул: строковый и RPN. Строковый вид записываются также как и в офисных приложениях, например, "ROUND (A1 + B1)", а RPN формулы записываются в обратной польской нотации (Reverse Polish Notation (RPN)), например: A1, B1, Add, 0, ROUND

RPN формулы

Пример использования встроенной процедуры 

  // Write the formula E1 = ABS(A1)
  SetLength(MyRPNFormula, 2);
  MyRPNFormula[0].ElementKind := fekCell;
  MyRPNFormula[0].Col := 0;
  MyRPNFormula[0].Row := 0;
  MyRPNFormula[1].ElementKind := fekABS;
  MyWorksheet.WriteRPNFormula(0, 4, MyRPNFormula);

  // Write the formula F1 = ROUND(A1, 0)
  SetLength(MyRPNFormula, 3);
  MyRPNFormula[0].ElementKind := fekCell;
  MyRPNFormula[0].Col := 0;
  MyRPNFormula[0].Row := 0;
  MyRPNFormula[1].ElementKind := fekNum;
  MyRPNFormula[1].DoubleValue := 0.0;
  MyRPNFormula[2].ElementKind := fekROUND;
  MyWorksheet.WriteRPNFormula(0, 5, MyRPNFormula);

Встроенные процедуры

ABS - Возвращает абсолютное значение заданного числа. Принимает 1 аргумент. Пример: ABS (-1) = 1

ROUND - Округляет число до заданного числа десятичных знаков. Принимает 2 аргумента, сначало округляемое число, а затем количество десятичных знаков. Второй аргумент по умолчанию равен нулю и может быть отрицательным.

Примеры

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

Пример Excel 5

{
excel5demo.dpr

Demonstrates how to write an Excel 5.x file using the fpspreadsheet library

You can change the output format by changing the OUTPUT_FORMAT constant

AUTHORS: Felipe Monteiro de Carvalho
}
program excel5demo;

{$mode delphi}{$H+}

uses
  Classes, SysUtils, fpspreadsheet, fpsallformats, fpspreadsheet_pkg;

const OUTPUT_FORMAT = sfExcel5;

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyFormula: TsRPNFormula;
  MyDir: string;
begin
  // Initialization
  MyDir := ExtractFilePath(ParamStr(0));

  // Create the spreadsheet
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet');

  // Write some number cells
  MyWorksheet.WriteNumber(0, 0, 1.0);
  MyWorksheet.WriteNumber(0, 1, 2.0);
  MyWorksheet.WriteNumber(0, 2, 3.0);
  MyWorksheet.WriteNumber(0, 3, 4.0);

  // Write the formula E1 = A1 + B1
  // or, in RPN: A1, B1, +
  SetLength(MyFormula, 3);
  MyFormula[0].ElementKind:=fekCell; {A1}
  MyFormula[0].Col := 0;
  MyFormula[0].Row := 0;
  MyFormula[1].ElementKind:=fekCell; {B1}
  MyFormula[1].Col := 1;
  MyFormula[1].Row := 0;
  MyFormula[2].ElementKind:=fekAdd;;  {+}
  MyWorksheet.WriteRPNFormula(0, 4, MyFormula);

  // Creates a new worksheet
  MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet 2');

  // Write some string cells
  MyWorksheet.WriteUTF8Text(0, 0, 'First');
  MyWorksheet.WriteUTF8Text(0, 1, 'Second');
  MyWorksheet.WriteUTF8Text(0, 2, 'Third');
  MyWorksheet.WriteUTF8Text(0, 3, 'Fourth');

  // Save the spreadsheet to a file
  MyWorkbook.WriteToFile(MyDir + 'test' + STR_EXCEL_EXTENSION, OUTPUT_FORMAT);
  MyWorkbook.Free;
end.


Перебор всех Листов (Worksheets)

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  i: Integer;
begin
  // Here load MyWorkbook from a file or build it
 
  for i := 0 to MyWorkbook.GetWorksheetCount() - 1 do
  begin
    MyWorksheet := MyWorkbook.GetWorksheetByIndex(i);
    // Do something with MyWorksheet
  end;

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

Обратите внимание, что это только мета-код, не тестировал. 

program db5xls;
 
{$mode delphi}{$H+}
 
uses
  Classes, SysUtils, 
  // add database units
  fpspreadsheet, fpsallformats, fpspreadsheet_pkg;
 
const OUTPUT_FORMAT = sfExcel5;
 
var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
  MyDatabase: TSdfDataset;
  MyDir: string;
  i, j: Integer;
begin
  // Initialization
  MyDir := ExtractFilePath(ParamStr(0));
 
  // Open the database
  MyDatabase := TSdfDataset.Create;
  MyDatabase.Filename := 'test.dat';
  // Add table description here
  MyDatabase.Active := True;

  // Create the spreadsheet
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My Worksheet');
 
  // Write the field names
  for i := 0 to MyDatabase.Fields.Count - 1 do
    MyWorksheet.WriteUTF8Text(0, i, MyDatabase.Field[i].FieldName);

  // Write all cells to the worksheet
  MyDatabase.First;
  j := 0;
  while not MyDatabase.EOF do
  begin
    for i := 0 to MyDatabase.Fields.Count - 1 do
      MyWorksheet.WriteUTF8Text(j + 1, i, MyDatabase.Field[i].AsString);

    MyDatabase.Next;
    Inc(j);
  end;

  // Close the database
  MyDatabase.Active := False;
  MyDatabase.Free;

  // Save the spreadsheet to a file
  MyWorkbook.WriteToFile(MyDir + 'test' + STR_EXCEL_EXTENSION, OUTPUT_FORMAT);
  MyWorkbook.Free;
end.

Скачать

Subversion

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

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/fpspreadsheet fpspreadsheet

Текущий состояние

Текущее состояние поддерживаемых форматов:

Формат Поддержка нескольких листов Поддержка Unicode Чтение Запись Текст Число Строковая формула RPN формула
Excel 2.x Нет Нет** Работает Работает Работает Работает Не реализовано Работает
Excel 3.0 Нет Нет** Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано
Excel 4.0 Нет Нет** Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано
Excel 5.0 (Excel 5.0 and 95) Да Нет** Работает* Работает Работает Работает Не реализовано Работает
Excel 8.0 (Excel 97, 2000, XP and 2003) Да Да Работает* Работает Работает Работает Не реализовано Не реализовано
Microsoft OOXML Да Да Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано Не реализовано
OpenDocument Да Да Работает Работает Работает Работает Не реализовано Не реализовано

(*) Некоторые ячейки могут быть возвращены пустыми из-за отсутствия реализации некоторых числовых и строковых форматов. (**) В форматах, не поддерживающих Unicode, данные сохраняются в виде ISO 8859-1. Обратите внимание, что при чтении/записи FPSpreadsheet предлагает использовать UTF-8, но эти данные будут преобразованы в ISO при чтении или записи на диск. Будьте осторожны - символы, которые не укладываются в ISO Latin 1, будут потеряны в этих операциях.

Журнал изменений

Январь 2009

  • Реализована это кросс-платформенная поддержка для OLE файлов. Теперь файлы Excel 5.0 могут быть созданы в любой операционной системе.
  • Добавлена поддержка чтения файлов Excel 2.1

Февраль 2008

  • Initial commit to lazarus-ccr with write support for Excel 2.1, Excel 5.0 (Windows only) and experimental OOXML and OpenDocument

Лицензия

LGPL with static linking exception. This is the same license as is used in the Lazarus Component Library.

См. также

Поддержка и багрепорты

Рекомендованное место для обсуждения FPSpreadsheet и получения ответов на ваши вопросы это ветка форума Lazarus Forum.

Багрепорты должны быть отправленны в Lazarus/Free Pascal Bug Tracker; пожалуйста уточните что это "Lazarus-CCR" проект.

Внешние ссылки

--4yma 01:53, 13 April 2010 (CEST)

Retrieved from "http://wiki.freepascal.org/index.php?title=FPSpreadsheet/ru&oldid=119297"