文件上传与 AuthImage

Forge 提供了 FileUpload 组件处理文件上传和 AuthImage 组件渲染鉴权图片。你需要理解文件存储的是 fileId 而非 URL。

FileUpload

基本用法

<template>
  <FileUpload v-model:fileId="form.fileId" :max="1" />
</template>

<script setup>
import FileUpload from '@/components/file-upload/index.vue'

const form = reactive({ fileId: '' })
</script>

属性

属性	类型	默认值	说明
fileId	String	—	文件 ID（v-model）
max	Number	1	最大上传数量
accept	String	—	接受的文件类型
fileSize	Number	10	单文件大小限制（MB）
fileType	Array	—	允许的文件后缀

表单中使用

const schema = computed(() => [
  {
    field: 'fileId',
    label: '附件',
    component: 'FileUpload',
    max: 5,
    accept: '.pdf,.doc,.docx',
    fileSize: 20
  }
])

ImageUpload

图片上传组件（基于 FileUpload）：

<template>
  <ImageUpload v-model:fileId="form.avatar" :max="1" />
</template>

<script setup>
import ImageUpload from '@/components/file-upload/ImageUpload.vue'

const form = reactive({ avatar: '' })
</script>

重要：imageUpload 组件存储的是 fileId，不是 URL。

AuthImage

渲染需要认证的图片。由于后端图片接口需要 Token，直接用 NAvatar 的 src 属性无法携带 Token，必须使用 AuthImage：

<template>
  <!-- 正确：使用 AuthImage，自动带 Token -->
  <AuthImage :file-id="row.avatar" />

  <!-- 禁止：直接用 NAvatar src，无法携带 Token -->
  <NAvatar :src="row.avatarUrl" />
</template>

<script setup>
import AuthImage from '@/components/common/AuthImage.vue'
</script>

表格中渲染图片

const schema = computed(() => [
  {
    field: 'avatar',
    label: '头像',
    component: 'AuthImage',
    width: 80
  }
])

getFileUrl

获取文件的下载链接：

import { getFileUrl } from '@/utils/file'

// 获取下载 URL
const url = getFileUrl(fileId)

// 在新窗口打开
window.open(url)

文件访问流程

前端 AuthImage
    ↓
fetch + Authorization: Bearer <token>
    ↓
后端文件服务验证 Token
    ↓
返回图片二进制流
    ↓
AuthImage 渲染为 blob URL

上传流程

FileUpload 选择文件
    ↓
POST /file/upload（multipart/form-data，自动带 Token）
    ↓
后端存储文件，返回 fileId
    ↓
v-model:fileId 绑定 fileId
    ↓
提交表单时 fileId 随表单提交

注意事项

• 存储 fileId 而非 URL：imageUpload 和 FileUpload 的 v-model 都是 fileId
• 表格图片用 AuthImage：自动携带 Token，禁止直接用 NAvatar src
• 下载链接用 getFileUrl(fileId)：不要手动拼接 URL
• 文件类型校验：前端配置 accept 和 fileType，后端也需校验