Компонент электронной таблицы для Angular | ng-hub-ui-spreadsheet

Редактируемая таблица для Angular с клавиатурой Excel, прямоугольным выделением, буфером обмена, работающим с Excel в обе стороны, закреплёнными областями и объединёнными ячейками. MIT, доступная, без платного тарифа.

Справочник API

Вот полный контракт spreadsheet: всё, что можно привязать, прослушать, спроецировать и тематизировать, собрано в одном месте. Подключите то, что нужно, и оформите так, как хотите — это standalone и дружит с сигналами.

Входные свойства

Настройте spreadsheet с помощью 55 входных свойств. Привязывайте их, как любой @Input в Angular.

ИмяТипПо умолчаниюОписание
rowsОбязательноreadonly TRow[]—Строки в том виде, в каком они у вас хранятся. Лист никогда в них не пишет.
columnsОбязательноreadonly HubSpreadsheetColumn<TRow>[]—Что показывает и что допускает каждый столбец.
rowKeyОбязательно(row: TRow) => string—Устойчивое имя строки, чтобы состояние сохранения сопровождало свою строку и после перезагрузки.
errorsRecord<string, string>{}Сообщение проверки для каждой ячейки, с ключами как у `states`. Принадлежит хосту, поскольку проверка — дело того, кто знает, что означают данные. Ячейка обводится красным, а сообщение открывается во всплывающей подсказке при наведении или фокусе с клавиатуры.
invalidDraftsRecord<string, string>{}Двусторонний. Текст, который читатель оставил в ячейке, хотя это не значение, которое столбец может хранить, с тем же ключом, что и states. Ячейка продолжает его показывать, в рамке и с сообщением, что он не сохранён; повторное открытие ячейки возвращает его для исправления, Escape отказывается от него, а запись поверх ячейки или удаление её строки или столбца убирает его. Читайте его, чтобы не сохранить молча старое значение.
statesRecord<string, HubSpreadsheetCellState>{}Состояние сохранения для каждой ячейки; ключ — ключ строки и псевдоним столбца, соединённые символом табуляции.
decimalMark',' | '.'','Символ, которым этот читатель вводит десятичные дроби. Учитывается, только если вставленное значение не содержало сырого числа.
emptyTextstring''Что показывает пустой лист.
pageSizenumber10На сколько строк перемещают курсор Page Up и Page Down.
readonlybooleanfalseОтключает все редакторы независимо от настроек отдельных ячеек.
frozenColumnsnumber0Сколько столбцов остаются закреплёнными у начального края; считается так же, как Excel закрепляет области.
frozenRowsnumber0Сколько строк остаются закреплёнными под заголовком.
spansreadonly HubGridSpan[][]Объединённые блоки, каждый из которых задаётся верхним левым углом и размером.
disjointSelectionbooleantrueДобавляет ли клик с Ctrl (Cmd на Mac) второй блок к выделению вместо того, чтобы начать новое. Включено: так делает табличный редактор, и жест всё равно был свободен — обычный клик уже выделяет, а Ctrl ничего не говорил. Каждый блок отмечен, Delete очищает все, а любой обычный клик или стрелка начинают выделение заново. Копирование происходит только когда блоки складываются в таблицу, иначе оно отклоняется; маркер заполнения исчезает, пока выбрано больше одного блока — заполнение продолжает один блок, и какой из нескольких, ответа нет.
fillHandlebooleanfalseWhether the sheet offers the fill handle at the corner of the selection. Он же включает Ctrl+D (Cmd+D на Mac) для заполнения вниз.
canUndobooleanfalseДоступна ли отмена. Лист лишь спрашивает; историю хранит владелец.
canRedobooleanfalseДоступен ли повтор.
resizableColumnsbooleanfalseМожет ли читатель перетащить задний край столбца, чтобы расширить или сузить его.
reorderableColumnsbooleanfalseМожет ли читатель перетащить заголовок, чтобы переместить столбец в другое место.
reorderableRowsbooleanfalseМожет ли читатель перетащить строку, чтобы поместить её в другое место. С клавиатуры Alt+Shift со стрелкой вверх или вниз сдвигает строку курсора на одну позицию, а новая позиция зачитывается вслух.
rowHandleLabelstring''Доступное имя маркера перетаскивания строки.
columnWidthsRecord<string, number>{}Ширина каждого столбца в пикселях, ключ — псевдоним. Двусторонняя привязка: лист записывает значение по мере перетаскивания, а вы можете его сохранить.
minColumnWidthnumber48Минимальная ширина, до которой можно сузить столбец перетаскиванием.
virtualbooleanfalseРисует только строки, попадающие в окно просмотра, и резервирует высоту остальных — для листа в тысячи строк. По умолчанию выключено, и за это есть плата: строк вне видимости нет в документе, поэтому поиск браузера и печать достают лишь нарисованное, а строки должны быть одной высоты. Включение также задаёт листу высоту 24rem: растущий свободно, он равен своему содержимому, и виртуализировать нечего.
rowHeightnumber0Высота строки при виртуализации, в пикселях. Ноль измеряет первую нарисованную строку — это верно, пока строки одинаковы. Укажите её для листа, собираемого скрытым: ни разу не размеченная строка измеряется нулём, а окно, посчитанное от нуля, — это весь лист.
formulasbooleanfalseСчитается ли формулой ячейка, значение которой начинается с =. Выключено, пока не попросят: текстовый столбец вполне может хранить =1+1 как то, что кто-то написал. Формула может обратиться к столбцу по алиасу — =[units] * [price], =SUM([total:]) — и после переноса столбца или переписанного заголовка она значит то же самое, либо по координате, как пишет табличный редактор — =ROUND(SUM(E1:E4), 2) —, а координата говорит, где столбец был, а не какой он; rewriteRowFormulas() переносит такие вместе с листом, а ссылка на удалённое становится #REF!, а не читает втихую соседний. Двоеточие читает весь столбец, исключая спрашивающую ячейку; любой другой круг показывается как #CYCLE!, а не преследуется.
mergeablebooleanfalseМожет ли читатель объединять ячейки и разделять их — предлагается в контекстном меню, так что нужен и contextMenu. Выключено, пока не попросят, как любое изменение структуры.
editOn'click' | 'double-click''double-click'Что открывает редактор указателем. По умолчанию двойной щелчок — соглашение таблиц: щелчок выбирает ячейку и оставляет её значение в покое, первый набранный символ открывает редактор и попадает в него, а ячейка со списком или датой показывает значок, открывающий её одним щелчком. Значение click открывает с первого щелчка — для листа, который существует, чтобы в нём печатали. В обоих случаях редактор открывается при отпускании и только если указатель не двигался, поэтому выделение диапазона протягиванием работает по-прежнему.
expansionTemplateRef<HubSpreadsheetExpansionContext<TRow>> | nullnullШаблон, нарисованный под открытой строкой, с тем, что строка хранит за своими числами.
expandedRowstring | nullnullДвусторонний. Какая строка открыта, по её ключу; по одной строке за раз.
expandTogglebooleanfalseРисует маленькую кнопку по краям каждой строки, открывающей деталь, чтобы читатель открывал её без кнопки от владельца.
expandToggleLabelstring''Доступное имя этой кнопки; лист не ведёт словаря.
rowLevel(row: TRow) => number | undefined() => 0Как глубоко строка сидит в структуре: 1 — внутри одного свёртывания, 2 — внутри двух, 0 или ничего — вне любого.
collapsedRowsreadonly string[][]Двустороннее. Какие группы строк свёрнуты, по id группы.
collapsedColumnsreadonly string[][]Двустороннее. Какие группы столбцов свёрнуты, по id группы.
rowToggleLabelstring''Доступное имя кнопки группы строк.
columnToggleLabelstring''Доступное имя кнопки группы столбцов.
direction'auto' | 'ltr' | 'rtl''auto'В какую сторону идёт лист. auto следует за страницей — лист внутри статьи справа налево читается как статья, потому что dir наследуется —, а ltr и rtl задают направление принудительно для листа, который должен идти против окружающей страницы.
contextMenubooleanfalseПредлагает ли правый клик меню структурных изменений. Каждый пункт всё равно должен пройти проверку разрешений, а пустое меню не открывается никогда.
columns[].kind'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select''text'Как столбец показывает значения и считывает введённое. Столбец select открывает список и отклоняет всё, чего в нём нет; boolean рисует флажок, переключаемый одним кликом; date открывает поле даты.
columns[].formulastring—Формула, из которой выводится каждая ячейка этого столбца, объявленная в коде, а не хранимая в данных: итог строки, налог, текущий остаток. Противоположность формуле, которую набирает читатель, — та является значением строки и меняется как любое другое. Ячейки такого столбца вообще нельзя редактировать: замена одной потеряла бы формулу лишь в этой строке, и этого никто не заметит, пока итоги не перестанут сходиться. Требует formulas на листе.
columns[].placeholderstring—Подсказка в пустой ячейке этого столбца, пока на ней находится указатель. Никогда вместо значения: столбец подсказок, всегда видимых на экране, выглядит как столбец содержимого.
columns[].appendHubSpreadsheetAppend<TRow>—Второе значение, которое показывается после основного и выбирается из короткого списка: единица после количества, вид скидки после её размера. Изменение приходит как commit с ключом столбца append.key. Копирование записывает обе части; CSV и XLSX экспортируют только основное значение.
columns[].optionsreadonly HubSpreadsheetOption[]—Варианты ответа, которые предлагает столбец select. Ячейка показывает соответствующую подпись, а не сохранённое значение, и при отсутствии совпадения возвращается к исходному значению, так что строка с устаревшим вариантом остаётся читаемой.
structureHubSpreadsheetStructureOptions<TRow>{}Какие структурные изменения может запрашивать читатель. Всё отклоняется, пока не разрешено.
retiredColumnKeysreadonly string[][]Псевдонимы удалённых столбцов, чтобы новый столбец никогда не наследовал мёртвую идентичность.
hubSpreadsheetCell (directive on ng-template)Обязательноstring—Алиас столбца, ячейки которого рисуются этим шаблоном вместо рендерера по умолчанию. Привязывается сам атрибут директивы: hubSpreadsheetCell="state".
hubSpreadsheetCellRows (hubSpreadsheetCell)readonly TRow[][]Те же строки, что переданы таблице. Их никто не читает; они нужны лишь для того, чтобы компилятор мог типизировать строку в контексте шаблона.
hubSpreadsheetCellAction (hubSpreadsheetCell)string | ((row: TRow) => boolean)''Помечает столбец как такой, ячейки которого открываются во что-то, и задаёт доступное имя этого входа. Функция решает для каждой строки. Enter сохраняется для открытия, а нажатие передаётся через opened.
hubSpreadsheetEditor (directive on ng-template)Обязательноstring—Алиас столбца, редактор которого рисуется этим шаблоном вместо встроенного. Привязывается сам атрибут директивы: hubSpreadsheetEditor="assignee".
hubSpreadsheetEditorRows (hubSpreadsheetEditor)readonly TRow[][]Те же строки, что переданы таблице. Их никто не читает; они нужны лишь для того, чтобы компилятор мог типизировать строку в контексте шаблона.
hubSpreadsheetControl (directive on ng-container)ОбязательноHubSpreadsheetControlConfig—Рендерит редактор ячейки через адаптер контролов, зарегистрированный с помощью provideHubSpreadsheetControls(). Конфигурация читается один раз, при открытии редактора.
value (hub-spreadsheet-field, ng-hub-ui-spreadsheet/signals)TRow[][]Двусторонняя модель (используйте [(value)]), хранящая строки как значение поля Signal Forms; записывается обратно при каждом изменении ячейки пользователем. Генерирует valueChange.
disabled (hub-spreadsheet-field)booleanfalseПривязывается директивой Signal Forms FormField; отключает все редакторы.
errors (hub-spreadsheet-field)readonly ValidationError.WithOptionalFieldTree[][]Привязывается директивой Signal Forms FormField. Сюда приходят только собственные ошибки поля-массива, поэтому они показываются целиком, а не по ячейкам. hub-spreadsheet-field также принимает columns, rowKey, states, decimalMark, emptyText, pageSize, readonly, frozenColumns, frozenRows и spans с тем же значением, что и у hub-spreadsheet, и генерирует selectionChange.

