UploadFilePreviewList 文件预览列表

用于展示文件 ID 列表对应的文件预览信息（名称、缩略图、大小等），常见于详情页展示已上传的附件列表。

基础用法

传入文件 ID 列表，组件自动请求 previewUrl 获取文件详情并渲染预览。

基础用法

传入文件 ID 列表，组件自动请求后端获取文件详情并渲染预览。

当前绑定的文件 ID: ["file-001","file-002","file-003"]

<template>
  <div class="demo-wrapper">
    <p class="demo-desc">传入文件 ID 列表，组件自动请求后端获取文件详情并渲染预览。</p>

    <hx-upload-file-preview-list
      v-model="fileIds"
      preview-url="/api/file/preview"
      :show-download="true"
      :removable="true"
      @remove="handleRemove"
    />

    <p class="demo-value">
      当前绑定的文件 ID: {{ JSON.stringify(fileIds) }}
    </p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxUploadFilePreviewList } from '@whhx/ui'

const fileIds = ref(['file-001', 'file-002', 'file-003'])

function handleRemove(fileId: string) {
  console.log('删除文件:', fileId)
}
</script>

<style scoped>
.demo-wrapper {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-desc {
  font-size: 14px;
  color: #606266;
}

.demo-value {
  font-size: 12px;
  color: #909399;
  margin-top: 8px;
}
</style>

详情页切换场景

模拟表格详情页场景：当切换不同数据时，组件会请求对应的文件列表。通过网络请求日志可验证旧请求是否被正确取消。

详情页切换

模拟表格详情页场景：切换不同数据时，组件会加载对应的文件预览列表。
测试方法：打开浏览器开发者工具 Network 面板，切换详情时观察请求状态。
修复后行为：切换详情时，旧请求会被取消（cancelled），不会有重复请求。

当前详情 ID: 1

测试步骤：

1. 打开 Network 面板，清空现有记录
2. 点击任意「详情」按钮（如「详情 1」）
3. 立即点击另一个「详情」按钮（如「详情 2」）
4. 观察 Network 中的请求：详情 1 的请求应显示 cancelled/aborted 状态
5. 等待详情 2 的请求完成
6. 再次切换回详情 1，验证不会有重复请求

<template>
  <div class="demo-wrapper">
    <p class="demo-desc">
      模拟表格详情页场景：切换不同数据时，组件会加载对应的文件预览列表。
      <br>
      <strong>测试方法</strong>：打开浏览器开发者工具 Network 面板，切换详情时观察请求状态。
      <br>
      修复后行为：切换详情时，旧请求会被取消（cancelled），不会有重复请求。
    </p>

    <div class="detail-switcher">
      <hx-button
        v-for="item in detailList"
        :key="item.id"
        :type="currentId === item.id ? 'primary' : 'default'"
        size="small"
        @click="switchDetail(item.id)"
      >
        详情 {{ item.id }}
      </hx-button>
    </div>

    <div class="detail-content">
      <p class="detail-title">当前详情 ID: {{ currentId }}</p>
      <hx-upload-file-preview-list
        :key="currentId"
        v-model="currentDetail.fileIds"
        :preview-url="previewUrl"
        :removable="false"
      />
    </div>

    <div class="tips">
      <p><strong>测试步骤：</strong></p>
      <ol>
        <li>打开 Network 面板，清空现有记录</li>
        <li>点击任意「详情」按钮（如「详情 1」）</li>
        <li>立即点击另一个「详情」按钮（如「详情 2」）</li>
        <li>观察 Network 中的请求：详情 1 的请求应显示 cancelled/aborted 状态</li>
        <li>等待详情 2 的请求完成</li>
        <li>再次切换回详情 1，验证不会有重复请求</li>
      </ol>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'
import { HxButton, HxUploadFilePreviewList } from '@whhx/ui'

// 模拟的详情数据（使用 picsum 图片 ID 作为文件 ID）
const detailList = [
  { id: 1, fileIds: ['10', '20', '30'] },
  { id: 2, fileIds: ['40', '50'] },
  { id: 3, fileIds: ['60', '70', '80', '90'] },
]

const currentId = ref(1)
const currentDetail = computed(() => detailList.find(d => d.id === currentId.value)!)

function switchDetail(id: number) {
  currentId.value = id
}

// 使用 picsum.photos 作为模拟的文件预览服务
// 真实场景中，这里应该配置实际的文件预览接口
const previewUrl = 'https://picsum.photos/id'
</script>

<style scoped>
.demo-wrapper {
  display: flex;
  flex-direction: column;
  gap: 16px;
}

.demo-desc {
  font-size: 14px;
  color: #606266;
  line-height: 1.6;
  padding: 12px;
  background: #f5f7fa;
  border-radius: 4px;
}

.detail-switcher {
  display: flex;
  gap: 8px;
}

.detail-content {
  padding: 16px;
  border: 1px solid #ebeef5;
  border-radius: 8px;
}

.detail-title {
  font-weight: 600;
  margin-bottom: 12px;
  color: #303133;
}

.tips {
  font-size: 13px;
  color: #606266;
  line-height: 1.8;
  padding: 12px;
  background: #fff8e6;
  border-radius: 4px;
  border-left: 3px solid #e6a23c;
}

.tips ol {
  margin: 8px 0 0;
  padding-left: 20px;
}

.tips li {
  margin-bottom: 4px;
}
</style>

卡片尺寸控制

通过 itemWidth 和 itemHeight 控制卡片尺寸，固定尺寸的卡片宽度不会受文件名长度影响。

卡片尺寸

通过 itemWidth 和 itemHeight 控制卡片尺寸， 支持数字（自动添加 px 后缀）或带单位字符串。固定尺寸的卡片宽度不会因文件名长度而变化。

固定尺寸卡片（数字）

固定尺寸卡片（字符串）

自适应尺寸（默认）

当前绑定的文件 ID: ["file-001","file-002","file-003"]

<template>
  <div class="demo-wrapper">
    <p class="demo-desc">
      通过 <code>itemWidth</code> 和 <code>itemHeight</code> 控制卡片尺寸，
      支持数字（自动添加 px 后缀）或带单位字符串。固定尺寸的卡片宽度不会因文件名长度而变化。
    </p>

    <div class="demo-section">
      <h4 class="demo-title">固定尺寸卡片（数字）</h4>
      <hx-upload-file-preview-list
        v-model="fileIds"
        preview-url="/api/file/preview"
        :show-download="true"
        :removable="true"
        :item-width="220"
        :item-height="100"
        @remove="handleRemove"
      />
    </div>

    <div class="demo-section">
      <h4 class="demo-title">固定尺寸卡片（字符串）</h4>
      <hx-upload-file-preview-list
        v-model="fileIds"
        preview-url="/api/file/preview"
        :show-download="true"
        :removable="true"
        item-width="220px"
        item-height="100px"
        @remove="handleRemove"
      />
    </div>

    <div class="demo-section">
      <h4 class="demo-title">自适应尺寸（默认）</h4>
      <hx-upload-file-preview-list
        v-model="fileIds"
        preview-url="/api/file/preview"
        :show-download="true"
        :removable="true"
      />
    </div>

    <p class="demo-value">
      当前绑定的文件 ID: {{ JSON.stringify(fileIds) }}
    </p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxUploadFilePreviewList } from '@whhx/ui'

