5-08 · Image 与图片预览：从懒加载占位到全屏 viewer 的完整链路

$ wc -l packages/components/image/src/* packages/components/image/__tests__/*.spec.ts \
        packages/theme/src/components/image.css tests/types/fixtures/image.ts
     312 image.vue
     808 image-viewer.vue
      65 image.ts
      18 image-viewer-types.ts
     639 image.spec.ts
     382 image.css
      75 image.ts（类型夹具）

export const XyImage = withInstall(Image, "xy-image");
export const XyImageViewer = withInstall(ImageViewer, "xy-image-viewer");
export default XyImage;

// packages/components/image/src/image.ts:1-65（全文）
import type Image from "./image.vue";

export const imageFits = ["fill", "contain", "cover", "none", "scale-down"] as const;
export const imageLoadingTypes = ["eager", "lazy"] as const;

export type ImageFit = (typeof imageFits)[number];
export type ImageLoading = (typeof imageLoadingTypes)[number];
export type ImageViewerAction =
  | "zoomIn"
  | "zoomOut"
  | "clockwise"
  | "anticlockwise"
  | "toggleMode";
export type ImageLoadHandler = (event: Event) => void;
export type ImageErrorHandler = (event: Event) => void;
export type ImageSwitchHandler = (index: number) => void;

export interface ImageViewerErrorSlotProps {
  activeIndex: number;
  src: string;
  retry: () => void;
}

export interface ImageViewerProgressSlotProps {
  activeIndex: number;
  total: number;
}

export interface ImageViewerToolbarSlotProps {
  actions: (action: ImageViewerAction) => void;
  prev: () => void;
  next: () => void;
  reset: () => void;
  activeIndex: number;
  setActiveItem: (index: number) => void;
}

export interface ImageProps {
  src?: string;
  alt?: string;
  fit?: ImageFit;
  loading?: ImageLoading;
  lazy?: boolean;
  scrollContainer?: string | HTMLElement;
  previewSrcList?: string[];
  previewTeleported?: boolean;
  zIndex?: number;
  initialIndex?: number;
  infinite?: boolean;
  hideOnClickModal?: boolean;
  closeOnPressEscape?: boolean;
  zoomRate?: number;
  scale?: number;
  minScale?: number;
  maxScale?: number;
  showProgress?: boolean;
  crossorigin?: "anonymous" | "use-credentials" | "";
}

export type ImageInstance = InstanceType<typeof Image>;

export type ImageViewerInstance = InstanceType<typeof import("./image-viewer.vue").default>;

export type { ImageViewerProps } from "./image-viewer-types";
export type { ImageCrossorigin } from "./image-viewer-types";

// packages/components/image/src/image-viewer-types.ts:1-18（全文）
export type ImageCrossorigin = "anonymous" | "use-credentials" | "";

export interface ImageViewerProps {
  modelValue?: boolean;
  urlList?: string[];
  initialIndex?: number;
  infinite?: boolean;
  hideOnClickModal?: boolean;
  teleported?: boolean;
  closeOnPressEscape?: boolean;
  zIndex?: number;
  zoomRate?: number;
  scale?: number;
  minScale?: number;
  maxScale?: number;
  showProgress?: boolean;
  crossorigin?: ImageCrossorigin;
}

const containerRef = ref<HTMLElement | null>(null);
const imageSrc = ref("");
const isLoading = ref(false);
const hasLoadError = ref(false);
const showViewer = ref(false);
const observer = ref<IntersectionObserver | null>(null);

const previewEnabled = computed(
  () => Array.isArray(props.previewSrcList) && props.previewSrcList.length > 0
);

const isManualLazy = computed(() => {
  if (props.loading === "eager") {
    return false;
  }

  return props.lazy;
});

// packages/components/image/src/image.vue:116-147
function resetState() {
  hasLoadError.value = false;
  isLoading.value = Boolean(props.src);
}

function resolveScrollRoot() {
  if (typeof window === "undefined") {
    return null;
  }

  const { scrollContainer } = props;

  if (typeof HTMLElement !== "undefined" && scrollContainer instanceof HTMLElement) {
    return scrollContainer;
  }

  if (typeof scrollContainer === "string" && scrollContainer) {
    return document.querySelector(scrollContainer);
  }

  return null;
}

function disconnectObserver() {
  observer.value?.disconnect();
  observer.value = null;
}

function loadImage() {
  resetState();
  imageSrc.value = props.src;
}

function handleLoad(event: Event) {
  isLoading.value = false;
  hasLoadError.value = false;
  emit("load", event);
}

function handleError(event: Event) {
  isLoading.value = false;
  hasLoadError.value = true;
  emit("error", event);
}

// packages/components/image/src/image.vue:161-198
function setupLazyObserver() {
  if (typeof window === "undefined") {
    loadImage();
    return;
  }

  disconnectObserver();
  resetState();
  imageSrc.value = "";

  if (!props.src) {
    isLoading.value = false;
    return;
  }

  if (!("IntersectionObserver" in window)) {
    loadImage();
    return;
  }

  observer.value = new IntersectionObserver(
    (entries) => {
      if (!entries.some((entry) => entry.isIntersecting)) {
        return;
      }

      loadImage();
      disconnectObserver();
    },
    {
      root: resolveScrollRoot()
    }
  );

  if (containerRef.value) {
    observer.value.observe(containerRef.value);
  }
}

if (isManualLazy.value) {
  resetState();
  imageSrc.value = "";

  if (containerRef.value) {
    setupLazyObserver();
  }

  return;
}

onMounted(() => {
  if (isManualLazy.value && !observer.value) {
    setupLazyObserver();
  }
});

onBeforeUnmount(() => {
  disconnectObserver();
});

<!-- packages/components/image/src/image.vue:255-312 -->
<template>
  <div ref="containerRef" v-bind="containerAttrs" :class="[ns.base.value, attrs.class]">
    <slot v-if="hasLoadError" name="error">
      <div class="xy-image__error">图片加载失败</div>
    </slot>
    <template v-else>
      <img
        v-if="imageSrc"
        v-bind="imgAttrs"
        :src="imageSrc"
        :alt="props.alt"
        :loading="props.loading"
        :class="imageClasses"
        :style="imageStyle"
        :crossorigin="props.crossorigin || undefined"
        @click="openPreview"
        @load="handleLoad"
        @error="handleError"
      />

      <div v-if="isLoading" class="xy-image__wrapper">
        <slot name="placeholder">
          <div class="xy-image__placeholder" />
        </slot>
      </div>
    </template>

    <ImageViewer
      v-if="previewEnabled"
      v-model="showViewer"
      :url-list="props.previewSrcList"
      :initial-index="props.initialIndex"
      :infinite="props.infinite"
      :hide-on-click-modal="props.hideOnClickModal"
      :teleported="props.previewTeleported"
      :close-on-press-escape="props.closeOnPressEscape"
      :zoom-rate="props.zoomRate"
      :scale="props.scale"
      :min-scale="props.minScale"
      :max-scale="props.maxScale"
      :z-index="props.zIndex"
      :show-progress="props.showProgress"
      :crossorigin="props.crossorigin"
      @close="closePreview"
      @switch="handleSwitch"
    >
      <template v-if="slots['viewer-error']" #viewer-error="slotProps">
        <slot name="viewer-error" v-bind="slotProps" />
      </template>
      <template v-if="slots.progress" #progress="slotProps">
        <slot name="progress" v-bind="slotProps" />
      </template>
      <template v-if="slots.toolbar" #toolbar="slotProps">
        <slot name="toolbar" v-bind="slotProps" />
      </template>
    </ImageViewer>
  </div>
</template>

<teleport to="body" :disabled="!props.teleported">

const activeIndex = ref(0);
const isDragging = ref(false);
const mode = ref<"contain" | "original">("contain");
const transform = ref({
  scale: props.scale,
  deg: 0,
  offsetX: 0,
  offsetY: 0
});

const imageStyle = computed(() => ({
  transform: `translate(${transform.value.offsetX}px, ${transform.value.offsetY}px) scale(${transform.value.scale}) rotate(${transform.value.deg}deg)`,
  maxWidth: mode.value === "contain" ? "100%" : "none",
  maxHeight: mode.value === "contain" ? "100%" : "none"
}));

// packages/components/image/src/image-viewer.vue:107-152
function clampScale(value: number) {
  return Math.min(props.maxScale, Math.max(props.minScale, value));
}

function clampOffsets(nextScale: number, nextOffsetX: number, nextOffsetY: number) {
  const canvas = canvasRef.value;
  const image = viewerImageRef.value;

  if (!canvas || !image) {
    return {
      offsetX: nextOffsetX,
      offsetY: nextOffsetY
    };
  }

  const canvasWidth = canvas.clientWidth;
  const canvasHeight = canvas.clientHeight;
  const imageWidth = image.offsetWidth;
  const imageHeight = image.offsetHeight;

  if (!canvasWidth || !canvasHeight || !imageWidth || !imageHeight) {
    return {
      offsetX: nextOffsetX,
      offsetY: nextOffsetY
    };
  }

  const maxOffsetX = Math.max((imageWidth * nextScale - canvasWidth) / 2, 0);
  const maxOffsetY = Math.max((imageHeight * nextScale - canvasHeight) / 2, 0);

  return {
    offsetX: Math.min(maxOffsetX, Math.max(-maxOffsetX, nextOffsetX)),
    offsetY: Math.min(maxOffsetY, Math.max(-maxOffsetY, nextOffsetY))
  };
}

function resetTransform() {
  stopInteraction();
  transform.value = {
    scale: clampScale(props.scale),
    deg: 0,
    offsetX: 0,
    offsetY: 0
  };
  mode.value = "contain";
}

maxOffset = (image × scale − canvas) / 2，下限 0
offset ∈ [−maxOffset, +maxOffset]

// packages/components/image/src/image-viewer.vue:464-492
  switch (action) {
    case "zoomIn":
      {
        const nextScale = clampScale(transform.value.scale * props.zoomRate);
        const nextOffsets = clampOffsets(
          nextScale,
          transform.value.offsetX,
          transform.value.offsetY
        );

        transform.value = {
          ...transform.value,
          scale: nextScale,
          offsetX: nextOffsets.offsetX,
          offsetY: nextOffsets.offsetY
        };
      }
      break;
    case "zoomOut":
      transform.value = {
        ...transform.value,
        ...clampOffsets(
          clampScale(transform.value.scale / props.zoomRate),
          transform.value.offsetX,
          transform.value.offsetY
        ),
        scale: clampScale(transform.value.scale / props.zoomRate)
      };
      break;

// packages/components/image/src/image-viewer.vue:357-407
function startPinchGesture(touches: TouchList) {
  stopInteraction();

  const initialDistance = getTouchDistance(touches);
  const initialCenter = getTouchCenter(touches);
  const initialScale = transform.value.scale;
  const initialOffsetX = transform.value.offsetX;
  const initialOffsetY = transform.value.offsetY;

  const handleTouchMove = (event: TouchEvent) => {
    if (event.touches.length < 2) {
      return;
    }

    event.preventDefault();

    const nextDistance = getTouchDistance(event.touches);
    const nextCenter = getTouchCenter(event.touches);
    const nextScale = clampScale(
      initialDistance > 0 ? (initialScale * nextDistance) / initialDistance : initialScale
    );
    const nextOffsets = clampOffsets(
      nextScale,
      initialOffsetX + nextCenter.x - initialCenter.x,
      initialOffsetY + nextCenter.y - initialCenter.y
    );

    transform.value = {
      ...transform.value,
      scale: nextScale,
      offsetX: nextOffsets.offsetX,
      offsetY: nextOffsets.offsetY
    };
  };

  const handleTouchEnd = () => {
    stopPinching();
  };

  document.addEventListener("touchmove", handleTouchMove, {
    passive: false
  });
  document.addEventListener("touchend", handleTouchEnd);
  document.addEventListener("touchcancel", handleTouchEnd);

  clearPinchListeners = () => {
    document.removeEventListener("touchmove", handleTouchMove);
    document.removeEventListener("touchend", handleTouchEnd);
    document.removeEventListener("touchcancel", handleTouchEnd);
  };
}

// packages/components/image/src/image-viewer.vue:435-457
function handleDoubleClick() {
  if (loading.value || loadError.value) {
    return;
  }

  const baseScale = clampScale(props.scale);

  if (
    transform.value.scale !== baseScale ||
    transform.value.deg !== 0 ||
    transform.value.offsetX !== 0 ||
    transform.value.offsetY !== 0 ||
    mode.value !== "contain"
  ) {
    resetTransform();
    return;
  }

  transform.value = {
    ...transform.value,
    scale: clampScale(Math.max(baseScale * props.zoomRate, 2))
  };
}

// packages/components/image/src/image-viewer.vue:262-325
function startDragging(startX: number, startY: number) {
  if (!isMovable.value) {
    return;
  }

  stopDragging();

  const initialOffsetX = transform.value.offsetX;
  const initialOffsetY = transform.value.offsetY;
  isDragging.value = true;

  const updateOffset = (pageX: number, pageY: number) => {
    const nextOffsets = clampOffsets(
      transform.value.scale,
      initialOffsetX + pageX - startX,
      initialOffsetY + pageY - startY
    );

    transform.value = {
      ...transform.value,
      offsetX: nextOffsets.offsetX,
      offsetY: nextOffsets.offsetY
    };
  };

  const handleMouseMove = (event: MouseEvent) => {
    updateOffset(event.clientX, event.clientY);
  };

  const handleMouseUp = () => {
    stopDragging();
  };

  const handleTouchMove = (event: TouchEvent) => {
    const touch = event.touches[0];

    if (!touch) {
      return;
    }

    event.preventDefault();
    updateOffset(touch.clientX, touch.clientY);
  };

  const handleTouchEnd = () => {
    stopDragging();
  };

  document.addEventListener("mousemove", handleMouseMove);
  document.addEventListener("mouseup", handleMouseUp);
  document.addEventListener("touchmove", handleTouchMove, {
    passive: false
  });
  document.addEventListener("touchend", handleTouchEnd);
  document.addEventListener("touchcancel", handleTouchEnd);

  clearDragListeners = () => {
    document.removeEventListener("mousemove", handleMouseMove);
    document.removeEventListener("mouseup", handleMouseUp);
    document.removeEventListener("touchmove", handleTouchMove);
    document.removeEventListener("touchend", handleTouchEnd);
    document.removeEventListener("touchcancel", handleTouchEnd);
  };
}

// packages/components/image/src/image-viewer.vue:524-568
function handleKeydown(event: KeyboardEvent) {
  if (!props.modelValue || !isTopMost()) {
    return;
  }

  switch (event.key) {
    case "Escape":
      if (props.closeOnPressEscape) {
        event.preventDefault();
        event.stopPropagation();
        closeViewer();
      }
      break;
    case "ArrowLeft":
      event.preventDefault();
      handlePrev();
      break;
    case "ArrowRight":
      event.preventDefault();
      handleNext();
      break;
    case "ArrowUp":
      event.preventDefault();
      handleActions("zoomIn");
      break;
    case "ArrowDown":
      event.preventDefault();
      handleActions("zoomOut");
      break;
    case " ":
    case "Spacebar":
      event.preventDefault();
      handleActions("toggleMode");
      break;
  }
}

function handleWheel(event: WheelEvent) {
  if (!props.modelValue || !isTopMost()) {
    return;
  }

  event.preventDefault();
  handleActions(event.deltaY < 0 ? "zoomIn" : "zoomOut");
}

// packages/components/image/src/image-viewer.vue:181-197
function openViewer() {
  activeIndex.value = normalizeIndex(props.initialIndex);
  imageRequestVersion.value += 1;
  loading.value = true;
  loadError.value = false;
  resetTransform();
  openLayer();
  lockBodyScroll();
}

function closeViewer() {
  stopInteraction();
  closeLayer();
  unlockBodyScroll();
  emit("update:modelValue", false);
  emit("close");
}

// packages/xiaoye-primitives/src/composables/use-overlay-stack.ts:37-73
function createOverlayEntry(): OverlayEntry {
  const id = Symbol("overlay");
  let opened = false;
  const disposed = false;

  const entry: OverlayEntry = {
    id,
    zIndex: ref(-1),
    isTopMost: () => {
      if (disposed || !opened) return false;
      const top = getTopEntry();
      return top?.id === id;
    },
    openLayer: () => {
      if (disposed) return;
      entry.zIndex.value = ++zIndexCounter.value;
      if (!opened) {
        stack.value.add(entry);
        opened = true;
      }
      notifyStackChange();
    },
    closeLayer: () => {
      if (disposed || !opened) return;
      opened = false;
      entry.zIndex.value = -1;
      if (stack.value.delete(entry)) {
        notifyStackChange();
      }
    }
  };

  return entry;
}

// packages/components/image/src/image-viewer.vue:607-617
const focusTrap = useFocusTrap(wrapperRef, {
  active: () => props.modelValue,
  autoFocus: "container",
  restoreFocus: true
});

onBeforeUnmount(() => {
  stopInteraction();
  unlockBodyScroll();
  closeLayer();
});

@keydown.capture="focusTrap.handleKeydown"
@keydown="handleKeydown"

if (value) {
  openViewer();
  await nextTick();
  if (viewerImageRef.value?.complete) {
    loading.value = false;
  }
  wrapperRef.value?.focus();
  return;
}

/* packages/theme/src/components/image.css:71-134 */
.xy-image-viewer {
  position: fixed;
  inset: 0;
}

