OpenAgentPack Kit
组件反馈

FileCard 文件卡片

文件名、类型徽标与加载态;预览与下载由调用方注入

FileCard 展示单个文件的名称、徽标与加载态;预览与下载由调用方注入回调,组件不请求文件、不保存凭据。

import { FileCard } from "@openagentpack/kit-chat-ui";

copy-in 接入(复制后 import 改为项目内路径):

pnpm kit:add file-card

交给 coding agent 接入时使用 kit-components Skill;主题与渲染依赖见 组件总览。

何时使用

  • 消息流内的交付文件:流内 artifact 分片经 Chat 内置的 ArtifactCard 适配本组件渲染 (Chat),预览与下载双入口。
  • 管理端表单展示已选或已上传文件:纯展示形态,description 作状态词(console 模板文件配置即此用法)。
  • 输入附件的上传卡片(进度、错误与移除):用 Attachments.FileCard, 本组件不含上传语义。

代码演示

预览中的操作只显示回调结果,不会请求远端文件。

预览与下载

onClick 绑定文件名为主入口;与 onDownload 同传时,右侧渲染独立下载图标按钮。

FileCard(预览与下载)

入口组合与缩略图

仅 onDownload 时文件名即下载入口;无回调纯展示;传 src 时缩略图替代字符徽标。

FileCard(入口组合与缩略图)

加载与禁用

loading 阻止操作且第二行固定「加载中…」;disabled 整卡变暗并禁用操作。

FileCard(加载与禁用)

API

FileCard

属性说明类型默认值
name文件名,溢出截断、悬停看全名string—
typeMIME 类型,参与徽标与类型词判定string—
src调用方提供的缩略图地址,提供时替代字符徽标;组件不读取文件内容string—
description第二行说明;加载态被「加载中…」占据ReactNode—
loading加载态:阻止操作,第二行固定「加载中…」booleanfalse
disabled禁用操作,整卡变暗booleanfalse
onClick文件名绑定的主入口回调() => void—
onDownload下载回调;单独传入时文件名即下载入口,与 onClick 同传时渲染独立图标按钮() => void—
className追加到根节点的 Tailwind 工具类;卡片宽度固定 w-56 并随容器收缩string—

入口规则:主入口为 onClick ?? onDownload,绑定在文件名上;两个回调都不传时为静态展示。 type 的已知取值(表格 / 图片 / 音频 / 视频 / PDF / 文本 / 压缩包)在文件名旁展示类型词, 未知类型不展示占位词;有第二行时类型词让位。字符徽标先按 MIME 前缀、再按扩展名取词 (IMG / AUD / VID / PDF / ZIP / XLS,否则扩展名前 4 位或 FILE)。

下载由调用方接 kit-sdk client 经 server 代理执行:组件不请求 Provider,也不把预签名 URL 当作持久下载地址。

相关组件

场景组件数据与操作
输入附件(上传进度与移除)Attachments.FileCarditem: AttachmentItem、onRemove
消息流交付文件 / 产物ArtifactCard(Chat 内置)filename / contentType、onOpen / onDownload

移除输入附件仅通知调用方,不删除远端文件。

主题变量(Design Token)

引入 @openagentpack/kit-chat-ui/theme.css 后使用以下冻结 token。下表列出亮色值, 暗色由 data-kit-theme="dark" 使用对应色板。

Token用途默认主题工作区主题
--kit-bg-subtle卡片底色#f6f7fb#f7f7f7
--kit-border卡片描边#e3e6ef#e5e5e5
--kit-surface字符徽标底色;下载图标悬停底色#ffffff#ffffff
--kit-fg文件名文字#101322#171717
--kit-fg-muted徽标字符、类型词、说明文字与下载图标#5b6478#737373

键盘焦点环用 --kit-focus;文件名与说明走 --kit-text-label / --kit-text-caption 文字档位, 卡片圆角 --kit-radius-sm;下载图标悬停过渡消费 --kit-duration-fast / --kit-ease-out。 更多主题配置见 组件总览。

本页目录