Компонент электронной таблицы для 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 | — | Устойчивое имя строки, чтобы состояние сохранения сопровождало свою строку и после перезагрузки. |
errors | Record<string, string> | {} | Сообщение проверки для каждой ячейки, с ключами как у `states`. Принадлежит хосту, поскольку проверка — дело того, кто знает, что означают данные. Ячейка обводится красным, а сообщение открывается во всплывающей подсказке при наведении или фокусе с клавиатуры. |
invalidDrafts | Record<string, string> | {} | Двусторонний. Текст, который читатель оставил в ячейке, хотя это не значение, которое столбец может хранить, с тем же ключом, что и states. Ячейка продолжает его показывать, в рамке и с сообщением, что он не сохранён; повторное открытие ячейки возвращает его для исправления, Escape отказывается от него, а запись поверх ячейки или удаление её строки или столбца убирает его. Читайте его, чтобы не сохранить молча старое значение. |
states | Record<string, HubSpreadsheetCellState> | {} | Состояние сохранения для каждой ячейки; ключ — ключ строки и псевдоним столбца, соединённые символом табуляции. |
decimalMark | ',' | '.' | ',' | Символ, которым этот читатель вводит десятичные дроби. Учитывается, только если вставленное значение не содержало сырого числа. |
emptyText | string | '' | Что показывает пустой лист. |
pageSize | number | 10 | На сколько строк перемещают курсор Page Up и Page Down. |
readonly | boolean | false | Отключает все редакторы независимо от настроек отдельных ячеек. |
frozenColumns | number | 0 | Сколько столбцов остаются закреплёнными у начального края; считается так же, как Excel закрепляет области. |
frozenRows | number | 0 | Сколько строк остаются закреплёнными под заголовком. |
spans | readonly HubGridSpan[] | [] | Объединённые блоки, каждый из которых задаётся верхним левым углом и размером. |
disjointSelection | boolean | true | Добавляет ли клик с Ctrl (Cmd на Mac) второй блок к выделению вместо того, чтобы начать новое. Включено: так делает табличный редактор, и жест всё равно был свободен — обычный клик уже выделяет, а Ctrl ничего не говорил. Каждый блок отмечен, Delete очищает все, а любой обычный клик или стрелка начинают выделение заново. Копирование происходит только когда блоки складываются в таблицу, иначе оно отклоняется; маркер заполнения исчезает, пока выбрано больше одного блока — заполнение продолжает один блок, и какой из нескольких, ответа нет. |
fillHandle | boolean | false | Whether the sheet offers the fill handle at the corner of the selection. Он же включает Ctrl+D (Cmd+D на Mac) для заполнения вниз. |
canUndo | boolean | false | Доступна ли отмена. Лист лишь спрашивает; историю хранит владелец. |
canRedo | boolean | false | Доступен ли повтор. |
resizableColumns | boolean | false | Может ли читатель перетащить задний край столбца, чтобы расширить или сузить его. |
reorderableColumns | boolean | false | Может ли читатель перетащить заголовок, чтобы переместить столбец в другое место. |
reorderableRows | boolean | false | Может ли читатель перетащить строку, чтобы поместить её в другое место. С клавиатуры Alt+Shift со стрелкой вверх или вниз сдвигает строку курсора на одну позицию, а новая позиция зачитывается вслух. |
rowHandleLabel | string | '' | Доступное имя маркера перетаскивания строки. |
columnWidths | Record<string, number> | {} | Ширина каждого столбца в пикселях, ключ — псевдоним. Двусторонняя привязка: лист записывает значение по мере перетаскивания, а вы можете его сохранить. |
minColumnWidth | number | 48 | Минимальная ширина, до которой можно сузить столбец перетаскиванием. |
virtual | boolean | false | Рисует только строки, попадающие в окно просмотра, и резервирует высоту остальных — для листа в тысячи строк. По умолчанию выключено, и за это есть плата: строк вне видимости нет в документе, поэтому поиск браузера и печать достают лишь нарисованное, а строки должны быть одной высоты. Включение также задаёт листу высоту 24rem: растущий свободно, он равен своему содержимому, и виртуализировать нечего. |
rowHeight | number | 0 | Высота строки при виртуализации, в пикселях. Ноль измеряет первую нарисованную строку — это верно, пока строки одинаковы. Укажите её для листа, собираемого скрытым: ни разу не размеченная строка измеряется нулём, а окно, посчитанное от нуля, — это весь лист. |
formulas | boolean | false | Считается ли формулой ячейка, значение которой начинается с =. Выключено, пока не попросят: текстовый столбец вполне может хранить =1+1 как то, что кто-то написал. Формула может обратиться к столбцу по алиасу — =[units] * [price], =SUM([total:]) — и после переноса столбца или переписанного заголовка она значит то же самое, либо по координате, как пишет табличный редактор — =ROUND(SUM(E1:E4), 2) —, а координата говорит, где столбец был, а не какой он; rewriteRowFormulas() переносит такие вместе с листом, а ссылка на удалённое становится #REF!, а не читает втихую соседний. Двоеточие читает весь столбец, исключая спрашивающую ячейку; любой другой круг показывается как #CYCLE!, а не преследуется. |
mergeable | boolean | false | Может ли читатель объединять ячейки и разделять их — предлагается в контекстном меню, так что нужен и contextMenu. Выключено, пока не попросят, как любое изменение структуры. |
editOn | 'click' | 'double-click' | 'double-click' | Что открывает редактор указателем. По умолчанию двойной щелчок — соглашение таблиц: щелчок выбирает ячейку и оставляет её значение в покое, первый набранный символ открывает редактор и попадает в него, а ячейка со списком или датой показывает значок, открывающий её одним щелчком. Значение click открывает с первого щелчка — для листа, который существует, чтобы в нём печатали. В обоих случаях редактор открывается при отпускании и только если указатель не двигался, поэтому выделение диапазона протягиванием работает по-прежнему. |
expansion | TemplateRef<HubSpreadsheetExpansionContext<TRow>> | null | null | Шаблон, нарисованный под открытой строкой, с тем, что строка хранит за своими числами. |
expandedRow | string | null | null | Двусторонний. Какая строка открыта, по её ключу; по одной строке за раз. |
expandToggle | boolean | false | Рисует маленькую кнопку по краям каждой строки, открывающей деталь, чтобы читатель открывал её без кнопки от владельца. |
expandToggleLabel | string | '' | Доступное имя этой кнопки; лист не ведёт словаря. |
rowLevel | (row: TRow) => number | undefined | () => 0 | Как глубоко строка сидит в структуре: 1 — внутри одного свёртывания, 2 — внутри двух, 0 или ничего — вне любого. |
collapsedRows | readonly string[] | [] | Двустороннее. Какие группы строк свёрнуты, по id группы. |
collapsedColumns | readonly string[] | [] | Двустороннее. Какие группы столбцов свёрнуты, по id группы. |
rowToggleLabel | string | '' | Доступное имя кнопки группы строк. |
columnToggleLabel | string | '' | Доступное имя кнопки группы столбцов. |
direction | 'auto' | 'ltr' | 'rtl' | 'auto' | В какую сторону идёт лист. auto следует за страницей — лист внутри статьи справа налево читается как статья, потому что dir наследуется —, а ltr и rtl задают направление принудительно для листа, который должен идти против окружающей страницы. |
contextMenu | boolean | false | Предлагает ли правый клик меню структурных изменений. Каждый пункт всё равно должен пройти проверку разрешений, а пустое меню не открывается никогда. |
columns[].kind | 'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select' | 'text' | Как столбец показывает значения и считывает введённое. Столбец select открывает список и отклоняет всё, чего в нём нет; boolean рисует флажок, переключаемый одним кликом; date открывает поле даты. |
columns[].formula | string | — | Формула, из которой выводится каждая ячейка этого столбца, объявленная в коде, а не хранимая в данных: итог строки, налог, текущий остаток. Противоположность формуле, которую набирает читатель, — та является значением строки и меняется как любое другое. Ячейки такого столбца вообще нельзя редактировать: замена одной потеряла бы формулу лишь в этой строке, и этого никто не заметит, пока итоги не перестанут сходиться. Требует formulas на листе. |
columns[].placeholder | string | — | Подсказка в пустой ячейке этого столбца, пока на ней находится указатель. Никогда вместо значения: столбец подсказок, всегда видимых на экране, выглядит как столбец содержимого. |
columns[].append | HubSpreadsheetAppend<TRow> | — | Второе значение, которое показывается после основного и выбирается из короткого списка: единица после количества, вид скидки после её размера. Изменение приходит как commit с ключом столбца append.key. Копирование записывает обе части; CSV и XLSX экспортируют только основное значение. |
columns[].options | readonly HubSpreadsheetOption[] | — | Варианты ответа, которые предлагает столбец select. Ячейка показывает соответствующую подпись, а не сохранённое значение, и при отсутствии совпадения возвращается к исходному значению, так что строка с устаревшим вариантом остаётся читаемой. |
structure | HubSpreadsheetStructureOptions<TRow> | {} | Какие структурные изменения может запрашивать читатель. Всё отклоняется, пока не разрешено. |
retiredColumnKeys | readonly 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) | boolean | false | Привязывается директивой 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 событий, к которым можно подключить вашу логику.
| Имя | Тип | Описание |
|---|---|---|
commit | HubSpreadsheetCommit<TRow> | Ячейка получила новое значение, отличающееся от прежнего. |
pasted | HubSpreadsheetPaste<TRow> | Вставлен блок; сообщается, сколько значений вышло за пределы листа и сколько не были числами. |
cleared | HubSpreadsheetCellRef<TRow>[] | Нажата клавиша Delete или Backspace над несколькими ячейками либо над ячейкой со списком или «да/нет»; передаются охваченные редактируемые ячейки. Одиночная текстовая ячейка вместо этого открывает пустой редактор. |
opened | HubSpreadsheetCellRef<TRow> | Было использовано действие ячейки — указателем или Enter там, где нет поля для правки. |
selectionChange | HubGridRange | null | Выделенный прямоугольник изменился. |
filled | HubSpreadsheetPaste<TRow> | Перетаскивание маркера заполнения завершено; сообщается одним событием на весь жест. |
undoRequested | void | Пользователь запросил отмену. |
redoRequested | void | Пользователь запросил повтор. |
columnMoved | { from: number; to: number; key: string; keys: string[] } | Столбец перемещён в другое место. Сообщается, но не применяется: в данных уже переупорядоченные псевдонимы. |
rowMoved | { from: number; to: number; key: string; keys: string[] } | Строка была перемещена в другое место. Сообщается, но не применяется: в данных уже переставленные ключи. |
invalidDraftsChange | Record<string, string> | Несохранённый текст изменился: читатель покинул ячейку с текстом, который она не может хранить, или исправил, отбросил либо перезаписал такой текст. |
mergeRequested | HubSpreadsheetMergeRequest | Читатель попросил объединить выделение. В данных — создаваемый блок и якоря тех, что он поглощает: если просто добавить новый, два блока будут претендовать на одну ячейку. applySpanMerge() делает это одной строкой. |
unmergeRequested | readonly HubGridCoords[] | Читатель попросил разделить блоки, которых касается выделение, названные по их якорям. Применяется через applySpanUnmerge(). |
selectionRangesChange | readonly HubGridRange[] | Все прямоугольники выделения при каждом его изменении. Рядом с selectionChange, который по-прежнему сообщает о том, где курсор: тому, кто показывает сумму выделенного, нужны все, а тому, кто показывает «вы в B4», — нет. Один элемент, если блоки не выбирали с Ctrl. |
insertRequested | HubSpreadsheetInsertRequest | The reader asked to add rows or columns. Слишком длинная вставка так же запрашивает недостающие строки, с их числом в count. |
deleteRequested | HubSpreadsheetDeleteRequest | Читатель запросил удаление строк или столбцов; передаются затронутые псевдонимы. |
valueChange (hub-spreadsheet-field) | TRow[] | Генерируется двусторонней моделью value при изменении строк. |
columnWidthsChange | Record<string, number> | Генерируется двусторонней моделью columnWidths, когда пользователь меняет ширину столбца. |
expandedRowChange | string | null | Генерируется двусторонней моделью expandedRow, когда строка разворачивается или сворачивается. |
collapsedColumnsChange | readonly string[] | Генерируется двусторонней моделью collapsedColumns, когда группы столбцов сворачиваются или разворачиваются. |
collapsedRowsChange | readonly string[] | Генерируется двусторонней моделью collapsedRows, когда группы строк сворачиваются или разворачиваются. |
Методы
Управляйте spreadsheet из кода — 19 методов его программного интерфейса.
| Имя | Сигнатура | Возвращает | Описание |
|---|---|---|---|
HubSpreadsheetComponent.focusCell | focusCell(rowKey: string, column?: string): void | — | Ставит курсор и клавиатуру на ячейку по ключу строки и псевдониму столбца. Ждёт только что добавленную строку, а без псевдонима встаёт на её первую редактируемую ячейку, так что следующая клавиша её открывает. |
HubSpreadsheetComponent.editCell | editCell(rowKey: string, column?: string): void | — | Открывает редактор ячейки из кода, сохраняя её значение, как F2. Как и focusCell, ждёт только что добавленную строку; на нередактируемой ячейке только ставит курсор. |
sheetToXlsx | sheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8Array | Uint8Array | Лист как настоящий .xlsx, в байтах. Число остаётся числом, а столбец дат становится датой — того CSV не умеет. Записывается то, что показывает ячейка: столбец-список отдаёт свою подпись, формула — свой результат, если только values: 'stored' не потребует хранимого. |
downloadXlsx | downloadXlsx(filename: string, bytes: Uint8Array): void | — | Отдаёт читателю эту книгу на сохранение, добавляя .xlsx к имени, если его нет. Здесь потому, что каждый хост пишет одни и те же шесть строк и забывает освободить object URL. |
xlsxToRecords | xlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>> | Promise<Array<Record<string, string>>> | Читает первый лист книги в строки с ключами по алиасам столбцов, отменяя две вещи, которых в CSV не бывает: общие строки и даты, хранимые как число дней. Асинхронная, потому что настоящая книга сжата, а распаковщик берётся у платформы. |
sheetToCsv | sheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): string | string | Лист как CSV. Если разделитель не задан, он выводится из десятичного знака — запятая не может разделять то, что она же и разделяет внутри числа, — поэтому файл для тех, кто пишет 1.234,56, получает точку с запятой. |
downloadText | downloadText(filename: string, text: string, type?: string): void | — | Отдаёт читателю текстовый файл на сохранение, с меткой порядка байтов, из-за которой табличный редактор откроет его как UTF-8, а не как кракозябры. |
csvToRecords | csvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>> | Array<Record<string, string>> | Читает CSV в строки с ключами по алиасам столбцов, определяя разделитель по первой строке, а не предполагая его. Заголовки сопоставляются сперва по заголовку, затем по алиасу, без учёта регистра и пробелов по краям. |
sheetValues | sheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][] | HubSpreadsheetValue[][] | Что содержит каждая ячейка — с посчитанными формулами, а неудавшаяся записана так, как её пишет табличный редактор. Именно это читают оба экспорта; открыто для хоста, который пишет собственный файл. |
evaluateSheet | evaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheet | HubFormulaSheet | Выполняет все формулы листа в том порядке, какой требуют зависимости, считая по необходимости и запоминая. Круг замечается в момент замыкания, а не преследуется. Открыто для хоста, которому нужны ответы без отрисовки. |
rewriteRowFormulas | rewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[] | TRow[] | Переносит все координаты в строках, когда лист меняет форму: столбец переехал, строки или столбцы вставлены или удалены. Ссылка на удалённое становится #REF!, а не читает втихую соседний столбец. Вызывает её хост, потому что строки его. |
mergeRequestFor | mergeRequestFor(spans, range): HubSpreadsheetMergeRequest | null | HubSpreadsheetMergeRequest | null | Блок, которым стало бы выделение, и якоря, которые он поглощает; null для одной ячейки. Поглощённые якоря — как раз то, что хост делает неверно сам: добавив блок и не убрав их, получаешь два блока на одну ячейку. |
applySpanMerge | applySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[] | HubGridSpan[] | Список блоков после этого объединения, без поглощённых. |
applySpanUnmerge | applySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[] | HubGridSpan[] | Список блоков после того, как эти разъединены. |
spreadsheetRecords | spreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[] | HubSpreadsheetRecord[] | Каждая строка как простые данные с ключами по алиасам столбцов, чтобы работать с { price: 12, units: 3 }, а не сопоставлять координаты со своими полями по позиции. |
parseForColumn | parseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefined | HubSpreadsheetValue | undefined | Чего стоит в столбце набранная или вставленная строка: значение, null для пустой ячейки и undefined для того, чего столбец держать не может, — чтобы вызывающий мог отказать, а не сохранить мусор. |
nextColumnKey | nextColumnKey(taken: Iterable<string>, prefix?: string): string | string | Алиас, который никогда не принадлежал другому столбцу: новый столбец не переиспользует отставное имя, и ни одна сохранённая ссылка не сможет указать не туда. |
danglingColumnKeys | danglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[] | string[] | Ссылки, которые больше не ведут ни к одному столбцу, — то есть то, что удаление оставило бы висеть в пустоте. |
provideHubSpreadsheetControls | provideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProviders | EnvironmentProviders | Регистрирует адаптер контролов, и тогда каждый столбец-список открывается через него: с поиском, уже раскрытым, и с символом, открывшим ячейку, в поле поиска. Без адаптера лист рисует свой родной список — именно это и позволяет ставить библиотеку саму по себе. |
Шаблоны
Сделайте его своим — 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> |