shadcn-vue InputGroup 组件完全指南：为输入框与文本域构建前缀、后缀与操作区

shadcn-vue InputGroup 组件完全指南为输入框与文本域构建前缀、后缀与操作区【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vueInputGroup 是 shadcn-vue 中用于在Input /、Textarea /等输入控件周围挂载图标、文字、按钮、Tooltip、Dropdown 等附加内容的容器组件帮助开发者快速搭建搜索框、金额输入、消息发送等复合交互表单。阅读本篇后你将掌握 InputGroup 全家桶InputGroup、InputGroupAddon、InputGroupButton、InputGroupInput、InputGroupText、InputGroupTextarea的安装方式、对齐规则、焦点态机制与全部示例用法并理解其基于data-slot与 CSShas()选择器的底层实现原理。组件概览一个容器、五个零件InputGroup 采用容器 插槽的组合式设计。官方文档将其定位为向 input 或 textarea 展示附加信息或操作由以下六个组件构成组件职责InputGroup主容器包裹输入控件与所有附加内容InputGroupAddon附加内容容器承载图标、文字、按钮等InputGroupButton组内专用按钮尺寸与外观有专门优化InputGroupInput输入框Input 的组内变体样式预置InputGroupText静态文本如前缀$、单位pxInputGroupTextarea文本域Textarea 的组内变体样式预置在仓库中这些组件的完整源码位于 deprecated/www/src/registry/default/ui/input-group类型与 CVA 变体定义集中在 index.ts对应的交互示例位于 deprecated/www/src/registry/default/examples如InputGroupDemo.vue、InputGroupWithButton.vue等十余个示例。文档页本身引用的是 v4 应用中的同名示例组件 apps/v4/components/demo 目录。安装方式一CLI 一键添加推荐在项目根目录执行npx shadcn-vuelatest add input-group命令会自动把上述六个组件文件index.ts、InputGroup.vue、InputGroupAddon.vue、InputGroupButton.vue、InputGroupInput.vue、InputGroupText.vue、InputGroupTextarea.vue复制到项目的components/ui/input-group目录并解析其依赖如基础button、input、textarea组件与cn工具函数。方式二手动复制手动方式需要按文档列出的文件清单逐一复制通常包括index.ts—— 统一导出与 CVA 变体定义InputGroup.vueInputGroupAddon.vueInputGroupButton.vueInputGroupInput.vueInputGroupText.vueInputGroupTextarea.vue提示InputGroupButton依赖基础Button组件InputGroupInput依赖基础InputInputGroupTextarea依赖基础Textarea手动安装前需确认这些依赖已就绪。实际文件内容以仓库 deprecated/www/src/registry/default/ui/input-group 为准。基本用法在script setup中按需引入后即可组合使用script setup langts import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, } from /components/ui/input-group /script template InputGroup InputGroupInput placeholderSearch... / InputGroupAddon SearchIcon / /InputGroupAddon InputGroupAddon aligninline-end InputGroupButtonSearch/InputGroupButton /InputGroupAddon /InputGroup /template上面的例子展示了三种典型元素输入框、图标加号、尾部的操作按钮。注意align属性控制附加内容出现在哪一侧——默认inline-start左侧。对齐规则inline 与 block 两套坐标系InputGroup 支持四种对齐方向由InputGroupAddon的align属性控制对齐值适用场景说明inline-start默认InputGroupInput附加内容位于行首左/侧取决于书写方向inline-endInputGroupInput附加内容位于行尾右侧block-startInputGroupTextarea附加内容位于块首上方block-endInputGroupTextarea附加内容位于块尾下方规则给InputGroupInput /用inline-start/inline-end给InputGroupTextarea /用block-start/block-end。这是因为文本域需要上下分布的附加区如底部发送按钮而单行输入框则适合左右分布。从源码看这个规则并非简单的建议InputGroup.vue中通过has-[[data-align...]]选择器根据子元素上的data-align属性动态切换容器布局——block-start/block-end会触发flex-col纵向排布并调整内边距而inline-*则保持横向排布见 InputGroup.vue。对齐的底层实现InputGroupAddon组件将align透传为data-align属性并通过 CVA 生成对应样式类// deprecated/www/src/registry/default/ui/input-group/index.ts export const inputGroupAddonVariants cva( text-muted-foreground flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium select-none ..., { variants: { align: { inline-start: order-first pl-3 has-[button]:ml-[-0.45rem] has-[kbd]:ml-[-0.35rem], inline-end: order-last pr-3 has-[button]:mr-[-0.45rem] has-[kbd]:mr-[-0.35rem], block-start: order-first w-full justify-start px-3 pt-3 ..., block-end: order-last w-full justify-start px-3 pb-3 ..., }, }, defaultVariants: { align: inline-start }, }, )可以看出inline-*通过order-first/order-last在横向 flex 中定位block-*则切换为w-full的纵向占位并针对button、kbd做了负边距微调使组内按钮视觉上与容器边框贴合。焦点态与点击聚焦机制InputGroup 一个关键特性是统一的焦点态处理组内所有输入控件无论InputGroupInput、InputGroupTextarea还是自定义输入都带有data-slotinput-group-control标记InputGroup.vue据此用has-[[data-slotinput-group-control]:focus-visible]在容器上绘制ring焦点环见 InputGroup.vue。这意味着开发者无需在每个输入控件上单独处理 focus 样式焦点环始终渲染在容器边框上视觉统一。另外InputGroupAddon内置了点击聚焦逻辑点击附加区只要不是点击内部按钮会自动把焦点移回组内的input元素提升可访问性见 InputGroupAddon.vue。示例详解图标Icon在输入框侧边放置图标是最常见的用法InputGroup InputGroupInput placeholderSearch... / InputGroupAddon SearchIcon / /InputGroupAddon /InputGroup文本Text在输入框旁展示静态文本信息如货币符号、单位、协议提示InputGroup InputGroupAddon InputGroupTexthttps:///InputGroupText /InputGroupAddon InputGroupInput placeholderexample.com / /InputGroupInputGroupText内部是一个span默认使用text-muted-foreground前景色并对内部 SVG 图标做了尺寸规整见 InputGroupText.vue。按钮Button在输入组内执行动作例如搜索、复制、清空InputGroup InputGroupInput placeholderSearch... / InputGroupAddon aligninline-end InputGroupButtonSearch/InputGroupButton /InputGroupAddon /InputGroupInputGroupButton默认sizexs、variantghost与普通 Button 相比高度更紧凑h-6专为组内场景优化。可同时放置多个按钮InputGroupAddon InputGroupButtonButton/InputGroupButton InputGroupButtonButton/InputGroupButton /InputGroupAddon也可以混排按钮与图标icon-xs尺寸配合aria-label保证可访问性InputGroupButtonButton/InputGroupButton InputGroupButton sizeicon-xs aria-labelCopy CopyIcon / /InputGroupButtonTooltip借助 Tooltip 为输入组提供上下文提示例如解释某个字段的含义或校验规则。InputGroupAddon可容纳任意内容将 Tooltip 触发器包裹其中即可官方示例见 apps/v4/components/demo/InputGroupWithTooltip.vue。Textarea文本域输入组同样适用于文本域使用block-start/block-end对齐InputGroup InputGroupTextarea placeholderEnter message... / InputGroupAddon alignblock-end InputGroupButtonSend/InputGroupButton /InputGroupAddon /InputGroupInputGroup.vue通过has-[textarea]:h-auto自动让容器高度随文本域内容伸缩见 InputGroup.vue。Spinner加载指示器在输入处理过程中如表单提交、异步校验展示加载状态将 Spinner 放入 Addon 即可官方示例见 apps/v4/components/demo/InputGroupWithSpinner.vue。Label标签在输入组内添加标签以提升表单可访问性将 Label 与输入控件一同放入容器InputGroup InputGroupAddon Label foremailEmail/Label /InputGroupAddon InputGroupInput idemail typeemail placeholderyouexample.com / /InputGroupDropdown下拉菜单输入组与下拉菜单组合可承载选择分类 搜索这类复杂交互官方示例见 apps/v4/components/demo/InputGroupWithDropdown.vue。Button Group按钮组用按钮组包裹输入组可以构造前缀/后缀式组合控件如金额的加减、分页器的页码跳转官方示例见 apps/v4/components/demo/InputGroupWithButtonGroup.vue。自定义输入Custom Input除了内置的InputGroupInput/InputGroupTextarea任何自定义输入控件只要带上data-slotinput-group-control属性即可自动获得焦点态处理与布局适配。官方示例是一个可自动伸缩高度的 textarea见 apps/v4/components/demo/InputGroupWithCustomInput.vuescript langts setup import { InputGroup, InputGroupAddon, InputGroupButton } from /registry/default/ui/input-group /script template div classgrid w-full max-w-sm gap-6 InputGroup textarea >template InputGroup InputGroupInput / InputGroupAddon / /InputGroup /template容器渲染为带data-slotinput-group、rolegroup的div默认高度h-10、圆角rounded-md、1px 边框当内部存在 textarea 时自动切换为自适应高度见 InputGroup.vue。InputGroupAddon在输入控件旁展示图标、文本、按钮等任意内容。提示为了正确的焦点导航InputGroupAddon应放置在输入控件之后通过align属性控制其显示位置。Prop类型默认值aligninline-start \| inline-end \| block-start \| block-endinline-startclassstring—InputGroupAddon aligninline-end SearchIcon / /InputGroupAddon对InputGroupInput使用inline-start/inline-end对InputGroupTextarea使用block-start/block-end一个 Addon 内可以包含多个InputGroupButton与图标点击非按钮区域会自动聚焦组内输入框见 InputGroupAddon.vue。InputGroupButton输入组内的专用按钮。Prop类型默认值sizexs \| icon-xs \| sm \| icon-smxsvariantdefault \| destructive \| outline \| secondary \| ghost \| linkghostclassstring—template InputGroupButtonButton/InputGroupButton InputGroupButton sizeicon-xs aria-labelCopy CopyIcon / /InputGroupButton /template其尺寸/变体基于inputGroupButtonVariants的 CVA 定义xs为h-6、icon-xs为size-6等见 index.ts并复用基础Button组件的variant体系。InputGroupInput构建输入组时的Input /替代品组内样式已预置并使用统一的data-slotinput-group-control处理焦点态。Prop类型默认值classstring—其余 props 全部透传给底层Input /组件。template InputGroup InputGroupInput placeholderEnter text... / InputGroupAddon SearchIcon / /InputGroupAddon /InputGroup /template源码实现上InputGroupInput就是一层薄封装为Input追加data-slotinput-group-control并移除自身边框、圆角、focus ringborder-0 rounded-none bg-transparent focus-visible:ring-0让容器统一承担外观见 InputGroupInput.vue。InputGroupTextarea构建输入组时的Textarea /替代品同样预置组内样式并使用统一data-slot约定。Prop类型默认值classstring—其余 props 全部透传给底层Textarea /组件。template InputGroup InputGroupTextarea placeholderEnter message... / InputGroupAddon alignblock-end InputGroupButtonSend/InputGroupButton /InputGroupAddon /InputGroup /templateInputGroupTextarea与InputGroupInput的封装策略一致resize-none border-0 bg-transparent将外观职责交给容器见 InputGroupTextarea.vue。最佳实践小结遵循对齐约定单行输入用inline-*多行文本域用block-*保证布局与焦点行为正确Addon 放在输入控件之后文档明确要求如此排列以支持点击聚焦与键盘导航优先使用InputGroupInput/InputGroupTextarea它们已剥离重复样式并接入统一焦点环避免与容器边框冲突自定义控件记得打上data-slotinput-group-control这是获得自动行为与焦点态处理的契约入口善用按钮尺寸默认xs/ghost适合紧凑场景sm/default适合主操作按钮图标按钮用icon-xs/icon-sm并补充aria-label。【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址: https://gitcode.com/gh_mirrors/sh/shadcn-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考