Skip to content

feat(FilesCard): 添加previewTeleported属性，支持将预览图片弹窗teleport到body下 #311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IsDyh01 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(FilesCard): 添加previewTeleported属性，支持将预览图片弹窗teleport到body下 #311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 23 additions & 22 deletions apps/docs/en/components/filesCard/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,28 +32,29 @@ The `FilesCard` component is a flexible file display component that supports vis

## Properties

| Property Name | Type | Required | Default | Description |
| ---------------- | ---------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `uid` | `string \| number` | Yes | | File unique identifier |
| `name` | `string` | No | `undefined` | File name (supports automatic suffix parsing to match icons) |
| `fileSize` | `number` | No | `undefined` | File size (unit: bytes, automatically converted to readable format) |
| `fileType` | `string` | No | `undefined` | File type (priority higher than `name` suffix parsing, e.g. `'image'`, `'document'`) |
| `description` | `string` | No | `undefined` | Description text (supports dynamic generation of file type and size info) |
| `url` | `string` | No | `undefined` | File access URL (image files can be used for preview) |
| `thumbUrl` | `string` | No | `undefined` | Image thumbnail URL |
| `imgFile` | `File \| Blob` | No | `undefined` | Image file stream (automatically parsed as preview URL, only for temporary display before upload) |
| `iconSize` | `string` | No | `'42px'` | Icon/image size |
| `iconColor` | `string` | No | `undefined` | Icon color for non-image files (supports custom color values) |
| `showDelIcon` | `boolean` | No | `false` | Whether to show hover delete icon |
| `maxWidth` | `string` | No | `'236px'` | Card maximum width |
| `style` | `CSSProperties` | No | `undefined` | Card custom styles |
| `hoverStyle` | `CSSProperties` | No | `undefined` | Card custom styles when hovering |
| `imgVariant` | `'rectangle' \| 'square'` | No | `'rectangle'` | Image card form (rectangle/square) |
| `imgPreview` | `boolean` | No | `true` | Whether to enable image preview functionality |
| `imgPreviewMask` | `boolean` | No | `true` | Whether to show image preview mask overlay |
| `status` | `'uploading' \| 'done' \| 'error'` | No | `undefined` | File status (controls progress bar, error prompts and other visual feedback) |
| `percent` | `number` | No | `0` | Upload progress percentage (used with `status="uploading"`) |
| `errorTip` | `string` | No | `'Upload failed'` | Custom error status prompt text |
| Property Name | Type | Required | Default | Description |
| ------------------- | ---------------------------------- | -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `uid` | `string \| number` | Yes | | File unique identifier |
| `name` | `string` | No | `undefined` | File name (supports automatic suffix parsing to match icons) |
| `fileSize` | `number` | No | `undefined` | File size (unit: bytes, automatically converted to readable format) |
| `fileType` | `string` | No | `undefined` | File type (priority higher than `name` suffix parsing, e.g. `'image'`, `'document'`) |
| `description` | `string` | No | `undefined` | Description text (supports dynamic generation of file type and size info) |
Copy link

@coderabbitai coderabbitai bot Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Invalid example value for fileType (“document”).

The union in code does not include 'document'. Replace with valid options or remove the example to avoid misleading users.

Apply this diff (one option):

-| `fileType`          | `string`                           | No       | `undefined`       | File type (priority higher than `name` suffix parsing, e.g. `'image'`, `'document'`)                                        |
+| `fileType`          | `string`                           | No       | `undefined`       | File type (priority higher than `name` suffix parsing; valid values include `'word'`, `'excel'`, `'ppt'`, `'pdf'`, `'txt'`, `'mark'`, `'image'`, `'audio'`, `'video'`, `'three'`, `'code'`, `'database'`, `'link'`, `'zip'`, `'file'`, `'unknown'`). |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| `description` | `string` | No | `undefined` | Description text (supports dynamic generation of file type and size info) |
| `fileType` | `string` | No | `undefined` | File type (priority higher than `name` suffix parsing; valid values include `'word'`, `'excel'`, `'ppt'`, `'pdf'`, `'txt'`, `'mark'`, `'image'`, `'audio'`, `'video'`, `'three'`, `'code'`, `'database'`, `'link'`, `'zip'`, `'file'`, `'unknown'`). |
| `description` | `string` | No | `undefined` | Description text (supports dynamic generation of file type and size info) |
🤖 Prompt for AI Agents 
In apps/docs/en/components/filesCard/index.md around line 41, the example value
"document" for fileType is invalid because the prop's union does not include
'document'; update the table to either use a valid union member (e.g., replace
"document" with one of the actual allowed values) or remove the example value
entirely so it doesn't mislead readers, and ensure any accompanying text
reflects the chosen valid option.

