@veltra/desktop 1.7.8 → 1.7.10

package/src/components/image-cropper/__test__/use-transform.test.ts

@@ -0,0 +1,229 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createApp, shallowRef } from 'vue'
+
+import { useTransform } from '../use-transform'
+
+/** 挂载一个空组件以提供组合式函数所需的组件上下文 */
+function mountTransform(options?: { onReset?: () => void }) {
+  const target = shallowRef<HTMLElement>()
+  let api!: ReturnType<typeof useTransform>
+
+  const app = createApp({
+    setup() {
+      api = useTransform({
+        target,
+        // 画布 400×300，图片 800×600：适应缩放为 0.5
+        canvasSize: () => ({ width: 400, height: 300 }),
+        imageWidth: () => 800,
+        imageHeight: () => 600,
+        onReset: options?.onReset ?? (() => {})
+      })
+      return () => null
+    }
+  })
+
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  app.mount(host)
+
+  return {
+    api,
+    target,
+    unmount() {
+      app.unmount()
+      host.remove()
+    }
+  }
+}
+
+describe('useTransform', () => {
+  let unmount: (() => void) | undefined
+
+  afterEach(() => {
+    unmount?.()
+  })
+
+  it('fit：按容器适应缩放并居中', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+
+    api.fit()
+    expect(api.transform.scale).toBe(0.5)
+    expect(api.transform.translateX).toBe(-200)
+    expect(api.transform.translateY).toBe(-150)
+  })
+
+  it('zoomTo：钳制在适应缩放与其 10 倍之间', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    api.zoomTo(0.1)
+    expect(api.transform.scale).toBe(0.5)
+
+    api.zoomTo(100)
+    expect(api.transform.scale).toBe(5)
+  })
+
+  it('zoomIn / zoomOut：默认以画布中心为锚，中心点平移不变', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    api.zoomIn()
+    expect(api.transform.scale).toBeCloseTo(0.6, 10)
+    expect(api.transform.translateX).toBeCloseTo(-200, 10)
+    expect(api.transform.translateY).toBeCloseTo(-150, 10)
+
+    api.zoomOut()
+    expect(api.transform.scale).toBeCloseTo(0.5, 10)
+  })
+
+  it('zoomIn：以指定锚点缩放时锚点下的图片点保持不动', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    api.zoomIn({ x: 0, y: 0 })
+    expect(api.transform.scale).toBeCloseTo(0.6, 10)
+    expect(api.transform.translateX).toBeCloseTo(-160, 8)
+    expect(api.transform.translateY).toBeCloseTo(-120, 8)
+  })
+
+  it('rotate：90° 步进并归一化，90° / 270° 按交换宽高重新适应', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    api.rotate(1)
+    expect(api.transform.rotation).toBe(90)
+    // 交换宽高后：min(400/600, 300/800) = 0.375
+    expect(api.transform.scale).toBe(0.375)
+
+    api.rotate(-1)
+    expect(api.transform.rotation).toBe(0)
+    expect(api.transform.scale).toBe(0.5)
+
+    api.rotate(-1)
+    expect(api.transform.rotation).toBe(270)
+    api.rotate(1)
+    api.rotate(1)
+    expect(api.transform.rotation).toBe(90)
+  })
+
+  it('flip：水平 / 垂直翻转互不影响', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+
+    api.flip('horizontal')
+    expect(api.transform.flipX).toBe(true)
+    expect(api.transform.flipY).toBe(false)
+
+    api.flip('vertical')
+    expect(api.transform.flipX).toBe(true)
+    expect(api.transform.flipY).toBe(true)
+
+    api.flip('horizontal')
+    expect(api.transform.flipX).toBe(false)
+  })
+
+  it('resetTransform：恢复初始变换、重新适应并复位选区', () => {
+    const onReset = vi.fn()
+    const { api, unmount: u } = mountTransform({ onReset })
+    unmount = u
+    api.fit()
+
+    api.zoomIn()
+    api.rotate(1)
+    api.flip('horizontal')
+
+    api.resetTransform()
+    expect(api.transform).toMatchObject({
+      scale: 0.5,
+      translateX: -200,
+      translateY: -150,
+      rotation: 0,
+      flipX: false,
+      flipY: false
+    })
+    expect(onReset).toHaveBeenCalledTimes(1)
+  })
+
+  it('toImageDelta：按缩放 / 旋转 / 翻转换算屏幕位移', () => {
+    const { api, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    expect(api.toImageDelta(60, 30)).toEqual({ x: 120, y: 60 })
+
+    // 旋转 90°（顺时针）：屏幕右移对应图片 -y 方向
+    api.rotate(1)
+    const rotated = api.toImageDelta(10, 0)
+    expect(rotated.x).toBeCloseTo(0, 10)
+    expect(rotated.y).toBeCloseTo(-10 / 0.375, 10)
+
+    api.resetTransform()
+    api.flip('horizontal')
+    expect(api.toImageDelta(10, 0).x).toBeCloseTo(-20, 10)
+  })
+
+  it('图片未超出容器时选区外拖动不平移，超出后拖动平移', async () => {
+    const { api, target, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    const canvas = document.createElement('div')
+    // happy-dom 的 DOMRect 字段为 undefined，补零保证锚点计算
+    canvas.getBoundingClientRect = () => ({ left: 0, top: 0 }) as DOMRect
+    target.value = canvas
+    await Promise.resolve()
+
+    // 适应尺寸 400×300 未超出容器：拖动不平移
+    canvas.dispatchEvent(new MouseEvent('mousedown', { button: 0, clientX: 100, clientY: 100 }))
+    document.dispatchEvent(new MouseEvent('mousemove', { clientX: 130, clientY: 115 }))
+    document.dispatchEvent(new MouseEvent('mouseup'))
+    expect(api.transform.translateX).toBe(-200)
+    expect(api.transform.translateY).toBe(-150)
+
+    // 放大到 0.6 后显示尺寸 480×360 超出容器：拖动平移
+    api.zoomIn()
+    canvas.dispatchEvent(new MouseEvent('mousedown', { button: 0, clientX: 100, clientY: 100 }))
+    document.dispatchEvent(new MouseEvent('mousemove', { clientX: 130, clientY: 115 }))
+    document.dispatchEvent(new MouseEvent('mouseup'))
+    expect(api.transform.translateX).toBeCloseTo(-170, 10)
+    expect(api.transform.translateY).toBeCloseTo(-135, 10)
+
+    // 抬起后再次移动不再平移
+    document.dispatchEvent(new MouseEvent('mousemove', { clientX: 200, clientY: 200 }))
+    expect(api.transform.translateX).toBeCloseTo(-170, 10)
+  })
+
+  it('wheel：以指针位置为锚缩放', async () => {
+    const { api, target, unmount: u } = mountTransform()
+    unmount = u
+    api.fit()
+
+    const canvas = document.createElement('div')
+    // happy-dom 的 DOMRect 字段为 undefined，补零保证锚点计算
+    canvas.getBoundingClientRect = () => ({ left: 0, top: 0 }) as DOMRect
+    target.value = canvas
+    await Promise.resolve()
+
+    // happy-dom 的 WheelEvent 不携带 clientX / clientY，用 MouseEvent 模拟并补 deltaY
+    const wheel = (deltaY: number) => {
+      const e = new MouseEvent('wheel', { clientX: 0, clientY: 0 })
+      Object.defineProperty(e, 'deltaY', { value: deltaY })
+      canvas.dispatchEvent(e)
+    }
+
+    wheel(-100)
+    expect(api.transform.scale).toBeCloseTo(0.6, 10)
+    expect(api.transform.translateX).toBeCloseTo(-160, 8)
+    expect(api.transform.translateY).toBeCloseTo(-120, 8)
+
+    // 缩小被钳制在适应缩放
+    wheel(100)
+    wheel(100)
+    expect(api.transform.scale).toBe(0.5)
+  })
+})

