组件

vue-select-avatar 提供了两个核心组件：<Viewport/>（视口裁剪组件）和 <Preview/>（预览组件）。

<Viewport/>

视口裁剪组件，用于显示图片并提供裁剪交互功能。

基本示例

<script setup lang="ts">
import { ref } from 'vue'
import { Viewport } from 'vue-select-avatar'

const viewportRef = ref()

const handleCrop = async () => {
  const file = await viewportRef.value.crop({
    size: 200,
    type: 'image/jpeg',
    quality: 0.9,
  })
  console.log('裁剪后的文件:', file)
}
</script>

<template>
  <Viewport ref="viewportRef" />
  <button @click="handleCrop">裁剪</button>
</template>

Props

export interface ViewportProps {
  /**
   * 视口尺寸（同时设置宽高）
   *
   * @default 300
   */
  size?: number | 'full'
  /**
   * 视口宽度（覆盖size）
   */
  width?: number | 'full'
  /**
   * 视口高度（覆盖size）
   */
  height?: number | 'full'
  /**
   * 图片信息
   */
  info?: ImageInfo
  /**
   * 观察窗口大小（<=1 表示比例，>1 表示像素值）
   *
   * @default 0.6
   */
  view?: number
  /**
   * 是否为网格背景
   *
   * @default false
   */
  grid?: boolean
  /**
   * 缩放步长（<1 表示比例，>=1 表示像素值）
   *
   * @default 0.05
   */
  step?: number
  /**
   * 缩放步长（按下Ctrl键时，设置为0时，则不生效，<1 表示比例，>=1 表示像素值）
   *
   * @default 0.02
   */
  ctrlStep?: number
  /**
   * 缩放步长（按下Shift键时，设置为0时，则不生效，<1 表示比例，>=1 表示像素值）
   *
   * @default 2
   */
  shiftStep?: number
  /**
   * 滚轮反向
   *
   * @default false
   */
  reverse?: boolean
  /**
   * 最小观察窗口尺寸（mode=fixed-image 时生效）
   *
   * @default 10
   */
  minView?: number
  /**
   * 图片边距（mode=fixed-image 时生效）
   *
   * @default 10
   */
  padding?: number
  /**
   * 方向键移动
   *
   * @default true
   */
  arrow?: boolean
  /**
   * wasd 键移动
   *
   * @default true
   */
  wasd?: boolean
  /**
   * 遮罩实现方式
   *
   * - 'clip'：使用 clip-path
   * - 'double'：使用双层图片
   *
   * @default 'clip'
   */
  mask?: 'clip' | 'double'
  /**
   * 移动模式：'fixed-view'=观察窗固定图片移动，'fixed-image'=图片固定观察窗移动
   *
   * @default 'fixed-view'
   */
  mode?: 'fixed-view' | 'fixed-image'
  /**
   * 是否显示观察窗边框
   *
   * @default false
   */
  border?: boolean | number
}

Slots

插槽名称	描述
point-top-left	左上角控制点自定义内容（仅在 mode='fixed-image' 时生效）
point-top-right	右上角控制点自定义内容（仅在 mode='fixed-image' 时生效）
point-bottom-left	左下角控制点自定义内容（仅在 mode='fixed-image' 时生效）
point-bottom-right	右下角控制点自定义内容（仅在 mode='fixed-image' 时生效）

Exposes

export interface ViewportExposes {
  /**
   * 选择图片
   * @param options 选择图片选项
   */
  select: (options?: ImageSelectOptions) => Promise<void>
  /**
   * 裁剪图片
   * @param options 裁剪选项
   * @returns 裁剪后的图片信息
   */
  crop: <T extends File | string = string | File>(options?: CropOptions) => Promise<T>
  /**
   * 初始化位置信息
   * @param res 图片信息
   */
  positionInit: (res: ImageSelectResult) => void
}

<Preview/>

预览组件，用于实时显示裁剪效果。需要与 Viewport 组件配合使用。

基本示例

<script setup lang="ts">
import { ref } from 'vue'
import { Viewport, Preview } from 'vue-select-avatar'

const viewportRef = ref()
</script>

<template>
  <Viewport ref="viewportRef" />
  <Preview :viewport-ref="viewportRef" round />
</template>

Props

export interface PreviewProps {
  /**
   * 预览尺寸
   *
   * @default 180
   */
  size?: number | 'full'
  /**
   * 视口实例
   */
  viewportRef?: ViewportInstance
  /**
   * 是否圆形
   */
  round?: boolean
  /**
   * 背景颜色
   */
  bg?: string
}

Slots

Preview 组件不提供插槽。

Exposes

Preview 组件不提供暴露的方法。