SwImage

<!-- 本地图片：自动使用预生成的 avif/webp srcset -->
<SwImage src="/images/cover.jpg" alt="封面" ratio="16/9" />

<!-- SVG：直接输出，不走优化 -->
<SwImage src="/images/logo.svg" alt="Logo" fit="contain" />

<!-- 外部图片：无 srcset，直接 img -->
<SwImage src="https://picsum.photos/400/300" alt="示例" ratio="4/3" />

<!-- 外部图片单图覆盖 provider 路由：已签名 URL 强制 'noop' 原样直出（不走 CDN 处理） -->
<SwImage :src="signedUrl" alt="示例" ratio="4/3" provider="noop" />

<!-- ✅ 定宽 class 直接挂 SwImage 即可；在 flex 行里记得 flex-shrink: 0 -->
<SwImage class="avatar" src="/a.jpg" alt="" ratio="1/1" />
<style>.avatar { width: 3rem; flex-shrink: 0; }</style>

<!-- ❌ 想铺满定高父容器，:deep 穿透给容器打绝对定位——脆弱且 fill 已内置此能力 -->
<style>.hero :deep(.sw-image) { position: absolute; inset: 0; }</style>

<!-- ✅ 父容器定位/定高，SwImage 传 fill -->
<div class="hero"><SwImage src="/h.jpg" alt="" fit="cover" fill /></div>
<style>.hero { position: relative; height: 24rem; }</style>

<!-- 首屏 Hero 大图（LCP 三件套）：eager 立即加载 + preload 注入 <link rel="preload">
     + fetchpriority 网络优先级拉满（加密 .bnc 图不支持 preload，见注意事项） -->
<SwImage src="/images/hero.jpg" alt="首页主图" ratio="21/9" loading="eager" preload fetchpriority="high" :placeholder="false" />

<!-- 头像圆图：contain 完整显示，1:1 比例 -->
<SwImage src="/images/avatar.png" alt="用户头像" ratio="1/1" fit="contain" />

<!-- 封面模糊底图：blur 高斯模糊（详情页背景常用 pattern） -->
<SwImage src="/images/cover.jpg" alt="" :blur="12" ratio="16/9" />

<!-- 带占位图：加载中显示品牌 logo -->
<SwImage src="/images/product.jpg" alt="商品图" ratio="1/1" placeholder="/images/logo.svg" />

<!-- 监听加载事件 -->
<SwImage src="/images/cover.jpg" alt="封面" @load="onLoad" @error="onError" />

<SwImage
  src="/images/cover.jpg"
  alt="影片封面"
  ratio="3/4"
  class="hover-zoom"
  @click="goDetail"
>
  <div class="overlay">
    <span class="play-icon">▶</span>
    <span class="title">{{ item.title }}</span>
  </div>
</SwImage>

:root {
  --sw-image-hover-zoom-scale: 1.05; /* 收敛一点 */
  --sw-image-hover-zoom-duration: 0.6s; /* 慢一点 */
}

::alert{type="info"}
**`prefers-reduced-motion: reduce` 下自动不放大**，组件已内置兜底，业务无需自己补。缩放属「非必要动效」，对前庭功能障碍用户会引发眩晕（standards UX-004 / WCAG 2.3.3）。

另外，放大**只作用于真实图**：占位图不参与缩放（占位期 hover 放大占位 logo 没有意义）。插槽内的业务图也不受影响 —— 那部分动效由业务自己决定。
::
vue
<!-- placeholder-class：给占位 div 附加自定义类（如骨架屏脉冲动画） -->
<SwImage
  src="/images/cover.jpg"
  alt="..."
  placeholder-class="skeleton-pulse"
  :placeholder="{
    dark: '/images/placeholder-dark.png',
    light: '/images/placeholder-light.png',
  }"
/>

<SwImage src="/images/cover.jpg" alt="...">
  <template #placeholder>
    <div class="my-skeleton" />
  </template>
</SwImage>

<script setup lang="ts">
const imgRef = ref()

function measure() {
  const el = imgRef.value?.getElement()
  if (el) console.log(el.naturalWidth, el.naturalHeight) // 原图真实尺寸
}
</script>

<template>
  <SwImage ref="imgRef" src="/images/cover.jpg" alt="封面" @load="measure" />
</template>

<!-- 自定义 loading / error 占位底色 -->
<style>
.sw-image .placeholder { --sw-image-placeholder-bg: #16110f; }
.sw-image .placeholder.is-error { --sw-image-placeholder-error-bg: #3c0001; }
</style>