API

这里列出了 vue-select-avatar 提供的所有 JavaScript API，均提供完整的 TypeScript 类型定义，支持智能提示和类型检查。

selectImage

从用户设备选择图片文件并进行验证和处理。

类型签名：

function selectImage(options?: ImageSelectOptions): Promise<ImageSelectResult>

使用示例：

import { selectImage } from 'vue-select-avatar'

const result = await selectImage({
  accept: 'image/jpeg, image/png',
  maxFileSize: 5 * 1024 * 1024, // 5MB
  compress: true,
  quality: 0.8,
})

console.log('选择的文件:', result.file)
console.log('图片尺寸:', result.width, 'x', result.height)

ImageSelectOptions

export interface ImageSelectOptions {
  /**
   * 允许的文件类型（参考input的accept属性）
   *
   * @default DEFAULT_ACCEPT
   */
  accept?: string
  /**
   * 最大文件大小（单位：字节）
   * @default 2 * 1024 * 1024
   */
  maxFileSize?: number
  /**
   * 图片最小尺寸（宽高任一小于该值则无效）
   */
  minSize?: number
  /**
   * 图片最大尺寸（宽高任一超过该值则无效）
   * @default 5000
   */
  maxSize?: number
  /**
   * 超过最大尺寸时是否等比例缩放到最大尺寸
   * @default false
   */
  resizeToMax?: boolean
  /**
   * 是否启用压缩
   * - true：全部压缩
   * - number：文件大于该值时压缩（单位：字节）
   * @default false
   */
  compress?: boolean | number
  /**
   * 压缩质量（0-1）
   * @default 0.8
   */
  quality?: number
  /**
   * 矢量图最小尺寸
   * @default 1024
   */
  minVectorSize?: number
}

ImageSelectResult

export interface ImageSelectResult {
  file: File
  width: number
  height: number
}

selectFile

选择文件而不进行图片验证和处理。

类型签名：

function selectFile(options?: SelectFileOptions): Promise<File[]>

使用示例：

import { selectFile } from 'vue-select-avatar'

const files = await selectFile({
  accept: '.jpg,.png,.gif',
  multiple: true,
})

console.log('选择的文件数量:', files.length)

loadImage

加载图片并返回 HTMLImageElement 对象。

类型签名：

function loadImage(url: string, revoke?: boolean): Promise<HTMLImageElement>

使用示例：

import { loadImage } from 'vue-select-avatar'

const img = await loadImage('https://example.com/image.jpg')
console.log('图片尺寸:', img.width, 'x', img.height)

参数：

参数	类型	默认值	描述
url	string	-	图片 URL
revoke	boolean	false	是否在加载完成后撤销 Object URL

canvasToBlob

将 Canvas 元素转换为 Blob 对象。

类型签名：

function canvasToBlob(canvas: HTMLCanvasElement, type?: string, quality?: number): Promise<Blob>

使用示例：

import { canvasToBlob } from 'vue-select-avatar'

const canvas = document.createElement('canvas')
// ... 绘制内容到 canvas ...

const blob = await canvasToBlob(canvas, 'image/jpeg', 0.9)
console.log('Blob 大小:', blob.size, 'bytes')

参数：

参数	类型	默认值	描述
canvas	HTMLCanvasElement	-	Canvas 元素
type	string	'image/png'	MIME 类型
quality	number	-	图片质量（0-1），仅对有损压缩格式（如 image/jpeg、image/webp）有效

blobToBase64

将 Blob 对象转换为 Base64 字符串。

类型签名：

function blobToBase64(blob: Blob): Promise<string>

使用示例：

import { blobToBase64 } from 'vue-select-avatar'

const base64 = await blobToBase64(blob)
console.log('Base64 字符串长度:', base64.length)

常量

DEFAULT_ACCEPT

默认接受的文件类型。

const DEFAULT_ACCEPT =
  'image/jpeg, image/png, image/webp, image/bmp, image/svg+xml, image/avif, image/tiff'

类型定义

ViewportInstance

export type ViewportInstance = InstanceType<typeof Viewport>

ImageSelectResult

export interface ImageSelectResult {
  file: File
  width: number
  height: number
}

ImageSelectOptions

export interface ImageSelectOptions {
  /**
   * 允许的文件类型（参考input的accept属性）
   *
   * @default DEFAULT_ACCEPT
   */
  accept?: string
  /**
   * 最大文件大小（单位：字节）
   * @default 2 * 1024 * 1024
   */
  maxFileSize?: number
  /**
   * 图片最小尺寸（宽高任一小于该值则无效）
   */
  minSize?: number
  /**
   * 图片最大尺寸（宽高任一超过该值则无效）
   * @default 5000
   */
  maxSize?: number
  /**
   * 超过最大尺寸时是否等比例缩放到最大尺寸
   * @default false
   */
  resizeToMax?: boolean
  /**
   * 是否启用压缩
   * - true：全部压缩
   * - number：文件大于该值时压缩（单位：字节）
   * @default false
   */
  compress?: boolean | number
  /**
   * 压缩质量（0-1）
   * @default 0.8
   */
  quality?: number
  /**
   * 矢量图最小尺寸
   * @default 1024
   */
  minVectorSize?: number
}

CropOptions

export interface CropOptions {
  /**
   * 数据格式
   */
  format?: CropFormat
  /**
   * 输出图片尺寸
   */
  size?: number
  /**
   * 最大输出图片尺寸（如果截取图片尺寸超过该值则等比例缩放到该尺寸，如果设置了 size，该属性则无效）
   */
  maxSize?: number
  /**
   * 如果截取图片尺寸小于 size 时，则使用截取图片的尺寸
   * （如果还是使用 size 作为图片尺寸，则会将图片等比例放大，会造成文件大小变大）
   * （仅在设置了 size 时生效）
   */
  useOriginSize?: boolean
  /**
   * 输出图片类型
   */
  type?: 'image/jpeg' | 'image/png' | 'image/webp'
  /**
   * 输出图片质量（0-1）
   */
  quality?: number
  /**
   * 文件名
   */
  filename?: string
  /**
   * 当输出图片类型为 image/jpeg 的底色
   */
  backgroundColor?: string
}

Position

/**
 * 位置信息
 */
export interface Position {
  viewportWidth: number
  viewportHeight: number
  viewX: number
  viewY: number
  viewSize: number
  imageX: number
  imageY: number
  imageWidth: number
  imageHeight: number
  imageScale: number
}

ErrorCode

export type ErrorCode =
  | 'UNKNOWN' // 未知错误
  | 'CANCEL' // 取消
  | 'NOT_IMAGE_FILES' // 非图片文件
  | 'IMAGE_FILE_TOO_LARGE' // 图片文件过大
  | 'IMAGE_TOO_SMALL' // 图片尺寸过小
  | 'IMAGE_TOO_LARGE' // 图片尺寸过大
  | 'IMAGE_LOAD_FAILED' // 图片加载失败
  | 'CANVAS_TO_BLOB_FAILED' // canvas 转 blob 失败
  | 'BLOB_TO_BASE64_FAILED' // blob 转 base64 失败
  | 'CANVAS_CONTEXT_NOT_DEFINED' // canvas context 未定义
  | 'NO_IMAGE_SELECTED' // 未选择图片