События

Реагируйте на то, что делает spreadsheet, — 21 событий, к которым можно подключить вашу логику.

ИмяТипОписание
commitHubSpreadsheetCommit<TRow>Ячейка получила новое значение, отличающееся от прежнего.
pastedHubSpreadsheetPaste<TRow>Вставлен блок; сообщается, сколько значений вышло за пределы листа и сколько не были числами.
clearedHubSpreadsheetCellRef<TRow>[]Нажата клавиша Delete или Backspace над несколькими ячейками либо над ячейкой со списком или «да/нет»; передаются охваченные редактируемые ячейки. Одиночная текстовая ячейка вместо этого открывает пустой редактор.
openedHubSpreadsheetCellRef<TRow>Было использовано действие ячейки — указателем или Enter там, где нет поля для правки.
selectionChangeHubGridRange | nullВыделенный прямоугольник изменился.
filledHubSpreadsheetPaste<TRow>Перетаскивание маркера заполнения завершено; сообщается одним событием на весь жест.
undoRequestedvoidПользователь запросил отмену.
redoRequestedvoidПользователь запросил повтор.
columnMoved{ from: number; to: number; key: string; keys: string[] }Столбец перемещён в другое место. Сообщается, но не применяется: в данных уже переупорядоченные псевдонимы.
rowMoved{ from: number; to: number; key: string; keys: string[] }Строка была перемещена в другое место. Сообщается, но не применяется: в данных уже переставленные ключи.
invalidDraftsChangeRecord<string, string>Несохранённый текст изменился: читатель покинул ячейку с текстом, который она не может хранить, или исправил, отбросил либо перезаписал такой текст.
mergeRequestedHubSpreadsheetMergeRequestЧитатель попросил объединить выделение. В данных — создаваемый блок и якоря тех, что он поглощает: если просто добавить новый, два блока будут претендовать на одну ячейку. applySpanMerge() делает это одной строкой.
unmergeRequestedreadonly HubGridCoords[]Читатель попросил разделить блоки, которых касается выделение, названные по их якорям. Применяется через applySpanUnmerge().
selectionRangesChangereadonly HubGridRange[]Все прямоугольники выделения при каждом его изменении. Рядом с selectionChange, который по-прежнему сообщает о том, где курсор: тому, кто показывает сумму выделенного, нужны все, а тому, кто показывает «вы в B4», — нет. Один элемент, если блоки не выбирали с Ctrl.
insertRequestedHubSpreadsheetInsertRequestThe reader asked to add rows or columns. Слишком длинная вставка так же запрашивает недостающие строки, с их числом в count.
deleteRequestedHubSpreadsheetDeleteRequestЧитатель запросил удаление строк или столбцов; передаются затронутые псевдонимы.
valueChange (hub-spreadsheet-field)TRow[]Генерируется двусторонней моделью value при изменении строк.
columnWidthsChangeRecord<string, number>Генерируется двусторонней моделью columnWidths, когда пользователь меняет ширину столбца.
expandedRowChangestring | nullГенерируется двусторонней моделью expandedRow, когда строка разворачивается или сворачивается.
collapsedColumnsChangereadonly string[]Генерируется двусторонней моделью collapsedColumns, когда группы столбцов сворачиваются или разворачиваются.
collapsedRowsChangereadonly string[]Генерируется двусторонней моделью collapsedRows, когда группы строк сворачиваются или разворачиваются.

