简体中文
InputGroup 输入组
用于在同一输入表面中组合前缀、输入控件和后缀。
用法
为输入框添加固定前缀
组件结构
加粗的是必需部件。
data-scope="input-group"：root · item
示例
动作
将关联操作放在输入框末端
变体
outline 画描边输入面，subtle 用淡底嵌入已有表面
¥
¥
文本前后缀
添加协议和域名后缀
https://
.dev
设计指引
何时使用
- 输入框需要图标、单位或固定文本。
- 输入框需要紧邻的搜索、复制或提交动作。
何时不用
- 组合并列操作时，使用按钮组。
- 仅排列控件时，使用布局组件。
特性
- 所有内容共享一个背景与外轮廓，聚焦时整组换成承载面与聚焦描边。
- 支持
outline、subtle与ghost三种形态，与组内字段同一套词。 - 前后缀不参与交互，控件保留自身语义。
- 支持
sm、md和lg三种尺寸。
组合
最佳实践
- 前后缀保持简短，并使用静态内容。
- 可交互内容使用对应控件，不要放进
item。 - 组内控件使用相同尺寸。
反模式
- 使用过多前后缀，让输入区域难以识别。
- 用
item承载按钮或链接。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-input-group> |
| Vue 组件 | XhInputGroupItem XhInputGroupRoot |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/input-group.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
size | Size | 尺寸：sm / md / lg，写入根上供皮肤填入 item 的高度、内衬与字号槽位。 未提供时档位由组内控件自身的 data-size 决定，组内没有带档位的控件时使用 md。 | |
variant | ControlVariant | 形态：outline / subtle / ghost，与组内字段同一套词。默认 outline。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
getRootProps | () => T['element'] | |
getItemProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
样式参考
皮肤
@xihan-ui/styles/input-group.css 按 [data-scope="input-group"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-input-group 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。
forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-size | props.size |
root | data-variant | props.variant |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-input-group-bg | root | background | default | --xh-_input-group-bg | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-bg-disabled | root | background | disabledhas([data-xh-field-chrome][data-disabled])xh-field-chrome | --xh-bg-subtle | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-bg-focus | root | background | focus-within | --xh-_input-group-bg-focus | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-bg-hover | root | background | disabledhoverinvalidnot(:focus-within)not(:has([data-xh-field-chrome]:is([data-disabled], [data-readonly])readonlyxh-field-chrome | --xh-_input-group-bg-hover | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-bg-invalid | root | background | has([data-invalid], [aria-invalid='true'])invalid | --xh-bg-field-invalid | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-bg-read-only | root | background | has(:where([data-xh-field-chrome][data-readonly])readonlyxh-field-chrome | --xh-bg-subtle | input-group 的 root 部件 background 覆盖槽。 |
--xh-input-group-border | root | border | default | --xh-_input-group-border | input-group 的 root 部件 border 覆盖槽。 |
--xh-input-group-border-disabled | root | border-color | disabledhas([data-xh-field-chrome][data-disabled])xh-field-chrome | --xh-border-default | input-group 的 root 部件 border-color 覆盖槽。 |
--xh-input-group-border-focus | root | border-colorbox-shadow | focus-within | --xh-_input-group-border-focus | input-group 的 root 部件 border-color、box-shadow 覆盖槽。 |
--xh-input-group-border-hover | root | border-color | disabledhoverinvalidnot(:focus-within)not(:has([data-xh-field-chrome]:is([data-disabled], [data-readonly])readonlyxh-field-chrome | --xh-_input-group-border-hover | input-group 的 root 部件 border-color 覆盖槽。 |
--xh-input-group-border-invalid | root | border-color | has([data-invalid], [aria-invalid='true'])invalid | --xh-border-invalid | input-group 的 root 部件 border-color 覆盖槽。 |
--xh-input-group-item-bg | item | background-color | default | --xh-bg-subtle | input-group 的 item 部件 background-color 覆盖槽。 |
--xh-input-group-item-divider | itemroot | border-inline-endborder-inline-start | not(:first-child)not(:has(+ [data-scope='input-group'][data-part='item'])not(:last-child) | --xh-border-default | input-group 的 item、root 部件 border-inline-end、border-inline-start 覆盖槽。 |
--xh-input-group-item-fg | item | color | default | --xh-fg-default | input-group 的 item 部件 color 覆盖槽。 |
--xh-input-group-item-font-size | item | font-size | default | --xh-_input-group-font-size | input-group 的 item 部件 font-size 覆盖槽。 |
--xh-input-group-item-h | item | block-size | default | --xh-_input-group-h | input-group 的 item 部件 block-size 覆盖槽。 |
--xh-input-group-item-px | item | padding-inline | default | --xh-_input-group-px | input-group 的 item 部件 padding-inline 覆盖槽。 |
--xh-input-group-radius | controlroot | border-end-end-radiusborder-end-start-radiusborder-radiusborder-start-end-radiusborder-start-start-radius | defaultfirst-childis(*, [data-part='control'], [data-part='root'])is([data-part='control'], [data-part='root'])last-child | --xh-shape-control | input-group 的 control、root 部件 border-end-end-radius、border-end-start-radius、border-radius、border-start-end-radius、border-start-start-radius 覆盖槽。 |
--xh-input-group-shadow | root | box-shadow | default | --xh-_input-group-shadow | input-group 的 root 部件 box-shadow 覆盖槽。 |
--xh-input-group-w | root | inline-size | default | --xh-control-w | input-group 的 root 部件 inline-size 覆盖槽。 |
动效
动效角色：状态（见动效规范）。
background-color · border-color 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。