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 · 打点底座