SwGallery

SwGallery is a non-scrolling cover-card container that wraps into an equal-height grid, complementary to SwRail (horizontal scrolling row). It only owns layout and fetch pacing — all card visuals (cover / badge / rating / episode count) are rendered by the business via the #default scoped slot (usually with SwImage); movie / comic / novel covers are all the same to the component.

Column control (pick one)

Both are pure CSS (media query + CSS variables) — zero JS, SSR-safe. Passing columns overrides minItemWidth.

Load more (three-state loadMode, default button)

Append-mode data flow: on @load-more, append to items; an internal busy lock + the loading prop form a double lock against duplicate triggers (appending to items / finishing loading auto-unlocks, so failure cases can retry). Set finished when there is no more data (with total passed, remaining=0 is automatically treated as the end).

Failure & retry: when a request fails, the parent sets error: true and the load area becomes a "加载失败，点击重试" (load failed, tap to retry) button (clicking still emits @load-more; the parent clears error before retrying); in auto mode a failure removes the sentinel and switches to manual retry (preventing auto-retry loops) — once error is cleared and items are appended, auto loading resumes.

Standard Usage

<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="{ /* card tracking goes through SwLink; the grid has none built in */ }">
        <SwImage :src="item.img" :alt="item.name" ratio="2/3" />
        <p>{{ item.name }}</p>
      </SwLink>
    </template>
  </SwGallery>
</template>

Props

Events

Slots

Expose

CSS Variables

Caveats

• No built-in tracking: card impression / click go through SwLink :track inside the card; the grid itself reports nothing.
• Pager scenario: numbered paging is a replace-mode data flow — use loadMode="none" + SwPagination (framework#131); don't stuff page numbers into the Gallery.
• For component selection (horizontal scroll / carousel / video feed / grid) see the SwRail selection table.
• Pass :loading for retry-on-error too: both error and loading are parent-maintained; on failure, passing only :error without :loading keeps the internal load lock held and the retry click does nothing — pass :loading as well, and clear error back to false before firing the retry request.
• Pair @load-more with :finished or :total: with neither, "reached the end" is never detected — the button stays put (button mode) or the sentinel keeps re-firing empty pages (an infinite loop in auto mode). Set :finished="true" when there's no more data, or pass :total so the remaining count converges to zero.

See Also

• SwRail · SwImage · Tracking base