TsWorksheetGrid/ru

From Free Pascal wiki

English (en) русский (ru)


-- Zoltanleo 15:36, 21 September 2018 (CEST) Ввиду сложности дословного перевода текста с английского на русский слова, требующиеся по смыслу, но отсутствующие в английской версии, указаны в квадратных скобках.



Обзор

TsWorksheetGrid - это специализированный компонент сетки, который взаимодействует с TsWorksheet из библиотеки FPSpreadsheet и отображает файлы данных электронных таблиц, как обычный TStringGrid.

fpsgrid.png

Интерфейс программирования

TsWorksheetGrid наследуется от TCustomGrid и ведет себя как стандартный TStringGrid. Основное различие заключается в том, что сама сетка не хранит данные, но данные хранятся в TWorksheet из FPSpreadsheet. Доступ к рабочему листу можно получить с помощью свойства Worksheet сетки. Аналогично, Workbook позволяет получить доступ ко всей рабочей книге, к которой принадлежит рабочий лист.

Для доступа к ячейкам, их значениям и атрибутам доступно множество свойств, как и в случае StringGrid, например, запись значения ячейки с помощью Grid.Cells[ACol, ARow] := 1.234. Ячейки идентифицируются в этих свойствах с помощью индексов столбцов и строк ячейки. Обратите внимание, что индексы передаются в порядке "первый столбец/последняя строка" и включают индексы, занятые фиксированными ячейками, т.е. верхняя/левая ячейка данных имеет индексы col=1 и row=1. Это отличается от fpspreadsheat, где индексы всегда начинаются с 0 и передаются в функции в обратном порядке "первая строка/последний столбец".

Доступ к значениям ячеек

Свойство Cells[ACol, ARow] обеспечивает доступ к данным в ячейке, заданной его индексами столбцов и строк. Это похоже на TStringGrid. В отличие от TStringGrid, который работает только со строками, TsWorksheetGrid, принимает числа, даты, булевы типы и формулы. По этой причине тип данных Cells является variant.

Запись значений ячеек

Используйте этот код для записи данных в ячейку в TsWorksheetGrid с именем Grid для простоты:

  // Записываем строку
  Grid.Cells[1, 1] := 'Это - строка';  
  // Записываем строку со встроенными кодами HTML
  Grid.Cells[1, 2] := 'Химическая формула <b>воды</b>: H<sub>2</sub>O';
  // Записываем число
  Grid.Cells[1, 3] := 1.2345;
  // Записываем дату
  Grid.Cells[1, 4] := EncodeDate(2016, 1, 18);
  // Записываем формулу
  Grid.Cells[1, 5] := '=A3+2';
  // и т.д.
Note-icon.png

Примечание: Текст, назначенный ячейке, может содержать встроенные простые HTML-коды для изменения шрифта для определенных слов или символов.

Чтение значений ячеек

Точно так же значения ячеек можно считывать в переменные выделенных типов:

var
  str: String;
  x: Double;
begin
  str := Grid.Cells[1, 1];  // Переменная "str" будет содержать значение "Это  - строка",
  x := Grid.Cells[1, 2];    // x будет 1.2345
  str := Grid.Cells[1, 2];  // Хотя ячейка содержит число, она преобразуется в строку "1.2345"
end;

Сравнение значений ячеек

Так как свойство Cells является [типом] вариант, сравнение строки со строкой немного сложнее. Используйте функцию преобразования строк в вариант VarToStr(), предоставляемую модулем variant.

  // Это простое сравнение не удастся:
  // if Grid.Cells[1,1] = 'Это - строка' then ...

  // Используйте вместо этого:
  if VarToStr(Grid.Cells[1,1]) = 'Это - строка' then ...

Численные значения часто можно сравнивать без явного преобразования:

  if Grid.Cells[1,2] = 1.2345 then ...

Формулы в ячейках

Поскольку TsWorksheetGreed работает поверх электронной таблицы, могут быть вводиться все формулы, поддерживаемые FPSpreadsheet. См. этот документ для полного списка поддерживаемых формул.