.xy-image-viewer__mask {
  position: absolute;
  inset: 0;
  background: var(--xy-image-viewer-mask);
}

.xy-image-viewer__canvas {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 56px 88px 108px;
  box-sizing: border-box;
}

.xy-image-viewer__loading {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  color: var(--xy-bg-container);
  font-size: var(--xy-font-size-sm);
  background: color-mix(in srgb, var(--xy-overlay-color) 18%, transparent);
  pointer-events: none;
}

.xy-image-viewer__image,
.xy-image-viewer__error {
  max-width: 100%;
  max-height: 100%;
}

.xy-image-viewer__image {
  display: block;
  object-fit: contain;
  box-shadow:
    0 0 0 1px color-mix(in srgb, var(--xy-bg-floating) 18%, transparent),
    0 2px 8px color-mix(in srgb, var(--xy-text-heading) 6%, transparent);
  transform-origin: center center;
  transition:
    transform var(--xy-transition-duration-fast) var(--xy-transition-timing),
    opacity var(--xy-transition-duration-fast) var(--xy-transition-timing);
}

.xy-image-viewer__image.is-loading {
  opacity: 0;
}

.xy-image-viewer__image.is-draggable {
  cursor: grab;
  touch-action: none;
}

.xy-image-viewer__image.is-dragging {
  cursor: grabbing;
  transition: none;
}