4.4 KiB

Raw Blame History

Upload 上传组件 API 文档

组件路径

@/components/uploadFile/index

说明

上传接口地址固定为 app.globalData.upFileUrl，组件内部自动附加 loginState，无需外部传入。

组件仅提供上传按钮，不维护文件列表状态，不显示文件列表，不包含文件预览功能。父页面需要自行处理文件列表的显示和管理。

组件通过事件通知父页面文件选择、上传进度、上传成功、上传失败等状态，父页面需要监听这些事件并更新自己的文件列表。

Properties 入参

参数	说明	类型	默认值	必填
`maxCount`	最大上传文件数	`Number`	`9`	否
`maxSize`	单文件最大限制（byte）	`Number`	`10485760`（10MB）	否
`accept`	允许的文件类型数组，可选值：`'image'` \| `'video'` \| `'file'`	`Array`	`['image']`	否
`extensions`	自定义文件后缀（仅 accept 含 `'file'` 时生效），如 `['.pdf', '.doc']`	`Array`	`[]`	否
`readonly`	只读模式（不显示上传按钮）	`Boolean`	`false`	否
`useSlot`	是否使用自定义上传区域插槽	`Boolean`	`false`	否
`fileList`	已有文件列表（用于判断是否还能上传）	`Array`	`[]`	否

fileList 数据结构

{
  uid: string       // 文件唯一标识
  url: string       // 文件路径
  type: string      // 文件类型: 'image' | 'video' | 'file'
  name: string      // 文件名
  size: number      // 文件大小(byte)
}

Events 事件

事件名	说明	回调参数
`bind:success`	单文件上传完成	`{ file: UploadFile, response: any }`
`bind:error`	上传失败	`{ file: UploadFile, error: Error }`

事件返回的 UploadFile 结构

{
  uid: string                              // 文件唯一标识
  url: string                              // 文件路径（上传成功后为远程 url）
  type: 'image' | 'video' | 'file'         // 文件类型
  name: string                             // 文件名
  size: number                             // 文件大小(byte)
  status: 'pending' | 'uploading' | 'success' | 'error'  // 上传状态
  progress: number                         // 上传进度 0-100
}

Slots 插槽

插槽名	说明
`upload-area`	自定义上传区域布局，需同时设置 `useSlot="{{true}}"`。使用时上传触发器尺寸自适应 slot 内容

CSS 变量

变量名	说明	默认值
`--upload-bg`	上传区域背景色	`#f7f8fa`
`--upload-border`	边框颜色	`#e5e7eb`
`--upload-text-secondary`	次要文字颜色	`#9ca3af`
`--upload-radius`	圆角大小	`16rpx`
`--upload-size`	上传按钮尺寸（仅默认上传框生效，slot 模式自适应）	`160rpx`

使用案例

案例 1：使用默认上传框

// page.json
{
  "usingComponents": {
    "upload-file": "@/components/uploadFile/index"
  }
}

<!-- page.wxml -->
<upload-file
  maxCount="{{3}}"
  maxSize="{{5242880}}"
  accept="{{['image']}}"
  fileList="{{fileList}}"
  bind:success="onUploadSuccess"
  bind:error="onUploadError"
/>

// page.ts
Page({
  data: {
    fileList: [] as UploadFile[],
  },

  onUploadSuccess(e: WechatMiniprogram.CustomEvent) {
    console.log('上传成功', e.detail.file, e.detail.response)
    // 添加上传成功的文件到列表
    this.setData({
      fileList: [...this.data.fileList, e.detail.file],
    })
  },

  onUploadError(e: WechatMiniprogram.CustomEvent) {
    console.log('上传失败', e.detail.file, e.detail.error)
    wx.showToast({ title: '文件上传失败', icon: 'none' })
  },
})

案例 2：使用 slot 自定义上传区域

<!-- page.wxml -->
<upload-file
  useSlot="{{true}}"
  maxCount="{{5}}"
  accept="{{['image', 'video']}}"
  fileList="{{fileList}}"
  bind:success="onUploadSuccess"
>
  <view slot="upload-area" class="custom-upload-area">
    <image src="/images/upload-icon.png" mode="aspectFit" />
    <text>点击上传</text>
  </view>
</upload-file>

// page.scss
.custom-upload-area {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12rpx;

  image {
    width: 64rpx;
    height: 64rpx;
  }

  text {
    font-size: 24rpx;
    color: #9ca3af;
  }
}

4.4 KiB Raw Blame History