Методы

Управляйте spreadsheet из кода — 19 методов его программного интерфейса.

ИмяСигнатураВозвращаетОписание
HubSpreadsheetComponent.focusCellfocusCell(rowKey: string, column?: string): void—Ставит курсор и клавиатуру на ячейку по ключу строки и псевдониму столбца. Ждёт только что добавленную строку, а без псевдонима встаёт на её первую редактируемую ячейку, так что следующая клавиша её открывает.
HubSpreadsheetComponent.editCelleditCell(rowKey: string, column?: string): void—Открывает редактор ячейки из кода, сохраняя её значение, как F2. Как и focusCell, ждёт только что добавленную строку; на нередактируемой ячейке только ставит курсор.
sheetToXlsxsheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8ArrayUint8ArrayЛист как настоящий .xlsx, в байтах. Число остаётся числом, а столбец дат становится датой — того CSV не умеет. Записывается то, что показывает ячейка: столбец-список отдаёт свою подпись, формула — свой результат, если только values: 'stored' не потребует хранимого.
downloadXlsxdownloadXlsx(filename: string, bytes: Uint8Array): void—Отдаёт читателю эту книгу на сохранение, добавляя .xlsx к имени, если его нет. Здесь потому, что каждый хост пишет одни и те же шесть строк и забывает освободить object URL.
xlsxToRecordsxlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>>Promise<Array<Record<string, string>>>Читает первый лист книги в строки с ключами по алиасам столбцов, отменяя две вещи, которых в CSV не бывает: общие строки и даты, хранимые как число дней. Асинхронная, потому что настоящая книга сжата, а распаковщик берётся у платформы.
sheetToCsvsheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): stringstringЛист как CSV. Если разделитель не задан, он выводится из десятичного знака — запятая не может разделять то, что она же и разделяет внутри числа, — поэтому файл для тех, кто пишет 1.234,56, получает точку с запятой.
downloadTextdownloadText(filename: string, text: string, type?: string): void—Отдаёт читателю текстовый файл на сохранение, с меткой порядка байтов, из-за которой табличный редактор откроет его как UTF-8, а не как кракозябры.
csvToRecordscsvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>>Array<Record<string, string>>Читает CSV в строки с ключами по алиасам столбцов, определяя разделитель по первой строке, а не предполагая его. Заголовки сопоставляются сперва по заголовку, затем по алиасу, без учёта регистра и пробелов по краям.
sheetValuessheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][]HubSpreadsheetValue[][]Что содержит каждая ячейка — с посчитанными формулами, а неудавшаяся записана так, как её пишет табличный редактор. Именно это читают оба экспорта; открыто для хоста, который пишет собственный файл.
evaluateSheetevaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheetHubFormulaSheetВыполняет все формулы листа в том порядке, какой требуют зависимости, считая по необходимости и запоминая. Круг замечается в момент замыкания, а не преследуется. Открыто для хоста, которому нужны ответы без отрисовки.
rewriteRowFormulasrewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[]TRow[]Переносит все координаты в строках, когда лист меняет форму: столбец переехал, строки или столбцы вставлены или удалены. Ссылка на удалённое становится #REF!, а не читает втихую соседний столбец. Вызывает её хост, потому что строки его.
mergeRequestFormergeRequestFor(spans, range): HubSpreadsheetMergeRequest | nullHubSpreadsheetMergeRequest | nullБлок, которым стало бы выделение, и якоря, которые он поглощает; null для одной ячейки. Поглощённые якоря — как раз то, что хост делает неверно сам: добавив блок и не убрав их, получаешь два блока на одну ячейку.
applySpanMergeapplySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[]HubGridSpan[]Список блоков после этого объединения, без поглощённых.
applySpanUnmergeapplySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[]HubGridSpan[]Список блоков после того, как эти разъединены.
spreadsheetRecordsspreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[]HubSpreadsheetRecord[]Каждая строка как простые данные с ключами по алиасам столбцов, чтобы работать с { price: 12, units: 3 }, а не сопоставлять координаты со своими полями по позиции.
parseForColumnparseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefinedHubSpreadsheetValue | undefinedЧего стоит в столбце набранная или вставленная строка: значение, null для пустой ячейки и undefined для того, чего столбец держать не может, — чтобы вызывающий мог отказать, а не сохранить мусор.
nextColumnKeynextColumnKey(taken: Iterable<string>, prefix?: string): stringstringАлиас, который никогда не принадлежал другому столбцу: новый столбец не переиспользует отставное имя, и ни одна сохранённая ссылка не сможет указать не туда.
danglingColumnKeysdanglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[]string[]Ссылки, которые больше не ведут ни к одному столбцу, — то есть то, что удаление оставило бы висеть в пустоте.
provideHubSpreadsheetControlsprovideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProvidersEnvironmentProvidersРегистрирует адаптер контролов, и тогда каждый столбец-список открывается через него: с поиском, уже раскрытым, и с символом, открывшим ячейку, в поле поиска. Без адаптера лист рисует свой родной список — именно это и позволяет ставить библиотеку саму по себе.