Строка формулы должна начинаться с символа «=». Ссылки на ячейки должны следовать за символом "A1" в обозначении Excel, то есть индексом столбца должны быть символы «A» .. «Z», а индекс строки - целое число, начинающее [нумерацию] с 1. Если имеется более 26 столбцов, можно использовать два (или три) символа.

В случае диапазона ячеек координаты верхних и нижних правых углов прямоугольника ячейки должны быть разделены цветом, напр., '=SUM(A1:C10)' вычисляет сумму значений в прямоугольнике ячейки, проходящих между A1 и C10.

Формулы, относящиеся к ячейкам других листов, можно использовать, следуя синтаксису Excel: укажите имя листа, за которым следует символ "!" перед адресом ячейки, напр., '=Sheet3!A1' или '=SUM(Sheet3:Sheet4!A1:C10)'.

Обратите внимание, что формулы по умолчанию автоматически не вычисляются. Чтобы активировать автоматический расчет формул, установите для свойства сетки AutoCalc значение true или установите опцию рабочей книги boAutoCalc, используемую сеткой. "Автоматический расчет" означает, что все формулы на всем листе пересчитываются всякий раз, когда изменяется содержимое любой ячейки. Поэтому не требуется, чтобы ячейки, адрессованные

формулой, имели значения при ее вводе.
// Включаем автоматический расчет формул
Grid.AutoCalc := true;        
// or: Grid.Workbook.Options := Grid.Workbook.Options + [boAutoCalc];

// Вводим ячейки
Grid.Cells[1,1] := 1;         // это - ячейка A1
Grid.Cells[1,2] := 2;         // это - ячейка A2

// Вводим формулу
Grid.Cells[1,3] := '=A1+A2';  // Вычисляем сумму значений в A1 и A2 

// Другая формула в ячейке B3
Grid.Cells[2,3] := '=B1*B2';  // Не имеет значения, что ячейки B1 и B2 еще не существуют.

// Вводим ячейки, необходимые по формуле
Grid.Cells[2,1] := '=A3';     // Используем результат предыдущей формулы
Grid.Cells[2,2] := 10;

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

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

  • BackgroundColor[ACol, ARow: Integer]: TsColor - задает цвет фона ячейки. TsColor - целое число, содержащее [значение] rgb-составляющей цвета. Модуль fpsTypes предоставляет список констант для большого количества предопределенных цветов; могут использоваться цвета, определенные стандартным модулем Graphics (за исключением значений цвета системы).
  • CellBorder[ACol, ARow: Integer]: TsCellBorders - указывает, какие края ячеек будут обозначены рамкой. Используйте установленные значения [cbEast, cbWest, cbNorth, cbSouth] для правого, левого, верхнего и нижнего краев соответственно.
  • CellBorderStyle[ACol, ARow: Integer; ABorder: TsCellBorder]: TsCellBorderStyle - указывает стиль, который будет использоваться для линии границы ячейки, указанной в параметре ABorder. TsCellBorderStyle - это запись, содержащая информацию о стиле линии и цвете линии. Обратите внимание, что набор CellBorder[ACol, ARow] должен содержать элемент ABorder, чтобы активировать эту границу.
  • CellFont[ACol, ARow: Integer]: TFont - описывает шрифт, используемый при прорисовке текста ячейки. Элементы шрифта могут быть изменены отдельно этими свойствами:
    • CellFontColor[ACol, ARow: Integer]: TsColor - определяет цвет текста. См. "BackgroundColor" выше для [получения] описания типа TsColor.
    • CellFontName[ACol, ARow: Integer]: String - это имя шрифта.
    • CellFontSize[ACol, ARow: Integer]: Single - это размер точки шрифта (1 pt = 1/72 дюйма).
    • CellFontStyle[ACol, ARow: Integer]: TsFontStyles - представляет собой набор, содержащий элементы для использования жирного шрифта, курсива, подчеркнутого или зачеркнутого шрифтов.
  • HorAlignment[ACol, ARow: Integer]: TsHorAlignment - позволяет изменять горизонтальное выравнивание текста ячейки (haLeft, haCenter, или haRight).
  • NumberFormat[ACol, ARow: Integer]: String - представляет собой строку формата номера, совместимую с Excel, например. '0.000' для отображения числового значения с 3 десятичными знаками. Формат чисел важен, если цифры должны отображаться как значения даты или времени.
  • TextRotation[ACol, ARow: Integer]: TsTextRotation - должен использоваться для поворота текста внутри ячейки. Тип TsTextRotation обеспечивает [ориентацию] trHorizontal [(по горизонтали, по умолчанию)], rt90DegreeClockwiseRotation [(на 90° по часовой стрелке)], rt90DegreeCounterClockwiseRotation [(на 90° против часовой стрелки)] и rtStacked [(символов, располагающихся друг над другом, подобно японским иероглифам)].
  • VertAlignment[ACol, ARow: Integer]: TsVertAlignment - позволяет изменять горизонтальное выравнивание текста ячейки (vaTop [(по верхнему краю)], vaCenter [(по центру)] или vaBottom [(по нижнему краю)]).
  • Wordwrap[ACol, ARow: Integer]: Boolean - активирует автоперенос строки текста, длина которой больше ширины ячейки (или высота, если используется повернутый текст).

