Input Group 输入组

为输入框添加图标、文字或按钮。由输入组绘制边框，并在内部输入框聚焦时显示焦点环；点按附加区会聚焦输入框。

基础用法

SInputGroup() {
  SInputGroupAddon() { SIcon({ name: 'search' }) }
  SInputGroupInput({ placeholder: 'Search…' })
  SInputGroupAddon({ alignment: 'inline-end' }) {
    SInputGroupText({ text: '12 results' })
  }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

文字

用 SInputGroupText 添加前缀与后缀。

SInputGroup() {
  SInputGroupAddon() { SInputGroupText({ text: 'https://' }) }
  SInputGroupInput({ placeholder: 'example.com' })
  SInputGroupAddon({ alignment: 'inline-end' }) { SInputGroupText({ text: '.com' }) }
}
SInputGroup() {
  SInputGroupAddon() { SInputGroupText({ text: '$' }) }
  SInputGroupInput({ placeholder: '0.00', inputType: 'number' })
  SInputGroupAddon({ alignment: 'inline-end' }) { SInputGroupText({ text: 'USD' }) }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

按钮

输入框内的紧凑按钮（xs、sm、icon-xs、icon-sm）。

@Local url: string = 'https://sparkui.dev';

SInputGroup() {
  SInputGroupInput({ value: this.url!! })
  SInputGroupAddon({ alignment: 'inline-end' }) {
    SInputGroupButton({ icon: 'copy', sizing: 'icon-xs', label: 'Copy' })
      .onClick(() => this.copied = true)
  }
}
SInputGroup() {
  SInputGroupInput({ placeholder: 'Type to search…' })
  SInputGroupAddon({ alignment: 'inline-end' }) {
    SInputGroupButton({ text: 'Search', variant: 'secondary' })
  }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

块级附加区与校验失败

block-start / block-end 占满整行宽度。

SInputGroup() {
  SInputGroupAddon({ alignment: 'block-start' }) {
    SInputGroupText({ icon: 'file-text', text: 'script.ts' })
  }
  SInputGroupInput({ placeholder: 'console.log("Hello")' })
  SInputGroupAddon({ alignment: 'block-end' }) {
    SInputGroupText({ text: 'Line 1, Column 1' })
  }
}
SInputGroup({ invalid: true }) {
  SInputGroupAddon() { SIcon({ name: 'mail' }) }
  SInputGroupInput({ placeholder: 'Email' })
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SInputGroup

shadcn-vue 的 InputGroup（v4）：一个带边框的字段，内含输入框以及附加内容（图标、文字、按钮）。输入框获得焦点时，分组会绘制边框与焦点环（has-[:focus]:border-ring ring-ring/50 ring-[3px]）。

请按视觉顺序编写各部分：ArkUI 无法对插槽子组件重新排序（order-first / order-last）。块级附加内容（block-start / block-end）会占满整行，并位于输入框上方 / 下方单独一行。点按附加内容会使输入框获得焦点。

属性	类型	默认值	说明
invalid	boolean	false
disabled	boolean	false
modifier	AttributeModifier<FlexAttribute>	new SparkNoopModifier<FlexAttribute>()

插槽: 子组件（尾随闭包）

SInputGroupAddon

附加内容区域：text-muted-foreground flex items-center gap-2 py-1.5 text-sm font-medium；行内起始侧为 pl-3，行内结束侧为 pr-3，块级起始 / 结束则为占满宽度的 px-3 pt-3 / px-3 pb-3。点按它会使分组中的输入框获得焦点。

属性	类型	默认值	说明
alignment	InputGroupAddonAlignment InputGroupAddonAlignment = 'inline-start' | 'inline-end' | 'block-start' | 'block-end'	'inline-start'

插槽: 子组件（尾随闭包）

SInputGroupText

附加内容中的弱化文字 / 图标：text-muted-foreground flex items-center gap-2 text-sm。

属性	类型	默认值	说明
text	ResourceStr | undefined	undefined
icon	string | undefined	undefined	前导 lucide 图标（16vp）。

插槽: 子组件（尾随闭包）

SInputGroupButton

附加内容使用的紧凑按钮：shadcn 的 InputGroupButton（shadow-none，尺寸 xs 为 h-6 px-2，sm 为 h-8 px-2.5，icon-xs 为 size-6，icon-sm 为 size-8；默认变体为 ghost）。点击：直接在组件上使用原生 .onClick()。

属性	类型	默认值	说明
text	ResourceStr | undefined	undefined
icon	string | undefined	undefined	前导 lucide 图标名称。
variant	ButtonVariant ButtonVariant = 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'	'ghost'
sizing	InputGroupButtonSize InputGroupButtonSize = 'xs' | 'sm' | 'icon-xs' | 'icon-sm'	'xs'
disabled	boolean	false
label	string | undefined	undefined	无障碍名称；纯图标按钮必须设置。

SInputGroupInput

分组中的文本控件：采用 SInput 样式的 TextInput，本身没有边框 / 焦点环（flex-1 rounded-none border-0 bg-transparent shadow-none）。与 SInput 的值 API 相同。

属性	类型	默认值	说明
value!!	string | undefined	undefined	受控值（配合 !! 使用）。留空则为非受控。
defaultValue	string	''
placeholder	ResourceStr	''
inputType	InputKind InputKind = 'text' | 'password' | 'email' | 'number'	'text'
maxLength	number | undefined	undefined
label	string | undefined	undefined	没有可见标签时使用的无障碍名称。
modifier	AttributeModifier<TextInputAttribute>	new SparkNoopModifier<TextInputAttribute>()

事件	类型	默认值	说明
onValueChange	(v: string) => void	() => { }
onSubmit	(v: string) => void	() => { }