shadcn-vue Item 组件完全指南：用十个原子组件快速搭建内容列表与卡片

UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载Item 是 shadcn-vue 中一个小而美的布局原子组件它以 flex 容器为骨架配合标题、描述、媒体、操作区等十个子组件就能快速拼装出通知行、设置项、用户列表、数据卡片等常见 UI 块。本文基于官方文档并结合仓库内 Item 源码目录 与 官方演示组件完整讲解安装、组合方式、每个子组件的 API 与变体、as-child渲染链接的技巧以及从源码层面理解其样式体系的实现原理。组件定位为什么需要 ItemItem是一个通用的 flex 容器组件内部几乎可以承载任何类型的内容标题ItemTitle、描述ItemDescription和操作按钮ItemActions。将其与ItemGroup组合就能构建出整齐划一的条目列表。从功能上讲用div加几行 CSS 类也能实现同样的效果但正如官方文档所说作者在反复构建同类界面后决定把它沉淀成一个可复用组件并长期使用。它的价值在于约定优于配置子组件自带排版样式间距、字号、截断等无需每次手写可访问性友好容器自带焦点可见样式focus-visible边框与 ring支持键盘导航组合灵活头部、媒体、内容、操作、页脚等区域可自由编排满足不同布局。从源码结构看item 目录 下共包含 10 个.vue文件和一个统一导出入口 index.ts入口文件同时集中定义了itemVariants与itemMediaVariants两套 CVAclass-variance-authority变体函数所有子组件的样式均由这两套变体驱动。安装方式一CLI推荐在项目根目录执行npx shadcn-vuelatest add itemCLI 会自动将 item 相关文件含全部子组件写入你项目的components/ui/item目录并按需解析依赖如reka-ui的Primitive、class-variance-authority、cn工具函数。方式二手动复制从仓库的 item 源码目录 复制全部文件到项目的components/ui/item目录更新文件内的导入路径使其匹配你的项目配置例如将/registry/new-york-v4/ui/...改为/components/ui/.../lib/utils指向你的cn工具函数。基础用法引入后即可像普通组件一样组合使用script setup langts import { Item, ItemContent, ItemDescription, ItemFooter, ItemHeader, ItemMedia, ItemTitle, } from /components/ui/item /script template Item ItemHeaderItem Header/ItemHeader ItemMedia / ItemContent ItemTitleItem/ItemTitle ItemDescriptionItem/ItemDescription /ItemContent ItemFooterItem Footer/ItemFooter /Item /template推荐的内容编排是ItemMediaItemContent内含ItemTitle与ItemDescriptionItemActionstemplate Item ItemMedia / ItemContent ItemTitleItem/ItemTitle ItemDescriptionItem/ItemDescription /ItemContent ItemActions / /Item /template核心 Props 与样式变体Item 主组件PropTypeDefault说明variantdefault \| outline \| muteddefault视觉风格sizedefault \| smdefault尺寸as-childbooleanfalse是否将样式透传给子元素如aclassstring—追加自定义类从 Item.vue 源码可以看到它通过reka-ui的Primitive渲染默认asdiv并输出data-slotitem、data-variant、data-size三个数据属性样式由cn(itemVariants({ variant, size }), props.class)合并生成。对应的 itemVariants 定义如下基础样式group/item flex items-center border border-transparent text-sm rounded-md transition-colors flex-wrap outline-none并包含[a]:hover:bg-accent/50、focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3等交互样式——这意味着当 Item 内渲染链接时悬停与聚焦态自动生效variant.defaultbg-transparent透明背景variant.outlineborder-border显示边框variant.mutedbg-muted/50柔和底色size.defaultp-4 gap-4size.smpy-3 px-4 gap-2.5更紧凑。ItemMedia图标 / 图片 / 头像媒体区PropTypeDefault说明variantdefault \| icon \| imagedefault媒体呈现形式classstring—追加自定义类三种变体在 itemMediaVariants 中的差异default透明背景适合放置头像等已有样式的媒体iconsize-8 border rounded-sm bg-muted并将未显式指定尺寸的 SVG 统一约束为size-4imagesize-10 rounded-sm overflow-hidden图片填满容器并object-cover裁剪。图标与图片的典型用法template ItemMedia varianticon Icon / /ItemMedia /templatetemplate ItemMedia variantimage img src... alt... /ItemMedia /template其余子组件组件作用Props关键样式来自源码ItemGroup分组容器纵向排列多个 Itemclassrolelist、flex flex-colItemSeparator组内条目分隔线class—ItemContent包裹标题与描述flex flex-1 flex-col gap-1若只需要标题可以省略class—ItemTitle标题行font-medium text-sm leading-snugclass—ItemDescription描述文本text-muted-foreground line-clamp-2最多两行截断内部链接自动下划线class—ItemActions操作区flex items-center gap-2放按钮等交互元素class—ItemHeader条目头部class—ItemFooter条目底部class—各子组件的class均会通过cn()与内置样式合并且都输出对应的data-slot属性如item-group、item-media、item-title、item-description、item-actions便于 CSS 选择器精确定位。完整示例变体Variant三个变体并排对比详见 ItemVariantDemo.vuescript setup langts import { Button } from /components/ui/button import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle, } from /components/ui/item /script template div classflex flex-col gap-6 !-- default标准样式透明背景 -- Item ItemContent ItemTitleDefault Variant/ItemTitle ItemDescriptionStandard styling with subtle background and borders./ItemDescription /ItemContent ItemActions Button variantoutline sizesmOpen/Button /ItemActions /Item !-- outline清晰边框 -- Item variantoutline ItemContent ItemTitleOutline Variant/ItemTitle ItemDescriptionOutlined style with clear borders and transparent background./ItemDescription /ItemContent ItemActions Button variantoutline sizesmOpen/Button /ItemActions /Item !-- muted柔和的次级内容视觉 -- Item variantmuted ItemContent ItemTitleMuted Variant/ItemTitle ItemDescriptionSubdued appearance with muted colors for secondary content./ItemDescription /ItemContent ItemActions Button variantoutline sizesmOpen/Button /ItemActions /Item /div /template尺寸Sizesm尺寸适用于需要紧凑排列的场景如侧边栏列表项default则用于常规内容块。两者可通过sizesm与sizedefault切换。图标Icon将图标放入ItemMedia varianticon即可获得带背景的图标容器源码中[_svg:not([class*size-])]:size-4会自动统一图标尺寸。头像Avatar把头像组件放进ItemMedia默认变体与ItemContent组合成用户条目Item ItemMedia Avatar AvatarImage :srcuser.avatar classgrayscale / AvatarFallback{{ user.username.charAt(0) }}/AvatarFallback /Avatar /ItemMedia ItemContent ItemTitle{{ user.username }}/ItemTitle ItemDescription{{ user.email }}/ItemDescription /ItemContent /Item图片Image使用ItemMedia variantimage展示图片封面图片会自动裁切填满容器。分组列表GroupItemGroupItemSeparator组成整齐的列表详见 ItemGroupDemo.vuetemplate ItemGroup template v-for(person, index) in people :keyperson.username Item ItemMedia Avatar AvatarImage :srcperson.avatar classgrayscale / AvatarFallback{{ person.username.charAt(0) }}/AvatarFallback /Avatar /ItemMedia ItemContent ItemTitle{{ person.username }}/ItemTitle ItemDescription{{ person.email }}/ItemDescription /ItemContent ItemActions Button variantghost sizeicon classrounded-full Plus / /Button /ItemActions /Item ItemSeparator v-ifindex ! people.length - 1 / /template /ItemGroup /templateItemSeparator放在两个Item之间即可上例用v-if保证最后一项之后不渲染分隔线。头部Header使用ItemHeader在内容上方放置标题区例如分组标题或操作行。链接Link这是 Item 最具价值的用法通过as-child把样式与交互态透传给自定义元素如a。悬停与焦点态会自动应用到该元素上源码中[a]:hover:bg-accent/50与focus-visible:ring-3等规则生效script setup langts import { Item, ItemContent, ItemDescription, ItemMedia, ItemTitle, } from /components/ui/item /script template Item as-child a href/dashboard ItemMedia varianticon Home / /ItemMedia ItemContent ItemTitleDashboard/ItemTitle ItemDescription Overview of your account and activity. /ItemDescription /ItemContent /a /Item /template更紧凑的通知型链接行示例结合variantoutline sizesm见 ItemDemo.vueItem variantoutline sizesm as-child a href# ItemMedia BadgeCheckIcon classsize-5 / /ItemMedia ItemContent ItemTitleYour profile has been verified./ItemTitle /ItemContent ItemActions ChevronRightIcon classsize-4 / /ItemActions /a /Item下拉菜单Dropdown将Item与下拉菜单/弹出菜单组合如 ItemDropdownDemo.vue 所示可让每个条目都具备菜单操作适用于设置页或列表页的更多操作场景。常见组合模式速查场景推荐组合普通内容条目ItemItemContentItemTitleItemDescription带操作按钮的条目上述组合 ItemActions带图标的条目上述组合 ItemMedia varianticon用户列表ItemGroupItemItemMedia头像ItemSeparator可点击条目Item as-childa紧凑侧栏列表Item sizesm小结Item系列组件把条目型 UI从重复劳动中解放出来Item负责容器与变体ItemMedia承载图标/图片/头像ItemContent组织标题与描述ItemActions放置操作ItemGroup与ItemSeparator完成列表编排ItemHeader/ItemFooter提供头尾扩展位。其源码基于 reka-ui 的Primitive与 CVA 变体体系实现index.ts既保持了极简的 API 面又通过as-child保留了对链接、按钮等自定义元素的完整透传能力是构建设置面板、通知中心、消息列表、用户目录等界面的高效起点。赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐shadcn-vue registry.json 完全指南搭建属于自己的组件注册表shadcn vue registry.json 完全指南搭建属于自己的组件注册表 导读 registry.json 是 shadcn vue 生态中组件注UI组件前端shadcn-vue Field 组件完全指南用可组合的表单组件族构建无障碍表单shadcn vue Field 组件完全指南用可组合的表单组件族构建无障碍表单 Field 是 shadcn vue 中面向表单场景的组件族Field FUI组件前端Quasar QCard 组件完全指南用 Vue 快速构建高性能卡片式界面Quasar QCard 组件完全指南用 Vue 快速构建高性能卡片式界面 QCard 是 Quasar Framework 中用来承载和归纳重要内容分组的核前端UI组件跨平台上一篇如何快速上手AutoGPTQ5分钟从安装到第一个量化模型下一篇RealSense D455 深度相机实战把会跳的距离读成稳定的测量数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考