Эти свойства также могут быть доступны для диапазона ячеек, указанных индексами левого столбца, верхней строки, правого столбца и нижней строки блока ячейки. Поскольку эти свойства связаны с несколькими ячейками, они пишутся во множественном числе (с окончанием "s"):

  • BackgroundColors[ALeft, ATop, ARight, ABottom: Integer]: TsColor
  • CellBorders[ALeft, ATop, ARight, ABottom: Integer]: TsCellBorders
  • CellBorderStyles[ALeft, ATop, ARight, ABottom: Integer; ABorder: TsCellBorder]: TsCellBorderStyle
  • CellFonts[ALeft, ATop, ARight, ABottom: Integer]: TFont
  • CellFontColors[ALeft, ATop, ARight, ABottom: Integer]: TsColor
  • CellFontNames[ALeft, ATop, ARight, ABottom: Integer]: String
  • CellFontStyles[ALeft, ATop, ARight, ABottom: Integer]: TsFontStyles
  • CellFontSizes[ALeft, ATop, ARight, ABottom: Integer]: Single
  • HorAlignments[ALeft, ATop, ARight, ABottom: Integer]: TsHorAlignment
  • NumberFormats[ALeft, ATop, ARight, ABottom: Integer]: String
  • TextRotations[ALeft, ATop, ARight, ABottom: Integer]: TsTextRotation
  • VertAlignments[ALeft, ATop, ARight, ABottom: Integer]: TsVertAlignment
  • Wordwraps[ALeft, ATop, ARight, ABottom: Integer]: Boolean

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


Примеры

Этот пример добавляет формулу для сегодняшней даты в ячейку A1, форматирует ячейки для отображения числа в качестве даты и выбирает белый шрифт курсивом на светло-сером фоне. Вокруг ячейки пунктиром рисуется красная рамка.

const
  RED_DOTTED_BORDER: TsBorderStyle = (LineStyle: lsDotted; Color: scRed);

// Задаем содержимое ячейки
Grid.Cells[1,1] := '=TODAY()';

// Форматируем [содержимое] как дату
Grid.Numberformat[1,1] := 'yyyy/mm/dd';

// Выбираем цвет фона [сетки]
Grid.BackgroundColor[1,1] := scSilver;

// Выбираем [цвет и стиль] шрифта 
Grid.FontColor[1,1] := scWhite;
Grid.FontStyle[1,1] := [fssItalic];

// Прорисовываем границы ячейки 
Grid.Border[1,1] := [cbEast, cbWest, cbNorth, cbSouth];

