SwGallery

SwGallery 是不滾動、換行鋪成等高網格的封面卡容器，與 SwRail（橫滾橫排）互補。它只管佈局與取數節奏——卡片一切視覺（封面 / 角標 / 評分 / 集數）由 #default 作用域插槽業務渲染（通常放 SwImage），影 / 漫 / 小說封面對元件無差別。

列數控制（二選一）

兩者純 CSS 實作（media query + CSS 變數），零 JS、SSR 安全。columns 傳了即覆蓋 minItemWidth。

載入更多（loadMode 三態，預設 button）

追加式資料流：收到 @load-more 後往 items 追加；內部 busy 鎖 + loading prop 雙鎖防重複觸發（items 追加 / loading 收尾自動解鎖，失敗場景可重試）。無更多資料時置 finished（傳了 total 時 remaining=0 自動視為到底）。

失敗重試：請求失敗時父層置 error: true，載入區變「加载失败，点击重试」按鈕（點擊照常 emit @load-more，父層重試發請求前清 error）；auto 模式失敗時哨兵移除、轉手動重試（防失敗自動循環），error 清掉並追加後自動恢復。

標準用法

<script setup lang="ts">
const items = ref<Movie[]>([])
const total = ref(0)
const loading = ref(false)

async function loadMore() {
  loading.value = true
  try {
    const r = await request<MovieList>('/movie/list', { body: { offset: items.value.length } })
    items.value = [...items.value, ...r.list]
    total.value = +r.total
  } finally {
    loading.value = false
  }
}
await loadMore()
</script>

<template>
  <SwGallery :items="items" :total="total" :loading="loading" :min-item-width="180" @load-more="loadMore">
    <template #default="{ item }">
      <SwLink :to="`/movie/${item.id}`" :track="{ /* 卡片埋點走 SwLink，網格不內建 */ }">
        <SwImage :src="item.img" :alt="item.name" ratio="2/3" />
        <p>{{ item.name }}</p>
      </SwLink>
    </template>
  </SwGallery>
</template>

Props

Events

Slots

Expose

CSS 變數

注意事項

• 埋點不內建：卡片曝光 / 點擊走卡片內 SwLink :track；網格本身零上報。
• 翻頁器場景：頁碼翻頁是替換式資料流，用 loadMode="none" + SwPagination 組合（framework#131），不要把頁碼塞進 Gallery。
• 選型對照（橫滾 / 輪播 / 影片流 / 網格）見 SwRail 選型表。
• 失敗重試要同時傳 :loading：error / loading 都由父層維護；失敗時只傳 :error 不傳 :loading，內部載入鎖不釋放、重試點擊無效——請同時傳 :loading，並在重試發請求前把 error 清回 false。
• @load-more 要配 :finished 或 :total：兩者都不傳則永遠判不到「到底」，button 模式按鈕常駐、auto 模式哨兵反覆觸發拉空頁（死循環）。無更多資料時置 :finished="true"，或傳 :total 讓剩餘歸零自動收斂。

相關

• SwRail · SwImage · 打點底座