Библиотека форм для Angular | ng-hub-ui-forms

Доступные поля форм для Angular (input, textarea, slider, select, datepicker) с автоматическим выводом ошибок на уровне контрола, группы и формы, реактивными формами и CSS-переменными.

Справочник API

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

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

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

ИмяТипПо умолчаниюОписание
formControlName / [formControl]string | FormControlПривязывает любое поле к реактивному контролу. Ошибки отображаются автоматически, когда контрол был затронут (touched) и недействителен.
labelstring''Текст метки поля.
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.
formTextstringВспомогательный текст, отображаемый под контролом.
type (hub-input) — file is deprecated'text' | 'number' | 'password' | 'email' | 'tel' | 'url' | 'color' | 'checkbox' | 'switch' | 'counter' | 'file''text'Формат hub-input.
passwordRevealed (hub-input)booleanfalseДвунаправленное состояние видимости поля пароля. Нажатие на кнопку с иконкой глаза обновляет его; установка значения показывает или скрывает пароль.
passwordToggle (hub-input)booleantrueОтображается ли встроенная кнопка показа/скрытия пароля в полях пароля.
hideOnBlur (hub-input)booleantrueСкрывается ли показанный пароль автоматически, когда фокус покидает поле.
capsLockWarning (hub-input)booleantrueОтображается ли подсказка под полем, пока активен Caps Lock.
passwordStrength (hub-input)booleanfalseОтображает необязательный индикатор надёжности пароля из 4 сегментов под полем. Логику оценки можно переопределить через provideHubForms.
autocomplete (hub-input)string''Нативный атрибут autocomplete, например current-password или new-password для менеджеров паролей.
clearable (hub-input)booleanfalseЕсли true, показывает встроенную кнопку ✕ при наличии значения; очищает контрол и отправляет пустой поисковый запрос.
debounceTime (hub-input)number0Задержка в миллисекундах перед срабатыванием события search (0 — при каждом нажатии).
mask (hub-input)stringМаска шаблона для текстовых форматов. Токены: 0 = цифра, A = буква, * = буквенно-цифровой символ; остальные символы являются буквальными разделителями. Например, "0000 0000 0000 0000".
unmaskValue (hub-input)booleanfalseПри заданной маске сохранять в форме необработанные введённые символы (без разделителей) вместо форматированного текста.
range (hub-slider)booleanfalseПолзунок диапазона с двумя бегунками; значение становится кортежем [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)booleanfalseРазрешить выбор нескольких вариантов; значение становится массивом, кнопки переключаются (aria-pressed).
vertical (hub-segmented)booleanfalseРасполагать сегменты вертикально, а не в горизонтальный ряд.
vertical (hub-select) — deprecatedbooleanfalseУстарело и связано с устаревшими форматами, отличными от 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 | undefinedundefinedИмя свойства (путь в точечной нотации), по которому элементы dropdown группируются под заголовками групп опций.
searchable / clearable (hub-select)booleantrueМожно ли фильтровать опции вводом текста (searchable) и можно ли очистить выбор встроенной кнопкой очистки (clearable). По умолчанию оба равны true.
closeOnSelect (hub-select)booleantrueЗакрывается ли dropdown после выбора элемента. Установите false, чтобы он оставался открытым при выборе нескольких значений в режиме multiple.
fixedPlaceholder (hub-select)booleanfalseОставляет placeholder видимым даже после выбора значения. По умолчанию false (placeholder скрывается при выборе), что инвертирует нестандартное значение по умолчанию из ng-select v23.
loading / notFoundText (hub-select)boolean / stringfalse / NgSelectConfig.notFoundTextloading отображает состояние загрузки dropdown, пока асинхронные элементы загружаются; notFoundText — сообщение, показываемое, когда ни один элемент не соответствует поисковому запросу.
readonly (hub-input, hub-select, hub-textarea, hub-datepicker, hub-otp-input, hub-timepicker)booleanfalseЕсли 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)stringNgSelectConfig.addTagTextПодпись строки «добавить элемент», отображаемой при вводе, когда включён addTag.
minTermLength (hub-select)number0Минимальная длина поискового запроса, после которой срабатывает фильтрация (или Subject для typeahead).
typeahead (hub-select)Subject<string> | undefinedundefinedSubject, получающий изменения поискового запроса для асинхронной/серверной загрузки; если он задан, клиентская фильтрация отключается — верните результаты через items.
compareWith (hub-select)((a: any, b: any) => boolean) | undefinedundefinedСобственное сравнение элемента со связанным значением (например, объекты по id); если не задано, применяется встроенное сравнение поставщика.
searchFn (hub-select)((term: string, item: any) => boolean) | undefinedundefinedЗаменяет встроенное сопоставление, которое использует `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' | undefined5 / 1 / undefinedНастройки времени: minuteStep и secondStep — шаг спинбаттонов, а hourFormat принудительно задаёт 12- или 24-часовой формат; если не указан, выводится из локали и применяется как к отображению поля, так и к панели, чтобы они никогда не противоречили друг другу. Все три опираются на глобальную конфигурацию provideHubForms.
min / max / disabledDates (hub-datepicker)string | Date | number | null / ((date: Date) => boolean) | nullnullГраницы выбора и предикат отключения отдельных дат. Границы учитывают время, а не только день: день отключается лишь тогда, когда ни один его момент не разрешён, поэтому min = 2026-09-01T14:00 оставляет 1 сентября кликабельным, а более ранние часы отклоняют уже элементы выбора времени. Принимает ISO-строку, Date или миллисекунды эпохи.
locale / firstDayOfWeek / weekdayFormat (hub-datepicker)string / number / 'short' | 'narrow' | 'long'LOCALE_ID / undefined / undefinedi18n календаря: 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)booleantrue / true / trueФлаги поведения: clearable показывает кнопку очистки, showToday показывает кнопку «сегодня», а closeOnSelect закрывает календарь после выбора даты (только в одиночном режиме). По умолчанию: true / true / true.
multiple (hub-file-input)booleanfalseМожно ли хранить более одного файла. Меняет значение контрола с File на File[].
accept (hub-file-input)string'*'Допустимые типы файлов, например image/*,.pdf. Применяется и при перетаскивании и вставке, а не только в системном диалоге.
maxSize / minSize / maxTotalSize (hub-file-input)number | nullnullМаксимальный и минимальный размер одного файла и максимальный суммарный размер, в байтах.
maxFiles (hub-file-input)number | nullnullМаксимальное число файлов. Имеет смысл только вместе с multiple.
dragDrop / paste (hub-file-input)booleantrueМожно ли перетаскивать файлы на поле и вставлять их в него.
preview (hub-file-input)'none' | 'list' | 'grid''list'Как отображаются файлы: никак, списком или сеткой миниатюр.
allowDuplicates (hub-file-input)booleanfalseМожно ли выбрать один и тот же файл дважды (ключ: имя, размер и дата изменения).
capture (hub-file-input)'user' | 'environment' | nullnullОткрывает камеру устройства вместо файлового менеджера на поддерживаемых платформах.
autoUpload (hub-file-input)booleantrueНачинает ли только что принятый файл загружаться сразу. Игнорируется без зарегистрированного загрузчика.
buttonLabel / hint (hub-file-input)string | nullnullПереопределяет текст кнопки выбора и автоматически создаваемую подсказку об ограничениях.
dropText / dropSubtext (hub-file-input)string | nullnullПереопределение двух строк приглашения зоны перетаскивания для конкретного экземпляра. Обе по умолчанию берутся из глобальных подписей.
classlist (every field except hub-segmented and hub-legend)string''Дополнительные CSS-классы для хост-элемента.
showValid (all fields)booleanHubFormsConfig.showValidПоказывает ли действительное поле своё состояние валидности. По умолчанию выключено, потому что форма, которая красит зелёным каждое нетронутое поле, ни о чём не говорит; недопустимое состояние отображается всегда.
validFeedback (all fields)string | nullnullСообщение, отображаемое под полем, когда оно стало действительным, при включённом `showValid`.
invalidFeedbackTemplateFn (all fields)((key: string, value: any) => string) | nullnullПереопределяет сообщение для заданного ключа ошибки только в этом поле. Получает ключ ошибки и его значение и возвращает текст — значение по умолчанию для всего приложения задаётся в `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 | undefinednull / 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 событий, к которым можно подключить вашу логику.

ИмяТипОписание
valueChangeEventEmitter<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 eventSubmitEvent (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>