ImageUpload 图片上传

介绍

图片上传组件，支持多选、预览、删除，以及上传状态展示。适用于表单中的图片上传场景。

引入

import { TnImageUpload, TnUploadFile } from "@tuniao/tn-ui";

TnUploadFile 类说明

TnUploadFile 是一个 @ObservedV2 类，包含以下属性：

属性	说明	类型
url	图片地址	string
status	上传状态	"ready" | "uploading" | "success" | "error"
progress	上传进度（0-100）	number
message	提示信息	string

代码演示

基础用法

通过 fileList 属性传入文件列表，配合 onChoose 事件处理文件选择。

点我查看代码

@Local fileList: TnUploadFile[] = [];

TnImageUpload({
  fileList: this.fileList,
  onChoose: (files: TnUploadFile[]) => {
    this.fileList = [...this.fileList, ...files];
  },
  onDelete: (file: TnUploadFile, index: number) => {
    this.fileList = this.fileList.filter(
      (item: TnUploadFile, i: number) => i !== index
    );
  },
})

限制数量

通过 maxCount 属性限制最大上传数量，达到上限后上传区域自动隐藏。

点我查看代码

@Local fileList: TnUploadFile[] = [];

TnImageUpload({
  fileList: this.fileList,
  maxCount: 3,
  onChoose: (files: TnUploadFile[]) => {
    this.fileList = [...this.fileList, ...files];
  },
  onDelete: (file: TnUploadFile, index: number) => {
    this.fileList = this.fileList.filter(
      (item: TnUploadFile, i: number) => i !== index
    );
  },
})

多列布局

通过 columns 属性设置每行显示的列数。

点我查看代码

@Local fileList: TnUploadFile[] = [];

TnImageUpload({
  fileList: this.fileList,
  columns: 4,
  onChoose: (files: TnUploadFile[]) => {
    this.fileList = [...this.fileList, ...files];
  },
  onDelete: (file: TnUploadFile, index: number) => {
    this.fileList = this.fileList.filter(
      (item: TnUploadFile, i: number) => i !== index
    );
  },
})

自定义上传区域

通过 uploadIcon 和 uploadText 属性自定义上传区域的图标和文案。

点我查看代码

@Local fileList: TnUploadFile[] = [];

TnImageUpload({
  fileList: this.fileList,
  uploadIcon: "camera",
  uploadText: "拍照上传",
  onChoose: (files: TnUploadFile[]) => {
    this.fileList = [...this.fileList, ...files];
  },
  onDelete: (file: TnUploadFile, index: number) => {
    this.fileList = this.fileList.filter(
      (item: TnUploadFile, i: number) => i !== index
    );
  },
})

禁用状态

通过 disabled 属性禁用上传组件，禁用后不可选择和删除图片。

点我查看代码

@Local fileList: TnUploadFile[] = [
  { url: "https://example.com/image1.jpg", status: "success", progress: 100, message: "" } as TnUploadFile,
];

TnImageUpload({
  fileList: this.fileList,
  disabled: true,
})

模拟上传

通过模拟上传过程，展示上传进度动画和上传状态。

点我查看代码

@Local uploadDemoFileList: TnUploadFile[] = [];

TnImageUpload({
  fileList: this.uploadDemoFileList,
  onChoose: (files: TnUploadFile[]) => {
    this.addFilesWithUpload(files);
  },
  onDelete: (file: TnUploadFile, index: number) => {
    this.deleteUploadDemoFile(index);
  }
});
/**
 * 添加文件并模拟上传过程
 * @param files 待添加的文件数组
 */
addFilesWithUpload(files: TnUploadFile[]): void {
  const uploadingFiles: TnUploadFile[] = files.map((f: TnUploadFile): TnUploadFile => {
    return new TnUploadFile(f.url, "uploading");
  });
  this.uploadDemoFileList = [...this.uploadDemoFileList, ...uploadingFiles];
  for (let i: number = 0; i < uploadingFiles.length; i++) {
    this.simulateUpload(uploadingFiles[i]);
  }
}
/**
 * 删除模拟上传列表中的指定文件
 * @param index 待删除文件的索引
 */
deleteUploadDemoFile(index: number): void {
  this.uploadDemoFileList = this.uploadDemoFileList.filter((_item: TnUploadFile, i: number) => i !== index);
}

/**
 * 模拟单个文件的上传过程
 * 直接修改 TnUploadFile 的 @Trace 属性，仅触发进度文字的局部刷新
 * @param file 文件对象引用
 */
private simulateUpload(file: TnUploadFile): void {
  const timerId: number = setInterval(() => {
    if (file.status !== "uploading") {
      clearInterval(timerId);
      return;
    }
    const newProgress: number = file.progress + UPLOAD_STEP;
    if (newProgress >= 100) {
      clearInterval(timerId);
      const isFail: boolean = Math.random() < FAIL_THRESHOLD;
      file.progress = 100;
      file.status = isFail ? "error" : "success";
      file.message = isFail ? "上传失败" : "";
    } else {
      file.progress = newProgress;
    }
  }, UPLOAD_INTERVAL);
}

API

Props

参数	说明	类型	默认值
fileList	文件列表	TnUploadFile[]	-
maxCount	最大上传数量	number	9
multiple	是否支持多选	boolean	false
disabled	是否禁用	boolean	false
deletable	是否可删除	boolean	true
previewImage	是否支持预览	boolean	true
columns	每行列数	number	3
uploadIcon	上传区域图标	string	"add-circle"
uploadText	上传区域文案	string	""

Events

事件名	说明	回调参数
onChoose	选择文件后触发	(files: TnUploadFile[]) => void
onDelete	删除文件时触发	(file: TnUploadFile, index: number) => void
onPreview	预览图片时触发	(file: TnUploadFile, index: number) => void
onOversize	文件超出大小限制时触发	(files: TnUploadFile[]) => void