Работа с ячейками
Установка значения ячейки
Установка значений
Чтобы задать значение ячейки через API, используйте метод setValue(). Передайте в него следующие параметры:
cells- (string) идентификатор(ы) ячейки(ек) или диапазон ячеекvalue- (string/number/array) значение для установки в ячейку(и)
// установка значения для одной ячейки
spreadsheet.setValue("A1",5);
// установка одинакового значения для диапазона ячеек
spreadsheet.setValue("A1:D1",5);
// установка одинакового значения для разных ячеек
spreadsheet.setValue("B6,A1:D1",5);
// установка значений из массива для ячеек в диапазоне поочерёдно
spreadsheet.setValue("A1:D1",[1,2,3]);
Обратите внимание, что метод устанавливает одинаковые (повторяющиеся) значения для указанных ячеек. Если вы хотите добавить разные значения в ячейки таблицы, используйте метод parse().
Получение значений
Вы также можете получить значение(я), установленное в ячейке(ях), передав идентификатор(ы) нужной(ых) ячейки(ек) или диапазон ячеек в метод getValue().
Метод возвращает значение(я) в виде строки, числа или массива:
// получение значения одной ячейки
var cellValue = spreadsheet.getValue("A2"); // "Ecuador"
// получение значений диапазона ячеек
var rangeValues = spreadsheet.getValue("A1:A3"); // -> ["Country","Ecuador","Belarus"]
// получение значений разных ячеек
var values = spreadsheet.getValue("A1,B1,C1:C3");
//-> ["Country", "Product", "Price", 6.68, 3.75]
Проверка данных в ячейках
Начиная с версии v4.3, вы можете применять проверку данных к ячейкам, добавляя выпадающие списки вариантов. Для этого используйте метод setValidation():
spreadsheet.setValidation("B10:B15", ["Apple", "Mango", "Avocado"]);
Выпадающий список ограничивает выбор пользователя. При вводе неожиданного значения в ячейку отображается сообщение Недопустимое значение.
Метод setValidation() также может удалять проверку с указанных ячеек. Подробнее.
Вставка гиперссылки в ячейку
Для вставки гиперссылки в ячейку используйте метод insertLink(). Метод также позволяет добавить текст, отображаемый с гиперссылкой:
// вставка ссылки в ячейку "A2"
spreadsheet.insertLink("A2", {
text:"DHX Spreadsheet", href: "https://dhtmlx.com/docs/products/dhtmlxSpreadsheet/"
});
Если нужно удалить ссылку из ячейки, передайте только идентификатор ячейки в метод:
// удаление ссылки из ячейки "A2"
spreadsheet.insertLink("A2");
Стилизация ячеек
Установка стилей
Вы можете применить стили к ячейке или диапазону ячеек с помощью метода setStyle(). Он принимает два параметра:
cells- (string) идентификатор(ы) ячейки(ек) или диапазон ячеекstyles- (object/array) стили для применения к ячейкам
// установка стиля дл я одной ячейки
spreadsheet.setStyle("A1", {background: "red"});
// установка одинакового стиля для диапазона ячеек
spreadsheet.setStyle("A1:D1", {color: "blue"});
// установка одинакового стиля для разных ячеек
spreadsheet.setStyle("B6,A1:D1", {color: "blue"});
// установка стилей из массива для ячеек в диапазоне поочерёдно
spreadsheet.setStyle("A1:D1", [{color: "blue"}, {color: "red"}]);
Метод устанавливает одинаковый стиль для указанных ячеек. Если вы хотите применить разные стили к ячейкам таблицы, используйте метод parse().
Получение стилей
Чтобы получить стили, применённые к ячейке(ям), используйте метод getStyle(). Передайте в него идентификатор(ы) ячейки(ек) или диапазон ячеек:
// получение стиля одной ячейки
var style = spreadsheet.getStyle("A1");
// -> {background: "#8DE9E1", color: "#03A9F4"}
// получение стилей диапазона ячеек
var rangeStyles = spreadsheet.getStyle("A1:D1"); // -> см. подробности
// получение стилей разных ячеек
var values = spreadsheet.getStyle("A1,B1,C1:C3");
Для нескольких ячеек метод возвращает массив объектов со стилями, применёнными к ячейке:
[
{background: "red", border: "solid 1px yellow", color: "blue"},
{background: "red", border: "solid 1px yellow", color: "blue"},
{background: "#C8FAF6", border: "solid 1px yellow", color: "#81C784"},
{background: "#9575CD", border: "solid 1px yellow", color: "#079D8F"}
]
Редактирование ячейки
Включение редактора ячейки
Вы можете добавить поле ввода в ячейку, вызвав метод startEdit():
spreadsheet.startEdit();
Метод принимает два необязательных параметра:
cell- (string) необязательный, идентификатор ячейкиvalue- (string) необязательный, значение ячейки
Если идентификатор ячейки не передан, поле ввода добавляется в текущую выбранную ячейку.
Отключение редактора ячейки
Чтобы завершить редактирование ячейки, используйте метод endEdit(), который закрывает редактор и сохраняет введённое значение.
spreadsheet.endEdit();
Блокировка ячеек
Блокировка ячеек
Вы можете программно заблокировать ячейку или несколько ячеек, чтобы сделать их доступными для пользователей только для чтения. Для этого используйте метод lock(). Метод принимает в качестве параметра идентификатор(ы) ячейки(ек) или диапазон ячеек для блокировки.
// блокировка ячейки
spreadsheet.lock("A1");
// блокировка диапазона ячеек
spreadsheet.lock("A1:C1");
// блокировка указанных ячеек
spreadsheet.lock("A1,B5,B7,D4:D6");
Связанный пример: Spreadsheet. Заблокированные ячейки
Разблокировка ячеек
Чтобы разблокировать заблокированную(ые) ячейку(и), используйте метод unlock(). Передайте в него идентификатор(ы) ячейки(ек) или диапазон, содержащий заблокированные ячейки, в качестве параметра:
// разблокировка ячейки
spreadsheet.unlock("A1");
// разблокировка диапазона ячеек
spreadsheet.unlock("A1:C1");
// разблокировка указанных ячеек
spreadsheet.unlock("A1,B5,B7,D4:D6");
Проверка блокировки ячейки
Чтобы проверить, заблокирована ли ячейка или несколько ячеек, используйте метод isLocked() и передайте в него идентификатор(ы) ячейки(ек) или диапазон ячеек:
// проверка блокировки ячейки
var cellLocked = spreadsheet.isLocked("A1");
// проверка блокировки нескольких ячеек
var rangeLocked = spreadsheet.isLocked("A1:C1");
// проверка блокировки разрозненных ячеек
var cellsLocked = spreadsheet.isLocked("A1,B5,B7,D4:D6");
Метод возвращает true или false в зависимости от состояния ячейки. Если проверяется несколько ячеек одновременно, метод возвращает true, если среди указанных ячеек есть хотя бы одна заблокированная.
Сохранение заблокированного состояния
Заблокированное состояние ячеек является частью данных таблицы, поэтому оно не теряется при сохранении и восстановлении:
- метод serialize() включает свойство
lockedв сериализованные объекты ячеек, даже если у заблокированной ячейки нет значения - экспорт в файл Excel сохраняет заблокированное состояние, а импорт такого файла восстанавливает его
Заблокированное состояние также можно задать прямо в наборе данных через свойство locked ячейки. Подробнее.
Объединение ячеек
Объединение ячеек
Вы можете объединить две или более ячеек в одну, передав диапазон ячеек, которые нужно объединить, в метод mergeCells():
// объединение ячеек A6, A7 и A8
spreadsheet.mergeCells("A6:A8");
// объединение ячеек B2, C2 и D2
spreadsheet.mergeCells("B2:D2");
Разъединение ячеек
Вы также можете разъединить объединённые ячейки с помощью метода mergeCells(). В дополнение к диапазону ячеек передайте true в качестве второго параметра, чтобы разъединить указанные ячейки:
// разъединение ячеек B2, C2 и D2
spreadsheet.mergeCells("B2:D2", true);
Выделение ячеек
Выделение ячеек
Spreadsheet позволяет задать выделение ячеек с помощью API объекта Selection.
Вы можете выделить ячейку(и), передав её/их идентификатор(ы) в метод setSelectedCell():
// выделение ячейки
spreadsheet.selection.setSelectedCell("B5");
// выделение диапазона ячеек
spreadsheet.selection.setSelectedCell("B1:B5");
// выделение разрозненных ячеек
spreadsheet.selection.setSelectedCell("B7,B3,D4,D6,E4:E8");
Также можно получить идентификатор(ы) выбранной(ых) ячейки(ек) через метод getSelectedCell():
const selected = spreadsheet.selection.getSelectedCell(); // -> "B7,B3,D4,D6,E4:E8"
Снятие выделения с ячеек
Чтобы снять выделение с ячейки(ек), передайте её/их идентификатор(ы) в метод removeSelectedCell():
// устанавливает выделение
spreadsheet.selection.setSelectedCell("B7,B3,D4,D6,E4:E8");
// снимает выделение
spreadsheet.selection.removeSelectedCell("B7,D4,E5:E7");
const selected = spreadsheet.selection.getSelectedCell();
console.log(selected); // -> "B3,D6,E4,E8"
Связанный пример: Spreadsheet. Снятие выделения
Установка фокуса на ячейке
Объект Selection позволяет устанавливать фокус на ячейке таблицы и получать идентификатор ячейки в фокусе. Для этого используйте соответствующие методы:
// передайте идентификатор ячейки для установки фокуса
spreadsheet.selection.setFocusedCell("D4");
// получение ячейки в фокусе
var focused = spreadsheet.selection.getFocusedCell(); // -> "D4"