const fileIds = ref(['file-001', 'file-002', 'file-003'])

function handleRemove(fileId: string) {
  console.log('删除文件:', fileId)
}
</script>

<style scoped>
.demo-wrapper {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

.demo-desc {
  font-size: 14px;
  color: #606266;
  line-height: 1.6;
}

.demo-section {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.demo-title {
  font-size: 14px;
  font-weight: 600;
  color: #303133;
  margin: 0;
}

.demo-value {
  font-size: 12px;
  color: #909399;
}
</style>

API

Props

参数	说明	类型	默认值
v-model	文件 ID 列表，支持字符串（逗号分隔）或数组	string | string[]	-
preview-url	获取文件预览信息的接口地址，组件请求 ${previewUrl}/${fileId}	string	-
model-value-type	v-model 值类型	'string' | 'array'	'array'
show-download	是否显示下载按钮	boolean	true
removable	是否显示删除按钮	boolean	false
disabled	是否禁用	boolean	false
remove-confirm-title	删除确认框标题	string	'确认删除'
remove-confirm-message	删除确认框内容，支持 {name} 占位符	string	'确定要删除文件「{name}」吗？'
item-width	卡片宽度，支持数字或带单位字符串	string | number	undefined
item-height	卡片高度，支持数字或带单位字符串	string | number	undefined
delete-url	根据 fileId 删除文件的接口，组件调用 DELETE ${deleteUrl}/${fileId}	string	undefined

Events

事件名	说明	参数
update:modelValue	删除文件后触发	(value: string | string[])
remove	删除文件时触发（确认删除后、调用 deleteUrl 之前）	(fileId: string)