package/src/components/image-cropper/draw-crop.ts

@@ -0,0 +1,112 @@
+import type { ImageCropperResult } from '../../types'
+import type { SelectionRect } from './use-selection'
+
+/** 影响裁剪输出的变换（缩放 / 平移只影响画布展示，与输出无关） */
+export interface CropTransform {
+  /** 90° 步进角度：0 / 90 / 180 / 270 */
+  rotation: number
+  flipX: boolean
+  flipY: boolean
+}
+
+/** 输出尺寸，缺省维度按选区比例推算，都不传则为原图选区像素尺寸 */
+export interface CropOutputSize {
+  width?: number
+  height?: number
+}
+
+/**
+ * 把选区按当前旋转 / 翻转变换绘制到目标 canvas，预览（P4）与 getResult()（P5）共用。
+ * 输出为屏幕上看到的裁剪结果：先旋转后翻转，与舞台 transform 链一致
+ */
+export function drawCropToCanvas(
+  img: HTMLImageElement,
+  selection: SelectionRect,
+  transform: CropTransform,
+  canvas: HTMLCanvasElement,
+  outSize?: CropOutputSize
+): void {
+  const { rotation, flipX, flipY } = transform
+  // 旋转 90° / 270° 后输出的宽为选区高、高为选区宽
+  const swapped = rotation % 180 !== 0
+  const baseW = swapped ? selection.height : selection.width
+  const baseH = swapped ? selection.width : selection.height
+
+  const outW = Math.max(
+    1,
+    Math.round(outSize?.width ?? ((outSize?.height ?? baseH) / baseH) * baseW)
+  )
+  const outH = Math.max(
+    1,
+    Math.round(outSize?.height ?? ((outSize?.width ?? baseW) / baseW) * baseH)
+  )
+  canvas.width = outW
+  canvas.height = outH
+
+  const ctx = canvas.getContext('2d')
+  if (!ctx) return
+
+  ctx.translate(outW / 2, outH / 2)
+  ctx.rotate((rotation * Math.PI) / 180)
+  ctx.scale(((flipX ? -1 : 1) * outW) / baseW, ((flipY ? -1 : 1) * outH) / baseH)
+  // 以画布中心为锚绘制选区，旋转 / 翻转由上面的变换承担
+  ctx.drawImage(
+    img,
+    selection.x,
+    selection.y,
+    selection.width,
+    selection.height,
+    -selection.width / 2,
+    -selection.height / 2,
+    selection.width,
+    selection.height
+  )
+}
+
+/**
+ * canvas 导出为 Blob。
+ * 跨域图片污染画布时 toBlob 同步抛 SecurityError，包装为可捕获的 Promise 拒绝
+ */
+function canvasToBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    try {
+      canvas.toBlob((blob) => {
+        if (blob) resolve(blob)
+        else reject(new Error('Export crop result failed: canvas.toBlob got null'))
+      }, 'image/png')
+    } catch (err) {
+      reject(
+        new Error('Export crop result failed: canvas is tainted by cross-origin image', {
+          cause: err
+        })
+      )
+    }
+  })
+}
+
+/** Blob 读取为 dataURL 形式的 base64 */
+function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(reader.result as string)
+    reader.onerror = () =>
+      reject(reader.error ?? new Error('Export crop result failed: read blob as base64 failed'))
+    reader.readAsDataURL(blob)
+  })
+}
+
+/**
+ * 输出选区裁剪结果：离屏 canvas 经 drawCropToCanvas 按原图像素绘制后导出 Blob + base64。
+ * outSize 缺省为原图选区像素尺寸，传入则按该尺寸缩放输出
+ */
+export async function cropToResult(
+  img: HTMLImageElement,
+  selection: SelectionRect,
+  transform: CropTransform,
+  outSize?: CropOutputSize
+): Promise<ImageCropperResult> {
+  const canvas = document.createElement('canvas')
+  drawCropToCanvas(img, selection, transform, canvas, outSize)
+  const blob = await canvasToBlob(canvas)
+  return { blob, base64: await blobToBase64(blob) }
+}