| `url` | `string` | No | `undefined` | File access URL (image files can be used for preview) |
| `thumbUrl` | `string` | No | `undefined` | Image thumbnail URL |
| `imgFile` | `File \| Blob` | No | `undefined` | Image file stream (automatically parsed as preview URL, only for temporary display before upload) |
| `iconSize` | `string` | No | `'42px'` | Icon/image size |
| `iconColor` | `string` | No | `undefined` | Icon color for non-image files (supports custom color values) |
| `showDelIcon` | `boolean` | No | `false` | Whether to show hover delete icon |
| `maxWidth` | `string` | No | `'236px'` | Card maximum width |
| `style` | `CSSProperties` | No | `undefined` | Card custom styles |
| `hoverStyle` | `CSSProperties` | No | `undefined` | Card custom styles when hovering |
| `imgVariant` | `'rectangle' \| 'square'` | No | `'rectangle'` | Image card form (rectangle/square) |
| `imgPreview` | `boolean` | No | `true` | Whether to enable image preview functionality |
| `imgPreviewMask` | `boolean` | No | `true` | Whether to show image preview mask overlay |
| `previewTeleported` | `boolean` | No | `false` | whether to append image-viewer to body. A nested parent element attribute transform should have this attribute set to true. |
| `status` | `'uploading' \| 'done' \| 'error'` | No | `undefined` | File status (controls progress bar, error prompts and other visual feedback) |
| `percent` | `number` | No | `0` | Upload progress percentage (used with `status="uploading"`) |
| `errorTip` | `string` | No | `'Upload failed'` | Custom error status prompt text |

## Slots

Expand Down
45 changes: 23 additions & 22 deletions apps/docs/zh/components/filesCard/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,28 +32,29 @@

## 属性

| 属性名 | 类型 | 是否必填 | 默认值 | 描述 |
| ---------------- | ---------------------------------- | -------- | ------------- | ------------------------------------------------------------------ |
| `uid` | `string \| number` | 是 | | 文件唯一标识符 |
| `name` | `string` | 否 | `undefined` | 文件名（支持自动解析后缀匹配图标） |
| `fileSize` | `number` | 否 | `undefined` | 文件大小（单位：字节，自动转换为易读格式） |
| `fileType` | `string` | 否 | `undefined` | 文件类型（优先级高于 `name` 后缀解析，如 `'image'`、`'document'`） |
| `description` | `string` | 否 | `undefined` | 描述文本（支持动态生成文件类型和大小信息） |
| `url` | `string` | 否 | `undefined` | 文件访问地址（图片文件可用于预览） |
| `thumbUrl` | `string` | 否 | `undefined` | 图片缩略图地址 |
| `imgFile` | `File \| Blob` | 否 | `undefined` | 图片文件流（自动解析为预览地址，仅用于上传前临时展示） |
| `iconSize` | `string` | 否 | `'42px'` | 图标/图片尺寸 |
| `iconColor` | `string` | 否 | `undefined` | 非图片文件的图标颜色（支持自定义色值） |
| `showDelIcon` | `boolean` | 否 | `false` | 是否显示悬停删除图标 |
| `maxWidth` | `string` | 否 | `'236px'` | 卡片最大宽度 |
| `style` | `CSSProperties` | 否 | `undefined` | 卡片自定义样式 |
| `hoverStyle` | `CSSProperties` | 否 | `undefined` | 卡片悬停时的自定义样式 |
| `imgVariant` | `'rectangle' \| 'square'` | 否 | `'rectangle'` | 图片卡片形态（长方形/正方形） |
| `imgPreview` | `boolean` | 否 | `true` | 是否开启图片预览功能 |
| `imgPreviewMask` | `boolean` | 否 | `true` | 是否显示图片预览遮罩蒙层 |
| `status` | `'uploading' \| 'done' \| 'error'` | 否 | `undefined` | 文件状态（控制进度条、错误提示等视觉反馈） |
| `percent` | `number` | 否 | `0` | 上传进度百分比（配合 `status="uploading"` 使用） |
| `errorTip` | `string` | 否 | `'上传失败'` | 错误状态自定义提示文本 |
| 属性名 | 类型 | 是否必填 | 默认值 | 描述 |
| ------------------- | ---------------------------------- | -------- | ------------- | ----------------------------------------------------------------------------------------- |
| `uid` | `string \| number` | 是 | | 文件唯一标识符 |
| `name` | `string` | 否 | `undefined` | 文件名（支持自动解析后缀匹配图标） |
| `fileSize` | `number` | 否 | `undefined` | 文件大小（单位：字节，自动转换为易读格式） |
| `fileType` | `string` | 否 | `undefined` | 文件类型（优先级高于 `name` 后缀解析，如 `'image'`、`'document'`） |
| `description` | `string` | 否 | `undefined` | 描述文本（支持动态生成文件类型和大小信息） |
Copy link

@coderabbitai coderabbitai bot Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

