Библиотека форм для Angular | ng-hub-ui-forms
Доступные поля форм для Angular (input, textarea, slider, select, datepicker) с автоматическим выводом ошибок на уровне контрола, группы и формы, реактивными формами и CSS-переменными.
Справочник API
Вот полный контракт forms: всё, что можно привязать, прослушать, спроецировать и тематизировать, собрано в одном месте. Подключите то, что нужно, и оформите так, как хотите — это standalone и дружит с сигналами.
Входные свойства
Настройте forms с помощью 87 входных свойств. Привязывайте их, как любой @Input в Angular.
| Имя | Тип | По умолчанию | Описание |
|---|---|---|---|
formControlName / [formControl] | string | FormControl | — | Привязывает любое поле к реактивному контролу. Ошибки отображаются автоматически, когда контрол был затронут (touched) и недействителен. |
label | string | '' | Текст метки поля. |
labelType (hub-input, hub-select, hub-datepicker) | 'stacked' | 'floating' | 'horizontal' | 'stacked' | Расположение метки. `floating` размещает метку внутри контрола, где она заменяет собой placeholder, пока поле не получит фокус или значение. |
labelType (hub-textarea, hub-otp-input, hub-slider, hub-segmented, hub-timepicker) | 'stacked' | 'horizontal' | 'stacked' | Расположение метки. У этих полей нет варианта `floating`: если он передан, метка отрисовывается как `stacked`. |
placeholder (hub-input, hub-select, hub-textarea, hub-datepicker) | string | '' / NgSelectConfig.placeholder (hub-select) | Текст placeholder. |
formText | string | — | Вспомогательный текст, отображаемый под контролом. |
type (hub-input) — file is deprecated | 'text' | 'number' | 'password' | 'email' | 'tel' | 'url' | 'color' | 'checkbox' | 'switch' | 'counter' | 'file' | 'text' | Формат hub-input. |
passwordRevealed (hub-input) | boolean | false | Двунаправленное состояние видимости поля пароля. Нажатие на кнопку с иконкой глаза обновляет его; установка значения показывает или скрывает пароль. |
passwordToggle (hub-input) | boolean | true | Отображается ли встроенная кнопка показа/скрытия пароля в полях пароля. |
hideOnBlur (hub-input) | boolean | true | Скрывается ли показанный пароль автоматически, когда фокус покидает поле. |
capsLockWarning (hub-input) | boolean | true | Отображается ли подсказка под полем, пока активен Caps Lock. |
passwordStrength (hub-input) | boolean | false | Отображает необязательный индикатор надёжности пароля из 4 сегментов под полем. Логику оценки можно переопределить через provideHubForms. |
autocomplete (hub-input) | string | '' | Нативный атрибут autocomplete, например current-password или new-password для менеджеров паролей. |
clearable (hub-input) | boolean | false | Если true, показывает встроенную кнопку ✕ при наличии значения; очищает контрол и отправляет пустой поисковый запрос. |
debounceTime (hub-input) | number | 0 | Задержка в миллисекундах перед срабатыванием события search (0 — при каждом нажатии). |
mask (hub-input) | string | — | Маска шаблона для текстовых форматов. Токены: 0 = цифра, A = буква, * = буквенно-цифровой символ; остальные символы являются буквальными разделителями. Например, "0000 0000 0000 0000". |
unmaskValue (hub-input) | boolean | false | При заданной маске сохранять в форме необработанные введённые символы (без разделителей) вместо форматированного текста. |
range (hub-slider) | boolean | false | Ползунок диапазона с двумя бегунками; значение становится кортежем [lower, upper]. |
options (hub-segmented) | HubSegmentedOption[] | [] | Выбираемые опции для hub-segmented в порядке отрисовки — каждая { value, label, disabled? }. |
size (hub-segmented) | 'sm' | 'md' | 'lg' | 'md' | Визуальная плотность сегментированного элемента управления: 'sm', 'md' (по умолчанию) или 'lg'. |
disabled (all fields) | boolean (two-way, model) | false | Отключает поле. Наследуется каждым полем от общей базы и является двусторонним — поле, отключённое через свой реактивный контрол, сообщает об изменении обратно. В `hub-segmented` отдельные опции также могут отключаться через `option.disabled`. |
multiple (hub-segmented) | boolean | false | Разрешить выбор нескольких вариантов; значение становится массивом, кнопки переключаются (aria-pressed). |
vertical (hub-segmented) | boolean | false | Располагать сегменты вертикально, а не в горизонтальный ряд. |
vertical (hub-select) — deprecated | boolean | false | Устарело и связано с устаревшими форматами, отличными от dropdown: располагает опции buttons/checkbox/radio вертикально. Используйте `<hub-segmented [vertical]="true">`. |
color (hub-segmented) | 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'neutral' | string | '' | Семантический акцент выбранного сегмента (primary, success, …) или любой цвет; скользит в одиночном режиме. |
value (hub-segmented) | unknown | unknown[] | undefined | Двусторонне привязываемое выбранное значение (model()): значение выбранной опции в одиночном режиме, массив выбранных значений в режиме multiple. Испускает valueChange; обычно вместо этого управляется через formControlName. |
format (hub-select) — deprecated for buttons/checkbox/radio | 'dropdown' | 'buttons' | 'checkbox' | 'radio' | 'dropdown' | Как select отображает одно и то же значение. |
prepend / append (hub-input, hub-select, hub-textarea, hub-datepicker, hub-timepicker) | string | string[] | '' | Статические групповые дополнения у любого поля, отображаемого как рамка: строка — одно дополнение, массив — их последовательность, а пустые элементы отбрасываются, а не рисуются пустой рамкой. Дополнение разделяет границу поля и не получает фокус — для интерактивного элемента управления у края используйте шаблоны [hubPrepend] / [hubAppend]. Возможны оба варианта одновременно, и проецируемое содержимое всегда остаётся крайним элементом со своей стороны. |
items / bindLabel / bindValue / multiple (hub-select) | any[] / string / string / boolean | — | Опции, имена свойств label/value для объектных элементов и множественный выбор. |
groupBy (hub-select) | string | undefined | undefined | Имя свойства (путь в точечной нотации), по которому элементы dropdown группируются под заголовками групп опций. |
searchable / clearable (hub-select) | boolean | true | Можно ли фильтровать опции вводом текста (searchable) и можно ли очистить выбор встроенной кнопкой очистки (clearable). По умолчанию оба равны true. |
closeOnSelect (hub-select) | boolean | true | Закрывается ли dropdown после выбора элемента. Установите false, чтобы он оставался открытым при выборе нескольких значений в режиме multiple. |
fixedPlaceholder (hub-select) | boolean | false | Оставляет placeholder видимым даже после выбора значения. По умолчанию false (placeholder скрывается при выборе), что инвертирует нестандартное значение по умолчанию из ng-select v23. |
loading / notFoundText (hub-select) | boolean / string | false / NgSelectConfig.notFoundText | loading отображает состояние загрузки dropdown, пока асинхронные элементы загружаются; notFoundText — сообщение, показываемое, когда ни один элемент не соответствует поисковому запросу. |
readonly (hub-input, hub-select, hub-textarea, hub-datepicker, hub-otp-input, hub-timepicker) | boolean | false | Если true, поле отображает своё значение, но отклоняет любое взаимодействие — без стилизации disabled и без изменения состояния формы. |
appendTo (hub-select) | string | undefined | 'body' | CSS-селектор элемента, к которому добавляется панель dropdown. По умолчанию 'body', благодаря чему панель выходит из-под влияния предков с overflow/transform (карточек, контейнеров прокрутки, модальных окон); передайте undefined, чтобы отрисовать её inline. |
addTag (hub-select) | boolean | ((term: string) => any | Promise<any>) | false | Создание элементов из поискового запроса (формат dropdown): true добавляет запрос как есть; функция преобразует запрос в новый элемент — синхронно или через Promise. |
addTagText (hub-select) | string | NgSelectConfig.addTagText | Подпись строки «добавить элемент», отображаемой при вводе, когда включён addTag. |
minTermLength (hub-select) | number | 0 | Минимальная длина поискового запроса, после которой срабатывает фильтрация (или Subject для typeahead). |
typeahead (hub-select) | Subject<string> | undefined | undefined | Subject, получающий изменения поискового запроса для асинхронной/серверной загрузки; если он задан, клиентская фильтрация отключается — верните результаты через items. |
compareWith (hub-select) | ((a: any, b: any) => boolean) | undefined | undefined | Собственное сравнение элемента со связанным значением (например, объекты по id); если не задано, применяется встроенное сравнение поставщика. |
searchFn (hub-select) | ((term: string, item: any) => boolean) | undefined | undefined | Заменяет встроенное сопоставление, которое использует `searchable`. Получает введённый запрос и элемент и возвращает, соответствует ли элемент запросу, — благодаря чему поиск может учитывать поля, которых нет в метке. |
mode (hub-datepicker) | 'single' | 'range' | 'day-time-range' | 'single' | Одна дата, свободный диапазон дат или один день с временем начала и окончания внутри него. |
granularity (hub-datepicker) | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'day' | Точность каждой выбранной точки и панель, которая её выбирает: year и month отображают сетку из 12 ячеек, day — календарь, а hour, minute и second добавляют к нему строку времени. Ортогонально mode: mode задаёт, сколько точек выбирается, а granularity — насколько точна каждая. По умолчанию day, что выдаёт ту же строку YYYY-MM-DD, что и раньше; начиная с hour значение становится полной меткой времени ISO 8601 с локальным временем читателя и смещением именно этой даты. |
valueFormat / parse (hub-datepicker) | 'iso' | 'date' | 'timestamp' | ((date) => unknown) / ((raw) => Date | null) | null | 'iso' / null | Оси значения. valueFormat задаёт, что хранит связанный контрол: 'iso' (по умолчанию), 'date' для нативного Date, 'timestamp' для миллисекунд эпохи или функция для всего остального. parse задаёт, как читается входящее значение, заменяя встроенное распознавание ISO-строк любой ширины, экземпляров Date и миллисекунд эпохи — и применяется также к min и max. |
minuteStep / secondStep / hourFormat (hub-datepicker) | number / number / '12' | '24' | undefined | 5 / 1 / undefined | Настройки времени: minuteStep и secondStep — шаг спинбаттонов, а hourFormat принудительно задаёт 12- или 24-часовой формат; если не указан, выводится из локали и применяется как к отображению поля, так и к панели, чтобы они никогда не противоречили друг другу. Все три опираются на глобальную конфигурацию provideHubForms. |
min / max / disabledDates (hub-datepicker) | string | Date | number | null / ((date: Date) => boolean) | null | null | Границы выбора и предикат отключения отдельных дат. Границы учитывают время, а не только день: день отключается лишь тогда, когда ни один его момент не разрешён, поэтому min = 2026-09-01T14:00 оставляет 1 сентября кликабельным, а более ранние часы отклоняют уже элементы выбора времени. Принимает ISO-строку, Date или миллисекунды эпохи. |
locale / firstDayOfWeek / weekdayFormat (hub-datepicker) | string / number / 'short' | 'narrow' | 'long' | LOCALE_ID / undefined / undefined | i18n календаря: locale — тег BCP-47 для отображаемого значения и названий месяцев/дней недели (по умолчанию — LOCALE_ID приложения с откатом на en-US); firstDayOfWeek задаёт первый день недели (0 = воскресенье, 1 = понедельник…); weekdayFormat выбирает ширину подписей дней недели в заголовке. Последние два при отсутствии значения берутся из глобальной конфигурации provideHubForms. |
displayFormat / timeDisplayFormat / rangeSeparator / labels (hub-datepicker) | Intl.DateTimeFormatOptions | string | ((date) => string) / Intl.DateTimeFormatOptions / string / Partial<HubDatepickerLabels> | undefined / undefined / undefined / {} | Форматирование отображения: displayFormat отрисовывает выбранное значение и принимает Intl.DateTimeFormatOptions, шаблон даты Angular вроде 'dd/MM/yyyy HH:mm' или функцию; timeDisplayFormat накладывается поверх него, как только гранулярность начинает нести время, поэтому часть с датой сохраняет то, что задал displayFormat; rangeSeparator — текст между двумя датами диапазона; labels переопределяет подписи интерфейса для конкретного экземпляра (поверх глобальной конфигурации). |
clearable / showToday / closeOnSelect (hub-datepicker) | boolean | true / true / true | Флаги поведения: clearable показывает кнопку очистки, showToday показывает кнопку «сегодня», а closeOnSelect закрывает календарь после выбора даты (только в одиночном режиме). По умолчанию: true / true / true. |
multiple (hub-file-input) | boolean | false | Можно ли хранить более одного файла. Меняет значение контрола с File на File[]. |
accept (hub-file-input) | string | '*' | Допустимые типы файлов, например image/*,.pdf. Применяется и при перетаскивании и вставке, а не только в системном диалоге. |
maxSize / minSize / maxTotalSize (hub-file-input) | number | null | null | Максимальный и минимальный размер одного файла и максимальный суммарный размер, в байтах. |
maxFiles (hub-file-input) | number | null | null | Максимальное число файлов. Имеет смысл только вместе с multiple. |
dragDrop / paste (hub-file-input) | boolean | true | Можно ли перетаскивать файлы на поле и вставлять их в него. |
preview (hub-file-input) | 'none' | 'list' | 'grid' | 'list' | Как отображаются файлы: никак, списком или сеткой миниатюр. |
allowDuplicates (hub-file-input) | boolean | false | Можно ли выбрать один и тот же файл дважды (ключ: имя, размер и дата изменения). |
capture (hub-file-input) | 'user' | 'environment' | null | null | Открывает камеру устройства вместо файлового менеджера на поддерживаемых платформах. |
autoUpload (hub-file-input) | boolean | true | Начинает ли только что принятый файл загружаться сразу. Игнорируется без зарегистрированного загрузчика. |
buttonLabel / hint (hub-file-input) | string | null | null | Переопределяет текст кнопки выбора и автоматически создаваемую подсказку об ограничениях. |
dropText / dropSubtext (hub-file-input) | string | null | null | Переопределение двух строк приглашения зоны перетаскивания для конкретного экземпляра. Обе по умолчанию берутся из глобальных подписей. |
classlist (every field except hub-segmented and hub-legend) | string | '' | Дополнительные CSS-классы для хост-элемента. |
showValid (all fields) | boolean | HubFormsConfig.showValid | Показывает ли действительное поле своё состояние валидности. По умолчанию выключено, потому что форма, которая красит зелёным каждое нетронутое поле, ни о чём не говорит; недопустимое состояние отображается всегда. |
validFeedback (all fields) | string | null | null | Сообщение, отображаемое под полем, когда оно стало действительным, при включённом `showValid`. |
invalidFeedbackTemplateFn (all fields) | ((key: string, value: any) => string) | null | null | Переопределяет сообщение для заданного ключа ошибки только в этом поле. Получает ключ ошибки и его значение и возвращает текст — значение по умолчанию для всего приложения задаётся в `provideHubForms`. |
min / max (hub-input) | number | undefined (two-way, model) | undefined | Числовые границы для форматов number и counter. Двусторонние, поэтому счётчик, ограничивающий собственное значение, сообщает границу обратно. |
mode (hub-otp-input) | 'numeric' | 'alphanumeric' | 'alpha' | 'numeric' | Какие символы принимает ячейка и какую клавиатуру предлагает телефон: только цифры либо буквы и цифры. |
min / max (hub-timepicker) | string (HH:MM) | '' | Самое раннее и самое позднее время, которое принимает поле, в виде `HH:MM`. Пустое значение означает отсутствие ограничения. |
step (hub-timepicker) | number (seconds) | 0 | Гранулярность нативного степпера, в секундах. `0` оставляет браузерное значение по умолчанию — одну минуту. |
group / groupName (form[hubForm], hub-fieldset) | AbstractControl | null / string | undefined | null / undefined | Группа, ошибки которой показывает контейнер. Передайте в `group` сам `AbstractControl` либо в `groupName` — имя дочернего контрола окружающей формы; ни то, ни другое не нужно, если контейнер уже оборачивает группу, об ошибках которой сообщает. |
errorTrigger (form[hubForm], hub-fieldset) | 'touched' | 'submit' | 'always' | 'touched' | Когда становятся видимыми ошибки уровня группы: как только группа была затронута (touched), только после попытки отправки или сразу. |
formTextType (all fields) | 'bottom' | — | Расположение вспомогательного текста. Поддерживается только `bottom`. |
rows (hub-textarea) | number | — | Число видимых строк текста. |
cols (hub-textarea) | number | — | Число видимых столбцов. Если задано, поле перестаёт растягиваться на всю ширину. |
maxlength (hub-textarea) | number | — | Максимальное число символов. Задаёт и нативный лимит, и счётчик. |
counter (hub-textarea) | boolean | — | Показывать ли счётчик символов под полем. |
autoresize (hub-textarea) | boolean | — | Растёт ли поле под свой контент. |
length (hub-otp-input) | number | — | Число ячеек (символов) в коде. |
secret (hub-otp-input) | boolean | — | Скрывает символы, как в поле пароля. |
separator (hub-otp-input) | string | — | Символ-разделитель между группами. |
separatorEvery (hub-otp-input) | number | — | Вставляет видимый разделитель каждые N ячеек (0 — без разделителя). |
showValue (hub-slider) | boolean | — | Показывать ли всплывающие значения над ползунками. |
step (hub-input, hub-slider) | number | — | Величина шага (числовые поля и счётчики). |
legend (hub-fieldset) | string | — | Текст легенды. Игнорируется, если спроецирован шаблон `hubLegend`. |
required (all fields) | boolean | null (two-way, model) | null | Обязательно ли поле. При реактивной привязке значение выводится из собственных валидаторов контрола, поэтому заданное прямо в разметке учитывается только для полей на основе шаблонов (template-driven); оно управляет звёздочкой и атрибутом `required`. |
required (hub-legend) | boolean | — | Отображать ли индикатор обязательного поля. |
invalid (hub-legend) | boolean | — | Применять ли оформление недопустимого состояния. |
События
Реагируйте на то, что делает forms, — 13 событий, к которым можно подключить вашу логику.
| Имя | Тип | Описание |
|---|---|---|
valueChange | EventEmitter<value> | Вызывается при каждом изменении значения поля. |
search (hub-input) | EventEmitter<string> | Термин автодополнения с задержкой, выдаваемый по мере ввода (текстовые поля). |
rejected (hub-file-input) | EventEmitter<HubFileRejection[]> | Файлы, отклонённые объявленными ограничениями, каждый с причиной отклонения. |
fileRemoved (hub-file-input) | EventEmitter<File> | Файл, удалённый из выбора. |
uploadStateChange (hub-file-input) | EventEmitter<readonly HubFileItem[]> | Полный список элементов при каждом изменении статуса или прогресса загрузки. |
submit (form[hubForm]) — the native event | SubmitEvent (native, not a custom output) | Не собственный выход: `hubForm` слушает штатное событие `submit` самой формы, отменяет переход по умолчанию, помечает всё дерево как touched и переключает состояние submitted. Для своего обработчика привяжите `(submit)` к форме. |
disabledChange / requiredChange (all fields) · labelTypeChange / placeholderChange / minChange / maxChange / passwordRevealedChange (hub-input) · valueChange (hub-segmented) | EventEmitter<T> (the paired half of each two-way model) | Каждый двусторонний input на базе `model()` публикует парный выход `Change`, благодаря чему работают `[(disabled)]` и ему подобные. Здесь они перечислены потому, что синтаксис «банан в коробке» их скрывает. |
opened / closed / cleared / viewChange (hub-datepicker) | EventEmitter | События жизненного цикла и навигации календаря. |
onOpen / onClose / onClear / onSearch / onAdd / onRemove (hub-select) | EventEmitter | События жизненного цикла выпадающего списка и события tag/typeahead. |
onFocus / onBlur (hub-select) | EventEmitter<any> | Вызываются, когда контрол dropdown получает или теряет фокус (формат dropdown), ретранслируя события focus/blur поставщика. |
scroll / scrollToEnd (hub-select) | EventEmitter<{ start: number; end: number }> / EventEmitter<any> | scroll испускает видимое окно { start, end } во время прокрутки списка dropdown; scrollToEnd испускается, когда список достигает конца — хук для бесконечной/постраничной загрузки с typeahead. |
enter (hub-input) | EventEmitter<number | string | boolean | File | FileList | null> | Выдаёт текущее значение при нажатии Enter. |
completed (hub-otp-input) | EventEmitter<string> | Выдаёт полный код, когда заполнены все ячейки. |
Шаблоны
Сделайте его своим — 10 слотов шаблона позволяют проецировать собственную разметку.
| Имя | Описание | Пример |
|---|---|---|
hubFormText | Проецирование насыщенного содержимого вспомогательного текста. | <ng-template hubFormText>…</ng-template> |
hubValidationError | Переопределение сообщения для заданного ключа ошибки. | <ng-template hubValidationError key="min">…</ng-template> |
hubLegend | Пользовательское содержимое легенды fieldset. | <ng-template hubLegend>…</ng-template> |
ng-option-tmp (hub-select) | Пользовательская отрисовка опций выпадающего списка (реэкспортированная директива ng-select). | <ng-template ng-option-tmp let-item="item">…</ng-template> |
hubFileIcon (hub-file-input) | Значок файла для файлов без миниатюры; получает элемент как неявный контекст. | <ng-template hubFileIcon let-item>…</ng-template> |
hubFilePreview (hub-file-input) | Полностью заменяет отображение выбранного файла, получая элемент и действия удаления, повтора и отмены. | <ng-template hubFilePreview let-item let-remove="remove">…</ng-template> |
hubFileDropzoneNotice (hub-file-input) | Проецирует произвольную разметку в верхнюю часть зоны перетаскивания, над значком — для сообщения, которое не выразить ни приглашением, ни подсказкой об ограничениях. | <p hubFileDropzoneNotice>2 documents still missing</p> |
hubSegmentedOption (hub-segmented) | Заменяет содержимое каждого сегмента (иконки, бейджи, богатую разметку), при этом компонент по-прежнему управляет выбором, навигацией с клавиатуры и ARIA. Контекст: опция (неявно), selected и index. | <ng-template hubSegmentedOption let-option let-selected="selected" let-index="index">…</ng-template> |
hubSelectSuffix (hub-select, устарело) | Устарело с 22.16.0 — используйте [hubAppend], который делает то же самое в любом поле. Он продолжает работать; при наличии обоих побеждает [hubAppend]. Прикрепляет интерактивный элемент к конечному краю select — кнопку, которая действует на выбранное: настроить, посмотреть, создать новое. Объявляется шаблоном, а не проецируемым содержимым, потому что универсальный ng-content самого select передаёт ng-option движку и попросту проглотил бы её; отрисовка из шаблона к тому же оставляет действие после контрола в DOM, так что табуляция сначала попадает в поле, а затем на кнопку. Контрол и действие делят одну рамку и читаются как единое поле. | <ng-template hubSelectSuffix><button …>…</button></ng-template> |
hubPrepend / hubAppend (all box-shaped fields) | Содержимое, прикреплённое к краю поля и более богатое, чем текст в строке prepend / append: иконка или кнопка, действующая на значение. Доступно у каждого поля, которое выглядит как коробка со значением — hub-input, hub-select, hub-textarea и hub-datepicker. Оно дополняет строковые аддоны, а не заменяет их: строки отрисовываются первыми, поэтому проецируемое содержимое всегда остаётся крайним со своей стороны — единица подписывает поле, а действие стоит за ней. Проецируемое берёт рамку, скругление и высоту поля, а не свои собственные, так что кнопка не рисует второй, более толстый шов рядом с контролом. Объявляется шаблоном, потому что ng-content поля уже занят. Слот может принять и другое поле — hub-input, hub-select, hub-textarea или hub-datepicker как непосредственный дочерний элемент, — которое смыкается с полем-хозяином вплотную, чтобы цена и период, за который она берётся, читались как одно утверждение, которым они и являются. | <ng-template hubAppend><button …><hub-icon … /></button></ng-template> |