admin/registry
Admin 元件

Image

圖片純展示。視覺態：loading／loaded／error。

安裝

Terminal
pnpm dlx shadcn-vue add @admin/image
import {  AdminImage,  AdminImageFallback,  AdminImageImg,  AdminImagePlaceholder,} from '@/components/admin/image'

用法

<script setup lang="ts">import {  AdminImage,  AdminImageFallback,  AdminImageImg,  AdminImagePlaceholder} from '@/components/admin/image'</script>​<template>  <admin-image class="aspect-video w-80 rounded-md">    <admin-image-img alt="風景照" src="https://picsum.photos/seed/admin-image/800/450" />    <admin-image-placeholder />    <admin-image-fallback />  </admin-image></template>

場景

自訂版面與裁切

<script setup lang="ts">import {  AdminImage,  AdminImageFallback,  AdminImageImg,  AdminImagePlaceholder} from '@/components/admin/image'​const SRC_LANDSCAPE = 'https://picsum.photos/seed/admin-image-landscape/800/450'const SRC_PORTRAIT = 'https://picsum.photos/seed/admin-image-portrait/600/800'const SRC_SQUARE = 'https://picsum.photos/seed/admin-image-square/600/600'</script>​<template>  <div class="flex flex-col gap-6">    <section class="flex flex-col gap-2">      <span class="typo-caption-small text-text-50">aspect：video / square / [4/3]</span>      <div class="grid grid-cols-3 gap-4">        <admin-image class="aspect-video rounded-md">          <admin-image-img alt="aspect-video" :src="SRC_LANDSCAPE" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>        <admin-image class="aspect-square rounded-md">          <admin-image-img alt="aspect-square" :src="SRC_SQUARE" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>        <admin-image class="aspect-4/3 rounded-md">          <admin-image-img alt="aspect-4/3" :src="SRC_LANDSCAPE" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>      </div>    </section>​    <section class="flex flex-col gap-2">      <span class="typo-caption-small text-text-50">object-fit：預設 cover / object-contain</span>      <div class="grid grid-cols-2 gap-4">        <admin-image class="aspect-video rounded-md bg-bg-80">          <admin-image-img alt="cover" :src="SRC_PORTRAIT" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>        <admin-image class="aspect-video rounded-md bg-bg-80">          <admin-image-img alt="contain" class="object-contain" :src="SRC_PORTRAIT" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>      </div>    </section>​    <section class="flex flex-col gap-2">      <span class="typo-caption-small text-text-50">rounded：rounded-md / rounded-full</span>      <div class="flex gap-4">        <admin-image class="aspect-square w-32 rounded-md">          <admin-image-img alt="rounded-md" :src="SRC_SQUARE" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>        <admin-image class="aspect-square w-32 rounded-full">          <admin-image-img alt="rounded-full" :src="SRC_SQUARE" />          <admin-image-placeholder />          <admin-image-fallback />        </admin-image>      </div>    </section>  </div></template>

錯誤態 fallback

故意傳入無效 src 觸發 error，顯示預設 fallback。

<script setup lang="ts">import {  AdminImage,  AdminImageFallback,  AdminImageImg,  AdminImagePlaceholder} from '@/components/admin/image'</script>​<template>  <admin-image class="aspect-video w-80 rounded-md">    <admin-image-img alt="無法載入的圖片" src="/_does-not-exist.png" />    <admin-image-placeholder />    <admin-image-fallback />  </admin-image></template>

自訂 placeholder 與 fallback

子元件渲染條件

admin-image-placeholder 僅在 loading 狀態渲染，admin-image-fallback 僅在 error 狀態渲染；不放對應子元件即無該狀態的視覺。

<script setup lang="ts">import { IconAlertTriangle, IconRefresh } from '@tabler/icons-vue'import { computed, ref } from 'vue'import { AdminButton } from '@/components/admin/button'import {  AdminImage,  AdminImageFallback,  AdminImageImg,  AdminImagePlaceholder} from '@/components/admin/image'import { AdminLoading } from '@/components/admin/loading'​const reloadKey = ref(0)const customSrc = computed(  () => `https://picsum.photos/seed/admin-image-custom-${reloadKey.value}/800/450`)</script>​<template>  <div class="flex flex-col gap-3">    <div>      <admin-button size="small" variant="outline" @click="reloadKey++">        <icon-refresh class="size-4" />        重新載入      </admin-button>    </div>​    <div class="flex gap-4">      <admin-image class="aspect-video w-80 rounded-md">        <admin-image-img alt="客製 placeholder" :src="customSrc" />        <admin-image-placeholder>          <admin-loading mode="inline" />        </admin-image-placeholder>        <admin-image-fallback />      </admin-image>​      <admin-image class="aspect-video w-80 rounded-md">        <admin-image-img alt="客製 fallback" src="/_does-not-exist.png" />        <admin-image-placeholder />        <admin-image-fallback class="flex flex-col gap-2 bg-primary-10 text-error-40">          <icon-alert-triangle class="size-6" />          <span class="typo-caption-small">圖片暫時無法顯示</span>        </admin-image-fallback>      </admin-image>    </div>  </div></template>

API 參考

組成

<template>  <admin-image>    <admin-image-img alt="..." src="..." />    <admin-image-placeholder />    <admin-image-fallback />  </admin-image></template>

admin-image

Props

名稱型別預設值說明
classClassValue—根元素之自訂 class

Slots

名稱Bindings說明
default{}—

admin-image-img

Props

名稱型別預設值說明
src*string—圖片 URL（必填）
alt*string—圖片替代文字（必填）
loading"eager" | "lazy" | undefined—原生 `<img>` 之 `loading` 屬性
decoding"auto" | "async" | "sync" | undefined—原生 `<img>` 之 `decoding` 屬性
srcsetstring | undefined—響應式圖片之 `srcset` 候選清單
sizesstring | undefined—響應式圖片之 `sizes` 描述
referrerpolicyHTMLAttributeReferrerPolicy | undefined—原生 `<img>` 之 `referrerpolicy` 屬性
crossorigin"" | "anonymous" | "use-credentials" | undefined—原生 `<img>` 之 `crossorigin` 屬性
classClassValue—根元素之自訂 class

* 代表必填

Events

名稱Payload說明
errorEvent圖片載入失敗時觸發
loadEvent圖片載入成功時觸發

admin-image-placeholder

Props

名稱型別預設值說明
classClassValue—根元素之自訂 class

Slots

名稱Bindings說明
default{}—

admin-image-fallback

Props

名稱型別預設值說明
classClassValue—根元素之自訂 class

Slots

名稱Bindings說明
default{}—

注意事項

  • CDN 同 URL 不同檔：若 src 字串完全相同但內容換了（CDN 快取），<img> 不會自動重抓。父層應在 URL 後加 query string 強制更新。
  • 純展示用 admin-image；頭像場景改用 admin-avatar；表單上傳改用 admin-image-upload。

更新紀錄

此元件尚無更新紀錄。

File Upload

多檔上傳。拖曳、驗證、File 與 URL 並存；上傳由父層監聽 upload 事件處理。

Image Upload

單張圖片上傳。