fileType 示例值不准确（含有不存在的 'document'）。

类型联合中没有 'document'。请使用实际可用的取值，或移除该示例以免误导使用者。

-| `fileType`          | `string`                           | 否       | `undefined`   | 文件类型（优先级高于 `name` 后缀解析，如 `'image'`、`'document'`）                        |
+| `fileType`          | `string`                           | 否       | `undefined`   | 文件类型（优先级高于 `name` 后缀解析；可选：`'word'`、`'excel'`、`'ppt'`、`'pdf'`、`'txt'`、`'mark'`、`'image'`、`'audio'`、`'video'`、`'three'`、`'code'`、`'database'`、`'link'`、`'zip'`、`'file'`、`'unknown'`） |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| `description` | `string` | 否 | `undefined` | 描述文本（支持动态生成文件类型和大小信息） |
| `fileType` | `string` | 否 | `undefined` | 文件类型（优先级高于 `name` 后缀解析；可选：`'word'`、`'excel'`、`'ppt'`、`'pdf'`、`'txt'`、`'mark'`、`'image'`、`'audio'`、`'video'`、`'three'`、`'code'`、`'database'`、`'link'`、`'zip'`、`'file'`、`'unknown'`） |
🤖 Prompt for AI Agents 
In apps/docs/zh/components/filesCard/index.md around line 41, the example value
'document' in the `fileType` description is incorrect because the union type
does not include 'document'; remove or replace it with an actual allowed value
from the component's `fileType` union (or simply omit the example) and update
the description text so it no longer references the nonexistent 'document'
value.

| `url` | `string` | 否 | `undefined` | 文件访问地址（图片文件可用于预览） |
| `thumbUrl` | `string` | 否 | `undefined` | 图片缩略图地址 |
| `imgFile` | `File \| Blob` | 否 | `undefined` | 图片文件流（自动解析为预览地址，仅用于上传前临时展示） |
| `iconSize` | `string` | 否 | `'42px'` | 图标/图片尺寸 |
| `iconColor` | `string` | 否 | `undefined` | 非图片文件的图标颜色（支持自定义色值） |
| `showDelIcon` | `boolean` | 否 | `false` | 是否显示悬停删除图标 |
| `maxWidth` | `string` | 否 | `'236px'` | 卡片最大宽度 |
| `style` | `CSSProperties` | 否 | `undefined` | 卡片自定义样式 |
| `hoverStyle` | `CSSProperties` | 否 | `undefined` | 卡片悬停时的自定义样式 |
| `imgVariant` | `'rectangle' \| 'square'` | 否 | `'rectangle'` | 图片卡片形态（长方形/正方形） |
| `imgPreview` | `boolean` | 否 | `true` | 是否开启图片预览功能 |
| `imgPreviewMask` | `boolean` | 否 | `true` | 是否显示图片预览遮罩蒙层 |
| `previewTeleported` | `boolean` | 否 | `false` | image-viewer 是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 true |
| `status` | `'uploading' \| 'done' \| 'error'` | 否 | `undefined` | 文件状态（控制进度条、错误提示等视觉反馈） |
| `percent` | `number` | 否 | `0` | 上传进度百分比（配合 `status="uploading"` 使用） |
| `errorTip` | `string` | 否 | `'上传失败'` | 错误状态自定义提示文本 |

## 插槽

Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/components/FilesCard/index.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ const props = withDefaults(defineProps<FilesCardProps>(), {
imgVariant: 'rectangle',
imgPreview: true,
imgPreviewMask: true,
previewTeleported: false,
status: undefined,
percent: undefined,
errorTip: undefined
Expand Down Expand Up @@ -190,6 +191,7 @@ defineExpose({
class="elx-files-card-img"
:src="_previewImgUrl"
:preview-src-list="props.imgPreview ? [_previewImgUrl] : []"
:preview-teleported="props.previewTeleported"
fit="cover"
:show-progress="false"
hide-on-click-modal
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/components/FilesCard/types.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ export interface FilesCardProps {
imgVariant?: 'rectangle' | 'square';
// 图片是否开启预览
imgPreview?: boolean;
// image-viewer 是否插入至 body 元素上。 嵌套的父元素属性会发生修改时应该将此属性设置为 true
previewTeleported?: boolean;
// 是否显示预览遮罩
imgPreviewMask?: boolean;

Expand Down
5 changes: 5 additions & 0 deletions packages/core/src/stories/FilesCard/FilesCard.stories.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,11 @@ const meta: Meta<typeof FilesCardSource> = {
description: '是否显示图片预览遮罩蒙层',
defaultValue: true
},
previewTeleported: {
control: 'boolean',
description: '预览是否使用 teleport 插入至 body 元素上',
defaultValue: false
},
status: {
control: { type: 'radio' },
options: ['uploading', 'done', 'error'],
Expand Down