API 参考

这里是 forms 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。

输入

通过 14 个输入项精细调校 forms。像绑定任意 Angular @Input 一样绑定它们。

名称	类型	默认值	描述
`formControlName / [formControl]`	`string \| FormControl`	—	将任意字段绑定到响应式控件。当控件被触碰且无效时自动显示错误。
`label`	`string`	`''`	字段标签文本。
`labelType`	`'stacked' \| 'floating' \| 'horizontal'`	`'stacked'`	标签位置。
`placeholder`	`string`	`''`	占位符文本。
`formText`	`string`	—	显示在控件下方的辅助文本。
`type (hub-input)`	`'text' \| 'number' \| 'password' \| 'email' \| 'tel' \| 'url' \| 'color' \| 'checkbox' \| 'switch' \| 'counter' \| 'file'`	`'text'`	hub-input 的格式。
`prepend / append (hub-input)`	`string \| string[]`	—	控件前/后的输入组附加文本。
`mask (hub-input)`	`string`	—	文本格式的模式掩码。标记：0 = 数字，A = 字母，* = 字母或数字；其他字符为字面分隔符。例如 "0000 0000 0000 0000"。
`unmaskValue (hub-input)`	`boolean`	`false`	设置掩码后，在表单中存储原始输入的字符（无分隔符），而非格式化后的文本。
`range (hub-slider)`	`boolean`	`false`	双滑块范围选择器；值变为 [lower, upper] 元组。
`format (hub-select)`	`'dropdown' \| 'buttons' \| 'checkbox' \| 'radio'`	`'dropdown'`	select 渲染相同值的方式。
`items / bindLabel / bindValue / multiple (hub-select)`	`any[] / string / string / boolean`	—	选项、对象项的 label/value 属性名，以及多选设置。
`mode (hub-datepicker)`	`'single' \| 'range'`	`'single'`	单个日期或日期范围。
`min / max / disabledDates (hub-datepicker)`	`string \| Date / (date) => boolean`	—	可选日期的边界以及逐日期的禁用判定函数。

输出

响应 forms 的行为——有 4 个事件可供你挂接逻辑。

名称	类型	描述
`valueChange`	`EventEmitter<value>`	每当字段值变化时触发。
`submit (form[hubForm])`	`EventEmitter<void>`	在提交时触发，此时整个树已被标记为已触碰。
`opened / closed / cleared / viewChange (hub-datepicker)`	`EventEmitter`	日历生命周期和导航事件。
`onOpen / onClose / onClear / onSearch / onAdd / onRemove (hub-select)`	`EventEmitter`	下拉框生命周期以及标签/自动补全事件。

模板

打造你自己的样式——4 个模板插槽让你可以投影自定义标记。

名称	描述	示例
`hubFormText`	投影丰富的辅助文本内容。	`<ng-template hubFormText>…</ng-template>`
`hubValidationError`	覆盖指定错误键的提示消息。	`<ng-template hubValidationError key="min">…</ng-template>`
`hubLegend`	自定义 fieldset 的 legend 内容。	`<ng-template hubLegend>…</ng-template>`
`ng-option-tmp (hub-select)`	自定义下拉选项渲染（重新导出的 ng-select 指令）。	`<ng-template ng-option-tmp let-item="item">…</ng-template>`

CSS 变量

用 17 个 CSS 变量为每一个像素设置主题。在 :root 处覆盖它们，或将其限定到某个容器范围内。

共享字段令牌

每个字段共享的外观：标签、帮助文本、验证反馈和聚焦环。

变量	默认值	类型	描述
`--hub-label-font-weight`	`var(--hub-ref-font-weight-medium)`	string	字段标签的字重。
`--hub-form-feedback-color`	`var(--hub-sys-color-danger)`	color	验证错误文本颜色。
`--hub-form-text-color`	`var(--hub-sys-text-muted)`	color	帮助文本颜色。
`--hub-form-focus-ring-color`	`var(--hub-sys-focus-ring-color)`	color	聚焦环颜色。
`--hub-form-invalid-border-color`	`var(--hub-sys-color-danger)`	color	无效控件的边框颜色。

Input

input、textarea 和 select 触发器共享的文本控件外观。

变量	默认值	类型	描述
`--hub-input-bg`	`var(--hub-sys-surface-page)`	color	控件背景。
`--hub-input-border-color`	`var(--hub-sys-border-color-default)`	color	控件边框颜色。
`--hub-input-border-radius`	`var(--hub-ref-radius-md)`	length	控件边框半径。
`--hub-input-padding-y`	`0.375rem`	length	控件垂直内边距。
`--hub-input-padding-x`	`0.75rem`	length	控件水平内边距。
`--hub-input-focus-border-color`	`var(--hub-sys-color-primary)`	color	聚焦时的边框颜色。

Select、slider 和 datepicker

链接到系统令牌的组件专属强调色。

变量	默认值	类型	描述
`--hub-select-option-selected-bg`	`var(--hub-sys-color-primary)`	color	选中的下拉选项背景。
`--hub-select-value-bg`	`var(--hub-sys-surface-elevated)`	color	多选标签的背景。
`--hub-slider-track-fill-bg`	`var(--hub-sys-color-primary)`	color	slider 轨道的已填充部分。
`--hub-slider-thumb-bg`	`var(--hub-sys-color-primary)`	color	slider 滑块的颜色。
`--hub-daterangepicker-active-bg`	`var(--hub-sys-color-primary)`	color	选中的日历日期背景。
`--hub-daterangepicker-in-range-bg`	`color-mix(in srgb, var(--hub-sys-color-primary) 14%, transparent)`	color	范围内日历日期的背景。

样式与主题

尚未记录任何样式示例。本节将包含自定义方案和主题示例。