// Определяем, как будут нарисованы границы ячеек
Grid.BorderStyle[1,1, cbEast] := RED_DOTTED_BORDER;
Grid.BorderStyle[1,1, cbWest] := RED_DOTTED_BORDER;
Grid.BorderStyle[1,1, cbNorth] := RED_DOTTED_BORDER;
Grid.BorderStyle[1,1, cbSouth] := RED_DOTTED_BORDER;

[Процесс] определения границ ячеек для более крупного блока ячеек с помощью этих свойств [вручную] будет довольно громоздким, потому что могут использоваться различные стили для внутренних, внутренних и внутренних ячеек. Чтобы решить эту задачу проще, сетка предоставляет метод ShowCellBorders, который получает координаты блока ячейки и стили левой, верхней, правой, нижней внешней и горизонтальной и вертикальной внутренних линий границы. Используйте константу NO_CELL_BORDER, при которой граница не должна быть выделена в определенном месте:

const
  THICK_CELL_BORDER: TsCellBorderStyle = (LineStyle: lsThick; Color: clBlack);
  DOTTED_CELL_BORDER: TsCellBorderStyle = (LineStyle: lsDotted; Color: clSilver);

// Нарисуем толстую рамку вокруг блока A1:C3, без внутренней границы
Grid.ShowCellBorders(1,1, 3,3,      // левая, верхняя, правая, нижняя координаты блока ячеек
  THICK_CELL_BORDER, THICK_CELL_BORDER, THICK_CELL_BORDER, THICK_CELL_BORDER,   // стили внешней границы
  NO_CELL_BORDER, NO_CELL_BORDER                                                // стили внутренней границы
);

// Нарисуйте толстую рамку вокруг блока A1: C3, серые горизонтальные внутренние линии пунктиром
Grid.SetCellBorders(1,1, 3,3, 
  THICK_CELL_BORDER, THICK_CELL_BORDER, THICK_CELL_BORDER, THICK_CELL_BORDER, 
  DOTTED_CELL_BORDER, NO_CELL_BORDER
);

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

Комментарии могут быть добавлены в каждую ячейку с использованием свойства сетки CellComment[ACol, ARow: Integer]: String. Ячейки, содержащие комментарий, отмечены красным треугольником в верхнем правом углу ячейки. Если мышь перемещается в ячейку с комментарием, появляется всплывающее окно для отображения комментария.

Note-icon.png

Примечание: Чтобы всплывающее окно появилось, необходимо добавить флаг goCellHints в свойство Options сетки, а стандартное свойство сетки ShowHint должно [иметь значение] true. В противном случае всплывающие окна не будут отображаться.

Пример:

Grid.Cells[1,1] := '=pi()';
Grid.CellComment[1,1] := 'Число pi необходимо для вычисления площади и окружности круга.';

Гиперссылки в ячейках

Ячейки с прикрепленными гиперссылками позволяют пользователю перемещаться по другим ячейкам или другим документам [простым] нажатием на ячейку. Доступ к гиперссылкам можно получить с помощью свойства Hyperlink[ACol, ARow: Integer]: String. Строка гиперссылки содержит цель гиперссылки и необязательный текст всплывающей подсказки, который разделяется символом штриха ("|"). Внутренние цели уже обрабатываются сеткой, но для навигации у гиперссылки должен быть определен обработчик событий для OnClickHyperlink. Чтобы отличить нормальные клики по ячейкам от кликов по гиперссылкам, кнопка мыши должна удерживаться доли секунды до того, как будет [выполнен переход по] гиперссылке.

Пример:

// Пример добавления внешней гиперссылки
Grid.Cells[1,1] := 'Lazarus';
Grid.Hyperlink[1,1] := 'www.lazarus-ide.org|Открыть веб-сайт Lazarus';

// Пример добавления внутренней гиперссылки
Grid.Cells[2,2] := 'Итого';
Grid.Hyperlink[2,2] := '#Sheet2!B10|Перейдите к итогам, начиная с ячейки B10 листа 2';

// Пример для обработчика событий OnClickHyperlink, необходимого для внешних гиперссылок
uses
  ..., uriparser;