Шаблоны

Сделайте его своим — 3 слотов шаблона позволяют проецировать собственную разметку.

ИмяОписаниеПример
hubSpreadsheetEditorЗаменяет редактор одного столбца, названного по его алиасу. Шаблон получает значение, пару commit и cancel, draft, чтобы держать значение, не закрываясь, и `seed` — символ, которым читатель открыл ячейку, начав печатать, и которому место в поле поиска выбора. Таблица закрывает его так же, как свой редактор: Escape — как было, после того как закроется открытый внутри список; Tab — с тем, что держит draft; и так же, когда фокус уходит в другое место, если только не во всплывающее окно, которое один из его элементов называет через aria-controls, как список hub-select. Все остальные клавиши принадлежат редактору, включая Enter. Таблица не зависит от того, что вы туда кладёте.<ng-template hubSpreadsheetEditor="assignee" let-value let-seed="seed" let-commit="commit"> <hub-select [items]="people" autoOpen [initialSearchTerm]="seed ?? null" [ngModel]="value" (ngModelChange)="commit($event)" /> </ng-template>
hubSpreadsheetCellРисуйте ячейки столбца сами, пока их не редактируют: значок для состояния, аватар рядом с именем, ряд действий. Пара к hubSpreadsheetEditor, который закрывает другую половину жизни ячейки. В буфер обмена по-прежнему уходит значение, а не рисунок, и клавиатура по-прежнему стоит на ячейке. Передайте строки через hubSpreadsheetCellRows — и компилятор будет знать, что такое `row`.<ng-template hubSpreadsheetCell="state" let-value> <hub-badge variant="soft" [color]="colourOf(value)">{{ labelOf(value) }}</hub-badge> </ng-template>
hubSpreadsheetHeaderРисует заголовок столбца самостоятельно: значок рядом с названием, кнопку, которая редактирует столбец. Аналог hubSpreadsheetCell для заголовка. Элемент <th> остаётся за таблицей, с его шириной, закреплением, липкой позицией и флажком «выбрать все». Кнопку, ссылку или поле внутри можно нажать, не перетаскивая столбец. Шаблон получает столбец, его index, key и header в виде текста.<ng-template hubSpreadsheetHeader="price" let-column> {{ column.header }} <button type="button" (click)="editPrice()">Edit</button> </ng-template>