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>