procedure TForm1.GridOnClickHyperlink(Sender: TObject; const AHyperlink: TsHyperlink);
begin
var
  uri: TUri;
begin
  uri := ParseURI(AHyperlink.Target);
  case Lowercase(uri.Protocol) of
    'http', 'https', 'ftp', 'mailto', 'file':
      OpenUrl(AHyperlink.Target);
    else
      ShowMessage('Гиперссылка ' + AHyperlink.Target + ' нажата');
  end;
end;
Note-icon.png

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

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

Прямоугольная группа ячеек может быть объединена в один блок. Содержимое верхней/левой ячейки этого блока отображается во всех объединенных ячейках, содержимое других ячеек игнорируется.

Используйте метод MergeCells для выполнения этой операции. В качестве параметров требуется объединить левую, верхнюю, правую и нижнюю координаты диапазона ячеек. Они также могут быть объединены в запись TRect. Метод Unmerge снова разделяет ранее объединенный блок на отдельные ячейки, здесь достаточно координат одной ячейки из объединенного диапазона.

  // Пример слияния
  Grid.MergeCells(1,1, 3,1);          // Объединяем первые 3 ячейки первой строки
  Grid.Cells[1,1] := 'Итого';         // Записываем текст "Итого" по 3 ячейкам
  Grid.HorAlignment[1,1] := haCenter; // и центрируем его

  // Пример разделения
  Grid.UnmergeCells(1,1);             // Разделяем объединенный блок (1,1..3,1)

Ширина столбцов и высота строк

Column widths and row heights can be changed for all cells by setting the DefaultColWidth and DefaultRowHeight. This works also in design mode. In addition, the widths and heights of particular columns and rows can be modified by the properties ColWidths[ACol] and RowHeights[ARow]. These values must be given in pixels.

Ширину столбцов и высоту строк можно изменить для всех ячеек, определив [свойства] DefaultColWidth и DefaultRowHeight. Это работает также в режиме разработки. Кроме того, ширина и высота отдельных столбцов и строк могут быть изменены свойствами ColWidths[ACol] и RowHeights[ARow]. Эти значения должны указываться в пикселях.

  Grid.DefaultColWidth := 80;  // Это ширина всех столбцов, 
  Grid.ColWidths[10] := 10;    // исключая столбец #10, ширина которого составляет всего 10 пикселей.

  Grid.DefaultRowHeight := 20; // Все строки имеют высоту 20 пикселей,
  Grid.RowHeights[2] := 4;     // Строка #2 служит в качестве разделителя и имеет высоту всего 4 пиксела.

Новые свойства сетки

