Comp AI CRM 中 AI Elements 附件组件实战：Attachments 组合式文件展示方案

后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载Attachments 是 AI Elements 组件库中负责附件与来源文档展示的组件族为 AI 聊天界面中的文件、图片、视频、音频与引用来源提供统一、可组合的渲染方案。本文以仓库内 .agents/skills/ai-elements/references/attachments.md 为核心结合同目录可运行示例脚本与仓库中的附件数据实现完整讲解安装、AI SDK 集成、三种布局变体、全部 Props 与工具函数读完即可在 Next.js AI SDK 的聊天应用中落地一个支持缩略图、徽章、文件列表与悬停预览的附件区。组件定位与能力概览Attachment组件族解决的是 AI 对话场景中一个高频问题用户上传的文件、模型引用的来源文档如何以一致且美观的方式展示它提供的是一套统一的附件展示入口同时覆盖FileUIPart用户上传文件与SourceDocumentUIPartAI 引用的来源文档两类 AI SDK 数据。组件核心能力包括三种展示变体grid缩略图网格、inline紧凑徽章配合悬停预览、list带完整元数据的文件行同时支持 AI SDK 的FileUIPart与SourceDocumentUIPart数据自动媒体类型检测image、video、audio、document、source由getMediaCategory工具函数驱动inline 预览的悬停卡片支持AttachmentHoverCard系列带可自定义回调的移除按钮悬停时出现组合式composable架构Attachments、Attachment、AttachmentPreview、AttachmentInfo、AttachmentRemove等子组件自由拼装无障碍支持移除按钮带 ARIA 屏幕阅读器标签TypeScript 支持并导出getMediaCategory、getAttachmentLabel等工具函数。从仓库结构看该组件文档与示例统一存放在 .agents/skills/ai-elements 目录下配套三个可直接运行的示例脚本scripts/attachments.tsxgrid、scripts/attachments-inline.tsxinline、scripts/attachments-list.tsxlist可作为独立调试与效果预览的参照。安装与前置条件附件组件属于 AI Elements 组件库通过其 CLI 安装安装命令会将组件源码直接下载并集成到项目components目录下默认路径为/components/ai-elements/npx ai-elementslatest add attachments根据项目包管理器不同也可以使用等价命令pnpm dlx ai-elementslatest或bunx --bun ai-elementslatest。安装前需要确认环境满足以下前提Node.js 18 或更高版本Next.js 项目且已安装 AI SDK已配置 shadcn/ui若未安装运行安装命令时会自动安装。组件安装后即为项目代码的一部分而非隐藏在库中的黑盒可以直接阅读源码、按需修改样式Tailwind 类与行为与项目自身组件没有区别。注意仓库中的 AI Elements 技能文档说明.agents/skills/ai-elements/SKILL.md建议运行所有 CLI 命令时使用与项目packageManager匹配的包运行器上述npx示例应替换为项目实际使用的命令。与 AI SDK 集成展示用户上传文件附件组件最常见的用法是在聊天消息或输入区中展示用户上传的文件。AI SDK 的消息parts中上传文件对应FileUIPart类型因此只需要把FileUIPart { id: string }数组交给Attachments并为每个文件渲染一个Attachment即可use client; import { Attachments, Attachment, AttachmentPreview, AttachmentInfo, AttachmentRemove, } from /components/ai-elements/attachments; import type { FileUIPart } from ai; interface MessageProps { attachments: (FileUIPart { id: string })[]; onRemove?: (id: string) void; } const MessageAttachments ({ attachments, onRemove }: MessageProps) ( Attachments variantgrid {attachments.map((file) ( Attachment key{file.id} data{file} onRemove{onRemove ? () onRemove(file.id) : undefined} AttachmentPreview / AttachmentRemove / /Attachment ))} /Attachments ); export default MessageAttachments;要点说明data接收附件数据对象需包含id组件内部通过mediaType、type、url、filename等字段进行媒体类型判断与预览渲染onRemove为可选回调仅在需要删除能力时传入内部通过闭包把当前附件的id绑定到对应按钮AttachmentPreview负责渲染图片/视频预览或类型图标AttachmentRemove是悬停时出现的移除按钮由于整个组件支持组合你可以自行决定子组件的排列与嵌套层级例如只渲染AttachmentPreview而不显示移除按钮。三种布局变体Attachments通过variant属性切换整体布局三种变体分别对应不同的展示场景仓库内三个示例脚本即为各自变体的完整实现。Grid 变体消息内的缩略图网格适用于消息中带视觉缩略图的附件展示。示例 scripts/attachments.tsx 中附件数据包含filename、id、mediaType、type: file与url字段图片类附件如image/jpeg渲染缩略图无url的 PDF、视频则回退为类型图标。Attachments variantgrid {attachments.map((attachment) ( AttachmentItem key{attachment.id} attachment{attachment} onRemove{handleRemove} / ))} /Attachments示例用memo包裹AttachmentItem并用useCallback稳定handleRemove避免列表重渲染时不必要的子组件更新——这是在聊天消息列表中渲染大量附件时值得借鉴的性能实践。Inline 变体输入区的紧凑徽章适用于输入区等紧凑场景以徽章形式展示附件并在悬停时弹出预览卡片。示例 scripts/attachments-inline.tsx 展示了完整的 hover 交互组合AttachmentHoverCard key{attachment.id} AttachmentHoverCardTrigger asChild Attachment data{attachment} onRemove{handleRemove} div classNamerelative size-5 shrink-0 div classNameabsolute inset-0 transition-opacity group-hover:opacity-0 AttachmentPreview / /div AttachmentRemove classNameabsolute inset-0 / /div AttachmentInfo / /Attachment /AttachmentHoverCardTrigger AttachmentHoverCardContent {/* 图片类附件展示大图预览 文件名 mediaType */} /AttachmentHoverCardContent /AttachmentHoverCard该示例的核心逻辑在于先用getMediaCategory(attachment)得到媒体分类再通过mediaCategory image attachment.type file attachment.url判断是否渲染图片大图预览卡片内展示文件名getAttachmentLabel结果与mediaType元数据。此外示例中同时包含type: file与type: source-document两类数据验证了组件对来源文档的统一支持。List 变体带完整元数据的文件列表适用于文件列表场景每行展示图标、文件名、媒体类型与移除按钮。示例 scripts/attachments-list.tsx 展示了关键差异——为AttachmentInfo传入showMediaType以在文件名下方显示媒体类型Attachment data{attachment} key{attachment.id} onRemove{handleRemove} AttachmentPreview / AttachmentInfo showMediaType / AttachmentRemove / /Attachment示例中容器额外传入了classNamew-full max-w-md说明Attachments会透传 HTML 属性方便限制宽度、对齐等布局需求。Props 参考Attachments /容器组件负责设置布局变体。PropTypeDefaultDescriptionvariantunknown-展示布局变体grid / inline / list。...propsReact.HTMLAttributesHTMLDivElement-透传到底层 div 元素。Attachment /单个附件条目包装器。PropTypeDefaultDescriptiondataunknown-附件数据带 id 的 FileUIPart 或 SourceDocumentUIPart。onRemove() void-点击移除按钮时触发的回调。...propsReact.HTMLAttributesHTMLDivElement-透传到底层 div 元素。AttachmentPreview /渲染媒体预览图片、视频或类型图标。PropTypeDefaultDescriptionfallbackIconReact.ReactNode-无预览可用时展示的自定义图标。...propsReact.HTMLAttributesHTMLDivElement-透传到底层 div 元素。AttachmentInfo /展示文件名与可选媒体类型。PropTypeDefaultDescriptionshowMediaTypebooleanfalse是否在文件名下方展示媒体类型。...propsReact.HTMLAttributesHTMLDivElement-透传到底层 div 元素。AttachmentRemove /悬停时出现的移除按钮。PropTypeDefaultDescriptionlabelstring-按钮的屏幕阅读器标签无障碍必需。...propsReact.ComponentPropstypeof Button-透传到底层 Button 组件。AttachmentHoverCard /悬停预览功能的外层包装。PropTypeDefaultDescriptionopenDelaynumber0打开悬停卡片的延迟毫秒。closeDelaynumber0关闭悬停卡片的延迟毫秒。...propsReact.ComponentPropstypeof HoverCard-透传到底层 HoverCard 组件。AttachmentHoverCardTrigger /悬停卡片的触发元素。PropTypeDefaultDescription...propsReact.ComponentPropstypeof HoverCardTrigger-透传到底层 HoverCardTrigger 组件。AttachmentHoverCardContent /悬停卡片中展示的内容。PropTypeDefaultDescriptionalignunknown-悬停卡片内容的对齐方式。...propsReact.ComponentPropstypeof HoverCardContent-透传到底层 HoverCardContent 组件。AttachmentEmpty /无附件时的空状态组件。PropTypeDefaultDescription...propsReact.HTMLAttributesHTMLDivElement-透传到底层 div 元素。需要说明的是原文档中variant、data、align等 Prop 的类型标注为unknown实际取值以源码实现为准variant对应三种布局变体名data对应 AI SDK 的FileUIPart/SourceDocumentUIPartalign对应 HoverCard 的对齐选项。工具函数组件包导出两个可在业务代码中直接复用的工具函数。getMediaCategory(data)返回附件的媒体分类用于自定义预览逻辑如 inline 示例中判断是否渲染图片大图import { getMediaCategory } from /components/ai-elements/attachments; const category getMediaCategory(attachment); // Returns: image | video | audio | document | source | unknown从示例脚本看该函数依据mediaType与type字段进行判定image/jpeg等归于imageapplication/pdf归于documentvideo/mp4归于videoaudio/mp3归于audiotype: source-document归于source。getAttachmentLabel(data)返回附件的展示标签优先取文件名无文件名时回退为 Image 或 Attachment 等通用文案import { getAttachmentLabel } from /components/ai-elements/attachments; const label getAttachmentLabel(attachment); // Returns filename or fallback like Image or Attachment该函数适用于需要统一展示附件名称的场景如 hover 卡片标题、无障碍标签或列表首列。仓库中的附件数据处理对照AI Elements 的 Attachments 组件解决的是前端展示而附件数据从上传到可预览 URL 的链路在仓库中另有实现可对照参考。在 apps/api/src/conversations/conversation-attachments.ts 中可以看到与服务端对话附件同构的数据形态StoredBuilderAttachment类型包含id、name、mediaType、size四个字段与前端附件组件消费的filename/mediaType/id数据一一对应builderMessageWithAttachments将数据库中的 JSON 消息与附件列表合并为每个附件生成id、name、type、size并通过isPreviewableImage判断是否为可预览图片image/gif、image/jpeg、image/png、image/webp是则生成预览 URL否则置为nullattachmentUrl生成/api/conversations/attachments/{id}形式的预览地址并支持带share分享令牌的变体。从源码结构看这与前端getMediaCategory的按媒体类型决定展示形态思路一致服务端决定哪些类型值得生成预览 URL前端决定预览以何种视觉形态呈现两者共同构成了完整的附件展示链路。仓库中 apps/app/components/agent-builder 下的聊天相关组件如agent-builder-chat.tsx、agent-composer.tsx也在消息交互中涉及附件处理可作为 AI 对话界面集成附件的进一步参考。定制与无障碍实践由于组件代码直接进入项目目录定制非常直接样式定制修改components/ai-elements/attachments.tsx中的 Tailwind 类即可例如调整缩略图圆角、徽章配色或移除按钮样式所有子组件均透传HTMLAttributes也可通过className就地覆盖行为定制onRemove回调由你完全掌控可对接状态管理、乐观更新或后端删除接口hover 卡片的开关延迟通过AttachmentHoverCard的openDelay/closeDelay调节避免误触无障碍AttachmentRemove的label属性用于屏幕阅读器朗读建议为Attachment容器补充对应的 aria-label如文件名使附件区对辅助技术可感知。常见问题速查组件无样式确认项目按 shadcn/uiTailwind 4规范配置globals.css包含 Tailwind 导入与 shadcn/ui 基础样式CLI 未添加任何文件确认当前工作目录是项目根目录存在package.json、components.json配置正确并使用最新版 CLInpx ai-elementslatest/别名导入失败module not found检查tsconfig.json中是否配置了/*路径别名需包含baseUrl: .与paths: { /*: [./*] }缩略图不显示确认附件数据的url非空且mediaType属于图片类型——inline 示例中明确以attachment.type file attachment.url为前提才渲染大图。结语Attachments 组件族以容器 子组件自由组合的方式把 AI 聊天中最常见的附件展示需求网格缩略图、输入区徽章、文件列表、来源文档收敛为一套可预测、可定制、可无障碍访问的 API。配合getMediaCategory/getAttachmentLabel工具函数与 AI SDK 原生数据类型的直接支持它可以无缝嵌入任意基于 Next.js AI SDK 的对话界面。仓库中该组件的中文文档、三份可运行示例脚本以及与 apps/api/src/conversations/conversation-attachments.ts 对应的服务端附件链路为直接上手和二次开发提供了完整的参考。赞分享后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载相关推荐Comp AI CRM 中的 AI 推理展示ai-elements Reasoning 组件集成实战指南Comp AI CRM 中的 AI 推理展示ai elements Reasoning 组件集成实战指南 本文是一份以 ai elements 技能文档 ht后端前端CRM人工智能AI Agent如何用 forge-fhevm 的 deploy-local.sh 在本地 Anvil 节点部署 FHEVM 宿主合约栈如何用 forge fhevm 的 deploy local.sh 在本地 Anvil 节点部署 FHEVM 宿主合约栈 用 Foundry 在本地开发 FHE后端前端CRM人工智能AI AgentDB-GPT Agent 框架深度解析ConversableAgent 架构、多智能体协作与三层记忆体系DB GPT Agent 框架深度解析ConversableAgent 架构、多智能体协作与三层记忆体系 本文以 DB GPT 官方的 Agent 框架概念文后端前端CRM人工智能AI Agent上一篇VidBee开源视频下载工具完全指南1000网站视频离线保存下一篇VoxCPM文本转语音快速上手3条命令装好它还能克隆你的声音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考