SwTable

SwTable 是管理台資料表格：columns 配置驅動表頭與列序，儲存格預設渲染 item[key]，複雜內容（縮圖 / 狀態徽章 / 操作按鈕組）走 #cell-<key> 作用域插槽由業務自渲染；內建管理台高頻三大件——受控列排序（v-model:sort）、行選擇批量（v-model:selected）、loading 過渡，以及斑馬紋 / 密度 / 黏性表頭視覺旋鈕。視覺對齊 shadcn Table 基調。

語義 <table> 直出（SEO / a11y），根包一層 .sw-table 容器做 overflow-x: auto——窄螢幕時表格自身橫向滾動、不撐爆頁面。基線樣式（邊框 + 圓角 / 表頭弱化底 / 行 hover / 儲存格 padding）走 --sw-table-* token，applier 覆蓋變數即換膚。

邊界：分頁 / 篩選不內建——用 SwPagination / SwSegmented / SwSelect 頁面層組合；排序只管互動不排資料（受控，見下）；固定列 / 列寬拖曳 / 樹形 / 虛擬滾動等重功能等真實資料點再議。這對齊 framework「只管佈局不綁業務 UI」鐵律。

基礎用法

<script setup lang="ts">
const COLUMNS = [
  { key: 'name', label: '名称' },
  { key: 'category', label: '分类' },
  { key: 'count', label: '集数', width: '4rem', align: 'center' },
]
const rows = [{ id: 1, name: '未来都市', category: '动画', count: 12 }]
</script>

<template>
  <SwTable :columns="COLUMNS" :items="rows" />
</template>

儲存格 / 表頭插槽（營運台列表形態）

#cell-<key> 按列自訂儲存格（作用域 { item, value, index }），#header-<key> 自訂表頭（作用域 { column }）：

空態佔位

#empty 在 items 為空時渲染為一行整寬佔位；不傳則空 tbody：

列排序（受控）

column.sortable 讓列頭可點，三態循環 asc → desc → 無 並經 v-model:sort 受控回顯（表頭渲染指示箭頭 + aria-sort）。元件不排資料——業務拿到排序態後本地排（toSorted）或帶參調後端（管理台主流是伺服端排序）：

<script setup lang="ts">
const sort = ref<SwTableSort | undefined>()
// 伺服端排序：排序態變化即帶參重新拉資料
watch(sort, (s) => refetch({ orderBy: s?.key, order: s?.order }))
</script>

<template>
  <SwTable v-model:sort="sort" :columns="COLUMNS" :items="rows" />
</template>

行選擇與批量操作

selectable 渲染 checkbox 選擇列 + 表頭全選（部分選中時半選 indeterminate），選中集合走 v-model:selected（rowKey 值陣列）：

loading 過渡態

loading 讓表格半透明 + 遮罩轉圈，保留結構不閃白——服務「已有資料、翻頁 / 篩選刷新中」的過渡；首屏無資料的 loading 仍歸頁面層四態（骨架屏），兩者互補：

視覺旋鈕：斑馬紋與密度

striped 偶數行弱化底、size="compact" 收緊儲存格 padding，資料密集頁常用組合：

黏性表頭（長列表容器內滾動）

sticky-header + --sw-table-max-height 讓容器變滾動區、表頭釘在頂部：

管理台綜合形態

排序 + 行選批量 + loading + 行點擊 + 狀態徽章 + 行內操作的完整組合（真實營運台列表頁形態）：

與分頁組合（頁面層資料流）

表格不管分頁——頁碼翻頁用 SwPagination 受控替換 items：

<template>
  <SwTable :columns="COLUMNS" :items="pageItems">
    <template #empty>暂无数据</template>
  </SwTable>
  <SwPagination v-model:page="page" :total="total" :page-size="20" />
</template>

Props

SwTableColumn：{ key: string; label?: string; width?: string; align?: 'left' \| 'center' \| 'right'; sortable?: boolean }——key 既是預設儲存格取值欄位，也是 #cell-<key> / #header-<key> 插槽名後綴；width 落到 <th>（CSS 寬度值）；align 預設 'left'；sortable 讓列頭可點排序。

SwTableSort：{ key: string; order: 'asc' \| 'desc' }。兩個型別均可從套件名匯入：import type { SwTableColumn, SwTableSort } from '@swift-web/framework'。

Events

行內操作（編輯 / 上下架 / 刪除）仍在 #cell-<key> 插槽內用 SwButton 等自帶事件。

Slots

樣式定制 Token

表格皮膚經 --sw-table-* token 覆蓋（fallback 即預設視覺）：

注意事項

• 可排序表頭是真 <button>：sortable 列的表頭內容被包進 <button>（W3C ARIA APG 的 Sortable Table 範式），鍵盤可 Tab 聚焦、Enter / Space 排序，aria-sort 仍在 <th> 上。想改 hover 視覺請選 button.th-inner:hover。
• row-click 是便捷層，不是唯一通路：行本身刻意不做成可聚焦元素（長表會憑空多出等量 Tab 停靠點）。行內必須有承擔同一動作的真實可聚焦元素（詳情連結 / 操作按鈕），否則鍵盤與螢幕閱讀器使用者根本觸達不了該動作——那是 WCAG 2.1.1 Keyboard（Level A）不達標，且滑鼠測試永遠看不出來。dev 期會 console.warn 提示，生產建置整段被移除。
• 排序不排資料：v-model:sort 只是受控互動態——業務必須自己排（本地 toSorted 或帶參調後端），否則點了列頭「只有箭頭變、資料不動」。
• loading 與四態的分工：loading 服務「已有資料刷新中」的過渡；首屏無資料的 loading / error / empty 仍歸頁面層四態（骨架屏 / 重試入口），#empty 僅是空資料行的輕量兜底。
• 行內操作不觸發 row-click：#cell-* 內的 button / a / input 點擊不會冒泡成行點擊，無需手動 stopPropagation。
• 不內建分頁 / 篩選：用 SwPagination / SwSegmented / SwSelect 頁面層組合。
• 行內非同步操作記得鎖 pending：#cell-* 裡的操作按鈕遵守 SB-001（async @click 配 :loading），如上下架按行 id 鎖。
• 窄螢幕橫向滾動是內建行為：.sw-table 容器自帶 overflow-x: auto，列多時給列設 width 保證可讀寬度即可，別在外層再包滾動容器。

相關

• SwPagination · SwSegmented · SwSelect · SwGallery