package/src/components/image-cropper/image-cropper.vue

@@ -0,0 +1,302 @@
+<template>
+  <div :class="cls.b">
+    <div v-if="showToolbar" :class="cls.e('toolbar')">
+      <slot
+        name="toolbar"
+        :zoom-in="zoomIn"
+        :zoom-out="zoomOut"
+        :rotate="rotate"
+        :flip="flip"
+        :reset="resetTransform"
+        :set-aspect-ratio="setAspectRatio"
+        :aspect-ratio="currentRatio"
+      >
+        <!-- 宽高比预设 -->
+        <div :class="cls.e('tool-group')">
+          <button
+            v-for="preset in RATIO_PRESETS"
+            :key="preset.label"
+            type="button"
+            :class="[cls.e('tool'), bem.is('active', preset.value === currentRatio)]"
+            @click="setAspectRatio(preset.value)"
+          >
+            {{ preset.label }}
+          </button>
+        </div>
+
+        <!-- 缩放 / 旋转 / 翻转 / 重置 -->
+        <div :class="cls.e('tool-group')">
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="缩小"
+            title="缩小"
+            @click="zoomOut()"
+          >
+            <u-icon :size="15"><ZoomOut /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="放大"
+            title="放大"
+            @click="zoomIn()"
+          >
+            <u-icon :size="15"><ZoomIn /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="逆时针旋转 90°"
+            title="逆时针旋转 90°"
+            @click="rotate(-1)"
+          >
+            <u-icon :size="15"><RotateLeft /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="顺时针旋转 90°"
+            title="顺时针旋转 90°"
+            @click="rotate(1)"
+          >
+            <u-icon :size="15"><RotateRight /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="水平翻转"
+            title="水平翻转"
+            @click="flip('horizontal')"
+          >
+            <u-icon :size="15" :class="cls.e('flip-icon')"><ArrowUpdown /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="垂直翻转"
+            title="垂直翻转"
+            @click="flip('vertical')"
+          >
+            <u-icon :size="15"><ArrowUpdown /></u-icon>
+          </button>
+          <button
+            type="button"
+            :class="[cls.e('tool'), cls.em('tool', 'icon')]"
+            aria-label="重置"
+            title="重置"
+            @click="resetTransform()"
+          >
+            <u-icon :size="15"><Refresh /></u-icon>
+          </button>
+        </div>
+      </slot>
+    </div>
+
+    <div :class="cls.e('canvas')" ref="canvasRef">
+      <div v-if="loaded" :class="cls.e('stage')" :style="stageStyle">
+        <img :class="cls.e('image')" :src="imageUrl" draggable="false" alt="" />
+
+        <template v-if="selection">
+          <!-- 选区外半透明遮罩 -->
+          <div v-for="(style, i) in maskStyles" :key="i" :class="cls.e('mask')" :style="style" />
+
+          <!-- 裁剪选区：整体拖动 + 8 个手柄调整大小 -->
+          <div :class="cls.e('selection')" ref="selectionRef" :style="selectionStyle">
+            <!-- 3×3 网格线，顺序对应 style.scss 中 nth-child 的定位 -->
+            <i v-for="i in 4" :key="i" :class="cls.e('grid-line')" />
+            <i
+              v-for="handle in SELECTION_HANDLES"
+              :key="handle"
+              :class="cls.e('handle')"
+              :data-handle="handle"
+            />
+          </div>
+        </template>
+      </div>
+    </div>
+
+    <div v-if="showPreview && loaded" :class="cls.e('preview')">
+      <canvas :class="cls.e('preview-canvas')" ref="previewCanvasRef" />
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { useResizeObserver } from '@veltra/compositions'
+import {
+  ArrowUpdown,
+  Refresh,
+  RotateLeft,
+  RotateRight,
+  ZoomIn,
+  ZoomOut
+} from '@veltra/icons/normal'
+import { bem } from '@veltra/utils'
+import { computed, reactive, shallowRef, watch } from 'vue'
+
+import type {
+  ImageCropperProps,
+  ImageCropperEmits,
+  ImageCropperResult,
+  ImageCropperResultOptions,
+  _ImageCropperExposed
+} from '../../types'
+import { UIcon } from '../icon'
+import { cropToResult } from './draw-crop'
+import { useImageLoader } from './use-image-loader'
+import { usePreview } from './use-preview'
+import { SELECTION_HANDLES, useSelection } from './use-selection'
+import { useTransform } from './use-transform'
+
+defineOptions({ name: 'ImageCropper' })
+
+const props = withDefaults(defineProps<ImageCropperProps>(), {
+  showToolbar: true,
+  showPreview: true
+})
+
+const emit = defineEmits<ImageCropperEmits>()
+
+const cls = bem('image-cropper')
+
+const canvasRef = shallowRef<HTMLElement>()
+const selectionRef = shallowRef<HTMLElement>()
+const previewCanvasRef = shallowRef<HTMLCanvasElement>()
+
+const { imageUrl, loaded, naturalWidth, naturalHeight, imageEl } = useImageLoader({
+  src: () => props.src
+})
+
+const canvasSize = reactive({ width: 0, height: 0 })
+
+/** 宽高比预设，value 为 undefined 表示自由比例 */
+const RATIO_PRESETS: { label: string; value?: number }[] = [
+  { label: '自由', value: undefined },
+  { label: '1:1', value: 1 },
+  { label: '4:3', value: 4 / 3 },
+  { label: '16:9', value: 16 / 9 }
+]
+
+/** 当前生效的宽高比：工具栏预设可覆盖 prop，prop 变化时同步回来 */
+const currentRatio = shallowRef(props.aspectRatio)
+
+function setAspectRatio(ratio: number | undefined) {
+  currentRatio.value = ratio
+}
+
+const { transform, fit, reset, resetTransform, zoomIn, zoomOut, rotate, flip, toImageDelta } =
+  useTransform({
+    target: canvasRef,
+    canvasSize: () => canvasSize,
+    imageWidth: () => naturalWidth.value,
+    imageHeight: () => naturalHeight.value,
+    onReset: () => initSelection()
+  })
+
+const { selection, initSelection, clearSelection } = useSelection({
+  target: selectionRef,
+  imageWidth: () => naturalWidth.value,
+  imageHeight: () => naturalHeight.value,
+  toImageDelta,
+  aspectRatio: () => currentRatio.value
+})
+
+usePreview({
+  canvas: previewCanvasRef,
+  image: imageEl,
+  selection,
+  transform,
+  canvasSize: () => canvasSize
+})
+
+useResizeObserver({
+  targets: canvasRef,
+  onResize([entry]) {
+    if (!entry) return
+    canvasSize.width = entry.contentRect.width
+    canvasSize.height = entry.contentRect.height
+    if (loaded.value) fit()
+  }
+})
+
+watch(
+  () => props.src,
+  () => {
+    reset()
+    clearSelection()
+  }
+)
+
+watch(
+  () => props.aspectRatio,
+  (ratio) => {
+    currentRatio.value = ratio
+  }
+)
+
+watch(loaded, (isLoaded) => {
+  if (!isLoaded) return
+  fit()
+  initSelection()
+})
+
+// 选区或图片变换变化时发出裁剪变化事件，载荷为当前选区（图片像素坐标）与变换摘要
+watch([selection, () => ({ ...transform })], () => {
+  const sel = selection.value
+  if (!sel) return
+  emit('crop-change', {
+    selection: { ...sel },
+    transform: { rotation: transform.rotation, flipX: transform.flipX, flipY: transform.flipY }
+  })
+})
+
+/** 输出当前选区裁剪结果：默认原图选区像素，options 传入目标宽 / 高时按该尺寸缩放 */
+async function getResult(options?: ImageCropperResultOptions): Promise<ImageCropperResult> {
+  const img = imageEl.value
+  const sel = selection.value
+  if (!img || !sel) throw new Error('Export crop result failed: image not loaded or no selection')
+  return cropToResult(img, sel, transform, options)
+}
+
+defineExpose<_ImageCropperExposed>({ getResult })
+
+/** 舞台样式：图片与选区层共用同一变换，选区以图片像素坐标定位 */
+const stageStyle = computed(() => {
+  const { translateX, translateY, rotation, scale, flipX, flipY } = transform
+  return {
+    width: `${naturalWidth.value}px`,
+    height: `${naturalHeight.value}px`,
+    transform: `translate(${translateX}px, ${translateY}px) rotate(${rotation}deg) scale(${(flipX ? -1 : 1) * scale}, ${(flipY ? -1 : 1) * scale})`,
+    // 逆缩放系数：选区边框 / 网格线 / 手柄在缩放后保持屏幕恒定尺寸
+    '--u-image-cropper-inv-scale': String(1 / scale)
+  }
+})
+
+const selectionStyle = computed(() => {
+  const sel = selection.value
+  if (!sel) return {}
+  return {
+    left: `${sel.x}px`,
+    top: `${sel.y}px`,
+    width: `${sel.width}px`,
+    height: `${sel.height}px`
+  }
+})
+
+/** 选区外上 / 下 / 左 / 右四向遮罩 */
+const maskStyles = computed(() => {
+  const sel = selection.value
+  if (!sel) return []
+  const W = naturalWidth.value
+  const H = naturalHeight.value
+  const right = sel.x + sel.width
+  const bottom = sel.y + sel.height
+  return [
+    { left: '0px', top: '0px', width: `${W}px`, height: `${sel.y}px` },
+    { left: '0px', top: `${bottom}px`, width: `${W}px`, height: `${H - bottom}px` },
+    { left: '0px', top: `${sel.y}px`, width: `${sel.x}px`, height: `${sel.height}px` },
+    { left: `${right}px`, top: `${sel.y}px`, width: `${W - right}px`, height: `${sel.height}px` }
+  ]
+})
+</script>

package/src/components/image-cropper/index.ts

@@ -0,0 +1 @@
+export { default as UImageCropper } from './image-cropper.vue'