В дополнение к свойствам, унаследованным от его предков TCustomDrawGrid и TCustomGrid, TsWorksheetGrid вводит следующие новые published-свойства:

  • AllowDragAndDrop (boolean): если эта опция активна, ячейки можно перетащить в новое место. Переместите курсор мыши на границу ячеек, которые нужно перетащить, пока курсор мыши не станет четырехсторонней стрелкой, а затем начинайте перетаскивание. Если перетаскиваемая ячейка ссылается на формулу, формула НЕ обновляется - это поведение отличается от Excel, но согласуется с Open/LibreOffice Calc.
  • AutoCalc (boolean): формулы в сетке автоматически пересчитываются при изменении содержимого ячейки.
  • AutoExpand (set of aeData, aeNavigation, aeDefault):
    • Если опция aeData содержится в наборе AutoExpand, тогда сетка автоматически расширяется, если ячейки записываются за пределами предопределенного диапазона.
    • Если AutoExpand содержит параметр aeNavigation, тогда пользователь может перемещаться за пределами предопределенного диапазона ячеек; новые строки и столбцы автоматически добавляются в сетку (но не к основному листу). Если файл загружен в сетку, то размеры сетки автоматически расширяются до диапазона, необходимого для рабочего листа.
    • Опция aeDefault вступает в игру, если сетка меньше значений по умолчанию DEFAULT_COL_COUNT и DEFAULT_ROW_COUNT. Если этот параметр включен, сетка автоматически расширяется до этого размера по умолчанию [(с добавлением "недостающих" столбцов и строк)]. С другой стороны, если в сетке должно содержаться только определенное количество строк и столбцов, опция aeDefault должна быть удалена до установки [свойств] RowCount/ColCount.
  • EditorLineMode определяет, поддерживает ли редактор ячейки сетки только одиночные строки (elmSingleLine) или несколько строк (elmMultiLine). В последнем случае вы можете нажать CTRL + ENTER, чтобы начать новую строку во время редактирования ячейки.
  • FrozenBorderPen: если сетка имеет замороженные панели (см. FrozenCols и FrozenRows), разделительная линия вытягивает край последней замороженной строки и столбца , Свойство FrozenBorderPen определяет способ рисования этой строки. Установите [значение свойства] FrozenBorderPen.Style = psClear, чтобы скрыть эти линии.
  • FrozenCols и FrozenRows (integer): определяет количество НЕ прокручиваемых столбцов(строк) слева(сверху) сетки. Технически это настраиваемые фиксированные столбцы (строки) предка. Обратите внимание, что пользователь не может перемещаться или редактировать ячейки в этом диапазоне.
  • ReadFormulas (boolean): считывает формулы из входных файлов. Так как fpspreadsheet не поддерживает все формулы, доступные в приложениях электронной таблицы Office, есть вероятность, что при чтении файла может произойти сбой из-за формул; в этом случае чтение формул может быть отключено.
  • SelectionPen (TPen): определяет, как окрашивается граница выбранной ячейки. По умолчанию выбранная ячейка выделена черной линией шириной 3 пикселя.
  • ShowGridLines (boolean): позволяет отключить линии сетки
  • ShowHeaders (boolean): может использоваться для отключения заголовков столбцов и строк ('A', 'B', 'C', ..., '1', '2', '3'). Свойство DisplayFixedColRow имеет тот же эффект, но теперь устарело.
  • TextOverflow (boolean): если это свойство включено, то длинному текстовому контенту разрешается распространяться на соседние ячейки, если они пусты. Обратите внимание, что ячейки числовых данных округлены так, что ячейка не переполняется.
  • WorkbookSource (TsWorkbookSource): ссылки на источник рабочей книги, которые предоставляют данные. Если [ссылки] пустые, сетка использует внутренний источник рабочей книги.

События

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

Рекомендуемые значения свойств

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

  • AutoAdvance = aaDown: клавиша ENTER переводит [фокус] с выбранной ячейки в следующую нижнюю ячейку
  • AutoCalc = true: автоматическое вычисление формул
  • AutoEdit = true: для редактирования ячейки просто начинайте печатать. Кроме того, вы можете начать редактирование, нажав F2
  • AutoExpand = [aeData, aeNavigation, aeDefault]: не ограничивайте использование сетки предопределенными размерами сетки для пользовательского интерфейса, подобного Excel
  • EditorLineMode = elmMultiLine: активируйте редактор ячейки, поддерживающий многострочность во время редактирования
  • MouseWheelOption = mwGrid: колесико мыши прокручивает сетку, а не выбранную ячейку
  • Options: добавьте эти флаги в стандартные параметры, унаследованные от TCustomGrid:
    • goColSizing: пользователь может изменить ширину столбца, перетащив вертикальную разделительную линию между двумя ячейками заголовка столбца
    • goRowSizing: пользователь может изменить высоту строки, перетащив горизонтальную разделительную линию между двумя ячейками заголовка строки
    • goDblClickAutosize: двойной щелчок на разделительной линии между двумя ячейками заголовка столбца или строки изменяет ширину столбца или высоту строки до оптимального значения
    • goEditing: помещает сетку в режим редактирования (так же, как [и] AutoEdit)
    • goThumbTracking: немедленная прокрутка сетки, когда полоса прокрутки перетаскивается мышью (если эта опция отключена, прокрутка происходит в тот момент, когда кнопка мыши отпускается)
  • TextOverflow = true: разрешить длинный поток текста ячейки в пустые соседние ячейки

Смотри также