SwVideoFeed

SwVideoFeed 是抖音 / TikTok 式的直向短影片流元件：一屏一條、上下滑動逐條切換。行動端走瀏覽器原生直向 scroll-snap（手指滑動 + 慣性吸附原生白送，真機順滑）；桌面端用自訂滾輪 / 觸控板翻條（snappy 翻頁動畫）+ 鍵盤 ↑ / ↓ 翻條、Space 切目前條播放 / 暫停 + 可選 PC 上下箭頭。

內部是虛擬化 + 裸 hls 播放池：所有條目各渲一個全螢幕 slide 撐捲動高度，但只有視窗內（目前 ±windowSize）掛真實播放核，視窗外只顯封面 —— 長列表也不會爆記憶體。配合 @load-more 按需載入、finished 控邊界，做無限流。

業務 UI 不內建：按讚 / 作者 / 側欄圖示列 / 追蹤按鈕等業務疊層一律走 #overlay 插槽自渲，framework 只負責「捲動 + 播放 + 極簡控制」骨架。

靜音自動播放是預設：瀏覽器策略下「帶聲音的自動播放」需要使用者手勢。muted 預設 true（靜音播 + 靜音按鈕可解）；傳 muted="false" 是「嘗試進場帶聲」，詳見下方 進場帶聲音。

HLS 簽名過期恢復

hls.js 路徑下，分片或金鑰首次出現 403 / 無回應時，播放器重新載入同一播放位址，並從目前進度恢復；每次掛載最多重建一次；播放推進或超過 30 秒都不會恢復這個次數，後續 fatal 交由業務兜底。播放位址必須是可重新簽發的穩定入口，直接傳入已過期的 CDN 簽名位址無法靠重載續期。Feed 僅恢復原本正在播放且仍為 active 的項目，預載和暫停狀態不會自動起播。分片/金鑰逾時（包括 keyLoadTimeOut）、404 和 5xx 不觸發這條恢復，繼續交由 hls.js 處理；fatal 仍透過 error 通知業務。預載階段（或先前作為目前條時）遇到 fatal 的項目，在成為目前條時會依目前位址重建一次，線路短暫抖動可自癒；重建後仍失敗會再次觸發 error，之後不自動循環重試（滑走再滑回會再試一次）。

開發環境主控台的 HLS recovery 記錄本次錯誤類型、HTTP 狀態、重建前後進度及結果；進度超過恢復點才記錄 progress，不把清單載入成功當作續播成功。診斷不包含簽名 URL，也不上報正式環境後台。原生 HLS 不包含此恢復能力。

本集可取消歷史恢復

業務先校驗帳號、作品與集歸屬，再給影片條目傳 resume: { key, time }。key 標識本次觀看工作階段；僅目前活動條目顯示五秒實際播放倒數，可立即恢復或取消。暫停、手動 seek、換條或換源撤銷候選；背景、緩衝與廣告不消耗計時。預載條目不恢復，滑回已有工作階段位置及明確 seek_time（含 0）優先。

透過 resume-pending(index, item, pending) 按條目 ID 暫緩週期、暫停與離頁歷史寫入。私人歷史未讀完或讀取失敗時，業務也必須獨立阻止寫入；只有成功讀取才解除。框架不請求歷史、不跨集導覽，也不繞過系統自動播放限制。明確點擊繼續觀看時使用 seek_time，一般入口使用 resume。

基礎用法

items 傳短影片陣列，每條至少含封面 img + 播放線路 play_links。業務疊層放進 #overlay 插槽（接收 { item, index, active }）。元件預設佔滿全螢幕（100dvh），放進定高容器時用 CSS 變數 --sw-video-feed-height 改成 100%。

<SwVideoFeed :items="list">
  <template #overlay="{ item, index, active }">
    <div class="feed-overlay">
      <p class="author">@{{ item.meta?.author }}</p>
      <button class="like">♥ {{ item.meta?.likes }}</button>
    </div>
  </template>
</SwVideoFeed>

業務疊層（#overlay）

業務 UI（按讚 / 留言 / 分享圖示列 + 作者 / 描述）全部寫進 #overlay 插槽自渲，framework 不內建。插槽容器 pointer-events: none（影片區可點可滑），只給直接子元素兜底 pointer-events: auto 且零特異度，更深層靠繼承——所以在插槽內任意層級寫 pointer-events: none 都能生效並向下繼承（隱藏的操作列不會吃點擊），不必用 visibility: hidden 繞。

觸控端：互動控件與滑動的取捨

行動端 feed 走原生捲動，瀏覽器必須在 touchmove 當下判定「這是滑動還是點擊」， 一旦判成滑動就會取消該次 click，且無法反悔。所以在捲動容器裡，同一塊區域 「既能可靠點擊、又能從它起手滑動」二者不可兼得 —— 只能逐元素取捨。

不取捨的後果（真機實測）：直式單手拇指點右側收藏鈕時指尖天然帶弧形位移，超過瀏覽器的 touch slop 後一次誤觸同時吃掉兩件事 —— 收藏沒成功（click 被取消）+ 被動量吸到下一條。

framework 已替你做好預設取捨，applier 零改動：.slide 內的 button / a / [role="button"] 自動帶 touch-action: none，這些控件讓給點擊；影片體、封面、文案段落 以及各插槽的定位容器都不受影響，螢幕絕大部分照舊可以起手滑動。

const r = document.querySelector('.share-btn').getBoundingClientRect()
console.log(document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2))
// 命中自己 → 才是「滑動 vs 點擊」的判定問題；命中別的元素 → 是層疊遮擋，方向完全不同

副作用是按鈕 / 連結正上方不能起手滑動，這是上述硬約束的必然代價：那些位置本就是用來點的。 若某個連結面積很大（例如整塊「繼續觀看」卡片）又確實希望它可滑，把它改成 <div @click> 即可 （代價是失去連結語義與 SEO，自行權衡）。

⚠️ feed 內不支援巢狀橫向捲動

.feed-viewport 宣告了 touch-action: pan-y（fw#354）—— 目的是封死橫軸手勢面： overflow-y: auto 會讓另一軸的 visible 被規範強制計算成 auto，於是縱向流平白帶了一條橫軸捲動性， iPhone 真機上手指能橫向拉動整個 feed（elastic 回彈、畫面跟手；桌面重現不了）。

代價：touch-action 是祖先層級限制、後代無法恢復 —— 按規範手勢能力沿「觸點 → 實施捲動的容器」 這條鏈取交集，被祖先禁掉的手勢子元素寫不回來（在 #overlay 裡的元素上寫 touch-action: pan-x 無效）。 所以往 #overlay 裡放橫排推薦位 / 可橫滑標籤條這類東西會滑不動。

這是有意取捨：feed 語義就是整屏縱向流，橫滑內容與上面那條「整屏可點/可滑區互搶」本就衝突。 真有需求請提 framework issue 評估加 prop，別在 applier 側硬繞（繞不動）。

拖動進度條 seek 不受影響（fw#372 起兩態）—— 進度條展開態宣告 touch-action: none（按下即拖、 任意方向跟手）；收起態宣告 pan-y：縱向起手交給瀏覽器原生捲動 feed，橫向起手（約 10px 且橫向佔優） 進入拖動 —— 所以播放中也能直接在進度條上橫向起手拖動，不必先點一下畫面。

資料格式（VideoFeedItem）

items 是判別聯合：影片條（kind 省略或 'video'，複用播放器 PlayLink 線路）+ 廣告條（kind: 'ad'，全螢幕資訊流廣告，見下方資訊流廣告條）。

// 影片條（kind 省略即影片條，舊用法零改動）
interface VideoFeedVideoItem {
  kind?: 'video'
  img: string // 封面圖（cover 兜底，canplay 前 + 未進視窗的 slide 顯示）
  play_links: PlayLink[] // m3u8 多線路
  link_code?: string // 選哪條線路（對應 PlayLink.code，優先於元件級 linkCode）
  seek_time?: number // 起播位置（秒），loadedmetadata 後自動 seek。兩用：歷史進度續看 / 付費解鎖續播(resume_offset)
  resume?: { key: string | number; time: number } | null // Ownership-validated, cancellable history candidate
  locked?: boolean // 付費牆鎖定態（路徑 A）：true=付費內容且無權觀看；試看片段播完顯 #paywall（見下「付費牆」）
  id?: string | number // 業務標識（埋點 / v-for key）
  meta?: Record<string, unknown> // 透傳給 #overlay 的業務資料
}

// 廣告條（全螢幕資訊流廣告，創意走 #in-feed-ad slot）
interface VideoFeedAdItem {
  kind: 'ad'
  id?: string | number // 業務標識（埋點 / key）
  skipAfter?: number // 強制觀看時長（秒）；缺省回退 props.adSkipAfter（預設 0 = 不強制）
  meta?: Record<string, unknown> // 透傳給 #in-feed-ad slot 的廣告資料（圖 / 連結等）
}

type VideoFeedItem = VideoFeedVideoItem | VideoFeedAdItem

interface PlayLink {
  code: string // 線路標識
  id: number | string // 業務 id
  lid: number | string // 業務 lid
  m3u8_url: string // 實際播放位址（.m3u8 走 hls.js，其它走原生 <video>）
}

const list: VideoFeedItem[] = [
  {
    id: 1,
    img: 'https://cdn.example.com/cover1.jpg',
    play_links: [{ code: 'line1', id: 1, lid: 1, m3u8_url: 'https://cdn.example.com/1.m3u8' }],
    meta: { author: 'alice', likes: 1234 },
  },
  // 後端插入的廣告條（每 N 條一條）：全螢幕可滑、點擊開連結
  { kind: 'ad', id: 'ad-1', skipAfter: 4000, meta: { image: 'https://cdn.example.com/ad.jpg', link: '/promo' } },
]

按需載入（無限流）

目前條進入「剩餘不足 loadMoreThreshold 條」時觸發 @load-more，父層拉下一頁並追加到 items（不要整體替換，會丟已掛載播放核）。沒有更多時把 finished 置 true，元件不再觸發 @load-more；使用者滑到底再上滑會觸發一次 @reach-end。

<SwVideoFeed
  :items="list"
  :finished="finished"
  :load-more-threshold="5"
  @load-more="loadNext"
  @reach-end="onReachEnd"
>
  <template #overlay="{ item }">…</template>
</SwVideoFeed>

<script setup>
const list = ref([])
const finished = ref(false)
let loading = false
async function loadNext() {
  if (loading || finished.value) return
  loading = true
  const page = await api.fetchFeed(cursor)
  if (page.length === 0) finished.value = true
  else list.value.push(...page) // 追加，不替換
  loading = false
}
</script>

進場定位與虛擬化

• initialIndex 指定進場定位到第幾條（如從封面列表點進來的索引），預設 0（無動畫直接定位）。
• windowSize 是播放池半徑：預設 1（目前 ±1 = 3 條掛真實播放核），其餘只顯封面。
• 預載策略：預設預載後面 2 條影片各前 5 秒（起播存糧，變 active 後緩衝上限自動抬回 30s），覆蓋連滑兩次仍秒播；傳數字自定條數（如 :preload="3"），:preload="false" 完全關閉——滑到位後先封面兜底再載入，用秒播體感換 CDN 流量。廣告條（kind:'ad'，零影片流量）跳過且不佔預載名額，列表尾部不足時自然截斷；掛載視窗自動前伸覆蓋預載集。上一條不預載（剛劃過的舊當前條已載入，劃回仍即時）。注意秒數精控僅 hls.js 分支生效；iPhone 一律走原生 HLS（iOS 只有 ManagedMediaSource，而部分國產瀏覽器的 MMS 只推進時間軸、不渲染畫面 ⇒ 框架統一改走原生，fw#365），其緩衝由瀏覽器自決、盡力而為。
• ioThreshold 是 IntersectionObserver 判定「目前條」的可見比例閾值，預設 0.6。

<!-- 從第 3 條進場，前後各預掛 2 條 -->
<SwVideoFeed :items="list" :initial-index="3" :window-size="2" />

進場帶聲音（muted = false）

muted 預設 true（靜音自動播放，符合瀏覽器策略，永遠不會被攔）。傳 muted="false" 是嘗試「進場帶聲音播」：借使用者「點進 feed」那次手勢的 activation —— SPA 路由進入時首條通常可帶聲（PC / H5 通用）；若被瀏覽器攔截（如整頁重新整理無手勢），元件自動退回靜音並顯示靜音按鈕供使用者主動解除，不會黑屏。使用者一旦切換靜音態，會在整個 feed 持續生效（對目前條及之後所有條）。

<!-- 預設靜音播（最穩，行動端絕不被攔） -->
<SwVideoFeed :items="list" />

<!-- 嘗試進場帶聲（攔截則自動退回靜音） -->
<SwVideoFeed :items="list" :muted="false" />

桌面互動與靈敏度

• 滾輪 / 觸控板：累積 deltaY 翻條（一次手勢翻一條，帶冷卻防慣性多翻）。sensitivity.wheel 是靈敏度倍率（乘到累積量，預設 1，調大更靈敏）。
• 鍵盤（容器聚焦時）：↑ / ↓ 翻條，Space 切目前條播放 / 暫停。
• arrows（預設 true）：PC 上下箭頭，僅 hover 裝置顯示、端點禁用、行動端不顯。

<SwVideoFeed :items="list" :sensitivity="{ wheel: 1.5 }" :arrows="false" />

播完行為（endMode）

一條播完後做什麼，預設 'loop'（循環重播 —— 短影片主 feed 的性格）。

<!-- 劇集專輯 / 短劇合集：一集播完自動下一集 -->
<SwVideoFeed :items="episodes" end-mode="next" />

為什麼需要這個 prop 而不能自己接 ended：'loop' 檔下元件把 <video loop> 打開， 而 loop=true 的影片到末尾按 HTML 規範直接繞回、不派發 ended —— 業務側連事件都收不到。 endMode="next" 會同時關掉 loop 並接管推進。

極簡播放控制（抖音風）

每條播放核內建抖音式極簡控制（無需設定）：點擊畫面暫停 / 播放、點擊 / hover 喚出可拖動進度條（拖動時顯示目前 / 總時長）、播放中在進度條上橫向起手可直接拖動（無需先點畫面；縱向起手仍是切條，fw#372）、右下角靜音按鈕。位置 / 尺寸全部走 CSS 變數微調（見 CSS 變數）。

比例裁剪（fillThreshold）

影片與視口寬高比相似度 ≥ fillThreshold 時裁剪鋪滿（object-fit: cover，頂部對齊 + 水平置中）；預設 false（不裁，留黑邊 / contain）。

相似度 = min(影片比, 容器比) / max(影片比, 容器比)。建議取 0.8：

0.9 只能吃掉細黑邊，覆蓋不到主流高螢幕手機；0.8 讓規範直式素材在任何主流機型上滿螢幕（最多裁 20% 寬，與業界安全區量級一致），而真正比例不符的素材照樣安全留黑邊。

下方左右對比：測試流是橫屏 16:9，放進直盒預設留上下黑邊（contain）；開 fillThreshold 後接近比例的影片裁剪鋪滿。

<!-- 直屏短影片為主，接近直屏的裁滿鋪平 -->
<SwVideoFeed :items="list" :fill-threshold="0.8" />

資訊流廣告條（In-Feed Ad）

後端可把廣告資料插進 items 陣列（業界稱 In-Feed Ad，抖音 / TikTok 資訊流裡的全螢幕廣告）。元件按 kind 區分：kind: 'ad' 的條不掛播放核，改走 #in-feed-ad 作用域插槽由業務渲染圖片創意 + 點擊開連結 + 曝光埋點；它仍是普通 slide，可上下滑、@change 照常透傳。

#in-feed-ad 作用域 { item, index, active, countdown, canSkip }：

<SwVideoFeed :items="feed" :ad-skip-after="4000">
  <template #in-feed-ad="{ item, active, countdown, canSkip }">
    <!-- 廣告創意：圖片 + 連結 + 曝光埋點全由業務渲染 -->
    <SwAdNative :items="[toAdItem(item.meta)]" slot-key="feed_inline" />
    <!-- 強制觀看倒數提示 -->
    <span v-if="active && !canSkip" class="skip-hint">{{ countdown }}s 後可滑走</span>
  </template>
</SwVideoFeed>

強制觀看 N 秒（forced-view）：廣告條成為目前條後可鎖住「滑走」N 秒再放開（業界可跳過插播 / 插屏的「倒數後才能跳過」約定）。生效時長 = item.skipAfter ?? props.adSkipAfter，預設 0 = 不強制、自由滑走：

• >0 時：廣告條 active → 鎖滑走（桌面攔 next/prev/滾輪、行動端凍結原生捲動）+ 倒數；歸零解鎖、canSkip 轉 true。
• 逐條用 item.skipAfter 覆蓋、feed 級用 adSkipAfter 兜底。

埋點歸業務：feed 不替廣告條埋點，業務在 #in-feed-ad 裡用 SwAd*（自帶曝光 / 點擊）或 useAdTrack。feed 只管「時機 + 位置 + 強制觀看鎖」。

入口貼片廣告（preroll）

整個播放列表開始前展示一次的前貼片廣告（與單影片播放器的 SwVideoPlayer 前貼片 同款 API）。開關 prerollAd，貼片內容走 #preroll-ad 插槽，資料與 items 解耦（業務自備，不進列表）。

• 進場蓋住整 feed、壓住第一條正片（照常預 buffer、不播不出聲）；skip() 或倒數歸零進正片。
• 一次性：skip 後永不再現。預設不鎖捲動：貼片期上滑自動 skip() 進列表（不強制等廣告）。
• 強制觀看（opt-in）：開 prerollAdForceWatch 後，倒數期間鎖住翻條（滾輪 / 鍵盤 ↑↓ / 觸控 / 導航均不划走）、歸零自動解鎖（與資訊流廣告條 adSkipAfter 同口徑）；slot 據 canSkip 條件渲染 ✕ / 倒數。
• prerollAdAutoClose=true 時倒數歸零自動進正片；false 時歸零顯示預設「進入」按鈕（或業務 skip()）。

#preroll-ad 作用域 { countdown, skip, canSkip }（canSkip=當前能否跳過，強制觀看鎖期為 false，與 #in-feed-ad 同口徑）：

<!-- preroll-ad-force-watch：倒數期間鎖翻條（canSkip=false 期間別渲染 ✕）；
     preroll-ad-auto-close：歸零自動進正片（false 時歸零顯示「進入」按鈕） -->
<SwVideoFeed
  :items="videos"
  preroll-ad
  :preroll-ad-duration="5000"
  preroll-ad-force-watch
  :preroll-ad-auto-close="true"
>
  <template #preroll-ad="{ countdown, skip, canSkip }">
    <SwAdPreroll :items="playAdsToSwAdItems(feedPreroll)" slot-key="feed_preroll" @empty="skip()" />
  </template>
</SwVideoFeed>

週期性 popover 廣告（@change）

「每播 N 個彈一次 body 級彈窗廣告」不內建——元件只出 @change 翻條事件，業務計數自彈 SwAdPopup（內建會綁死頻率策略，違背「feed 不綁業務 UI」）。@change 透傳 item，業務可據 item.kind 把廣告條排除出計數：

<SwVideoFeed :items="feed" @change="onChange" />
<SwAdPopup ref="popRef" :items="popupAds" slot-key="feed_interval" />

<script setup>
const popRef = ref()
let played = 0
function onChange(_index, item) {
  if (item.kind === 'ad') return // 廣告條不計數
  if (++played % 5 === 0) popRef.value?.open() // 每播 5 個影片彈一次
}
</script>

付費牆（試看牆 paywall）

付費內容試看片段播完到點顯示購買門（變現，不是廣告，不進 SwAd* 家族）。機制走路徑 A：後端只下發試看片段（完整正片不下發到客戶端，從根上防扒源），片段播完自然 ended → 顯 #paywall 插槽。給影片條傳 locked: true（業務從後端付費欄位算，如 is_vip && !has_access，framework 不認欄位名）：

• 試看完顯牆：locked 條試看片段播完（播放核對 locked 條不循環、停末幀）→ 顯 #paywall 插槽 + 觸發 @paywall(index, item)（掛「牆曝光」轉換埋點）。
• 不鎖捲動、無關閉 X：付費牆是內容鎖定態、不是可關閉彈層 —— 可上滑 / skipToNext()（跳過此影片）走人；退出只有「解鎖 / 跳過」兩條路。
• 解鎖續播：購買成功後業務改本 item —— 換 play_links 為正片源 + 設 seek_time 為後端 resume_offset + 清 locked；元件自動換源並 seek 到續播點（複用 seek_time 起播）。framework 不提供 unlock()（拉正片源是業務的事）。

#paywall 作用域 { item, index, active, skipToNext }：

<SwVideoFeed :items="list" @paywall="onPaywallExposure">
  <template #paywall="{ item, skipToNext }">
    <div class="paywall">
      <p>試看已結束</p>
      <button @click="unlock(item)">開通會員解鎖</button>
      <button @click="skipToNext()">跳過此影片</button>
    </div>
  </template>
</SwVideoFeed>

<script setup>
async function unlock(item) {
  await purchase() // 業務支付
  const full = await fetchFullSource(item.id) // 拉正片 m3u8 + resume_offset
  item.play_links = full.play_links
  item.seek_time = full.resume_offset ?? 0 // 續播起點（缺省 0 從頭）
  item.locked = false // 清鎖 → 牆隱 + 自動換源續播
}
</script>

resume_offset 由後端給（試看=正片前 N 秒→N / 中段精彩片段→0 / 缺省→0 從頭）；前端不靠試看時長推算（試看未必是正片開頭）。付費 / 播放路徑頁面須 ssr: false（命中 ESLint no-isr-on-paid-paths）。

工作階段內續看（rememberProgress）

虛擬化會卸載滑出視窗的播放核、丟失播放進度。rememberProgress（預設 true）讓元件按播放 URL 記一份工作階段內進度：滑走某條 → 滑回 remount 時從原處續看（而非從頭）。

• 工作階段內（滑走 → 滑回，同一次瀏覽）：元件自動記 + 續，無需設定。此進度丟失是虛擬化卸載造成、由框架兜底。
• 跨工作階段歷史（明天再來）：元件不碰後端 —— 業務監聽 @timeupdate 節流上報後端、一般入口給 resume 候選，明確繼續才給 seek_time，並依 resume-pending 保護寫入。
• 與付費解鎖續播零衝突：工作階段進度按 URL 做 key，付費換源後新 URL 不在表 → 自動回退 item.seek_time(=resume_offset)。

<!-- 關閉工作階段續看（每條總從頭 / seek_time 起播） -->
<SwVideoFeed :items="list" :remember-progress="false" />

<!-- 跨工作階段歷史：業務監聽 timeupdate 自報後端 -->
<SwVideoFeed :items="list" @timeupdate="throttledReportProgress" />

下拉重新整理（pullToRefresh）

短影片 feed 站標配互動：首條 + 視口頂部時手指下拉超閾值、鬆手觸發 @refresh（pullToRefresh opt-in，預設關）。業務收到後拉新資料（通常重置 items 回第一頁——與 @load-more 的尾部追加對稱），並經受控 refreshing 收尾：置 true 保持指示器、拉完置 false 收起。

• 僅 touch：桌面滾輪 / 鍵盤不觸發（桌面重新整理有 F5 / 按鈕）。
• 不與內部機制打架：僅在「首條 + 頂部 + 非鎖定態（無 preroll 貼片 / 無廣告強制觀看）」才接管手勢，其餘場景完全放行原生捲動；指示器懸浮頂部、不位移內容。
• 指示器走 #refresh-indicator slot 自渲染（{ pulling, progress, refreshing }，按 progress 做跟手品牌動畫）；不提供時有極簡預設（箭頭拉滿翻轉 → 重新整理轉圈，尊重 prefers-reduced-motion）。

<SwVideoFeed :items="list" pull-to-refresh :refreshing="refreshing" @refresh="onRefresh">
  <template #refresh-indicator="{ progress, refreshing }">
    <BrandWave :progress="progress" :active="refreshing" />
  </template>
</SwVideoFeed>

const refreshing = ref(false)
async function onRefresh() {
  refreshing.value = true
  try {
    list.value = await api.feed({ page: 1 })
    page.value = 1
  } finally {
    refreshing.value = false
  }
}

載入與緩衝回饋

影片首屏等首幀和播放中途卡頓時都會顯示一個緩衝指示器 —— 元件內建、預設開啟，applier 零改動。

防閃爍：waiting 常常只持續幾十毫秒（seek、網路抖動），指示器延遲 300ms 才現身，短暫卡頓不會閃一下。這只影響 UI —— @waiting 事件是立即派發的，業務埋點的時間戳不受影響。

指示器不會動封面和畫面：中途卡頓時當前畫面原樣留著（只是疊一個轉圈），不會跳回封面圖。

自訂外觀

三檔，按需要選：

<SwVideoFeed :items="list">
  <!-- 自渲染：外層已經按緩衝態決定顯隱，這裡只管畫 -->
  <template #loading>
    <MyBrandSpinner />
  </template>
</SwVideoFeed>

<SwVideoFeed :items="list">
  <!-- 關掉：容器仍在但為空，不可見、也不攔手勢 -->
  <template #loading />
</SwVideoFeed>

CSS 變數

容器高度與極簡控制的位置 / 尺寸 / 配色都可透過 CSS 變數微調（寫在容器或父級）：

<!-- 嵌進定高容器 + 靜音按鈕上移 -->
<div style="height: 600px">
  <SwVideoFeed :items="list" style="--sw-video-feed-height: 100%; --sw-video-feed-mute-bottom: 4rem" />
</div>

命令式控制

透過樣板 ref 呼叫暴露方法：

<script setup>
const feedRef = ref()
</script>

<template>
  <SwVideoFeed ref="feedRef" :items="list" />
  <button @click="feedRef.next()">下一條</button>
  <button @click="feedRef.scrollToIndex(0)">回到第一條</button>
  <button @click="feedRef.setMuted(false)">取消靜音</button>
</template>

倍速與線路切換（設定選單場景）

feed 不內建設定選單 UI（抖音式 feed 無此形態是有意設計），但提供命令式 API + #overlay 作用域，業務可自渲染設定面板（如 PC 播放站從 artplayer 遷移時的倍速 / 線路能力平替）：

• setPlaybackRate(rate)：對目前條及後續條持續生效（翻條 remount 不丟）；rate 須為正數，非法值忽略。
• switchLine(code)：切換播放線路（play_links 裡的 code），重掛目前條並保留播放進度（進度遷移到新線路的會話進度表，remount 後續播）。
• #overlay 作用域透出 { playbackRate, lineCode }（響應式），設定面板據此顯示目前態。

<SwVideoFeed ref="feedRef" :items="list" link-code="line1">
  <template #overlay="{ playbackRate, lineCode }">
    <div class="settings">
      <button @click="feedRef.setPlaybackRate(playbackRate === 1 ? 2 : 1)">倍速 {{ playbackRate }}x</button>
      <button @click="feedRef.switchLine(lineCode === 'line1' ? 'line2' : 'line1')">線路 {{ lineCode }}</button>
    </div>
  </template>
</SwVideoFeed>

Props

播放行為埋點（:track.video）

feed 是多條流，track.video 傳映射函式 (item, index) => MediaTrackVideoSpec（回傳 undefined = 該條不上報）：

<SwVideoFeed
  :items="videos"
  :track="{ video: (item, i) => ({
    video_id: String(item.id), video_title: item.title ?? '',
    video_content_type: 'short_video',
    recommend_trace_id: item.trace_id ?? '',
  }) }"
/>

• 僅當前條計入埋點（窗口內鄰條的 play/pause 噪音自動過濾）；切條自動重置行為門閂。
• 行為詞表同 SwVideoPlayer 播放行為埋點；feed 預設 loop 循環播放，無自然 ended，完播由 play_progress_100 承擔。
• 逃生艙：新增原生透傳事件 @play(index, item) / @pause(index, item) / @timeupdate(index, currentTime, duration)，自有打點 SDK 直接消費。

Events

Slots

暴露方法（defineExpose）

控件配色 Token

播放控件（播放圖標 / 拖動時長 / 靜音鈕 / 進度條）配色經 --sw-video-feed-* token 覆蓋（fallback 即預設媒體語境黑白值）：

--sw-video-feed-play-icon-color(白 60%) · -seek-bg(黑 55%) · -seek-color(白) · -seek-total-color(白 65%) · -mute-bg(黑 40%) · -mute-color(白) · -progress-track(白 30%) · -progress-fill(白 85%) · -progress-fill-active(白) · -progress-handle(白)

注意事項

• #overlay 自渲業務 UI：按讚 / 作者 / 追蹤 / 側欄圖示列等都在 #overlay 裡寫，framework 不內建；插槽容器 pointer-events: none（影片區可點可滑），只給直接子元素兜底 pointer-events: auto 且零特異度，更深層靠繼承——所以在插槽內任意層級寫 pointer-events: none 都能生效並向下繼承（隱藏的操作列不會吃點擊），不必用 visibility: hidden 繞。
• @load-more 用追加不用替換：父層拿到新頁 items.value.push(...page)，整體替換會卸載已掛載的播放核、丟進度。
• 定高容器必設 --sw-video-feed-height：元件預設 100dvh 全螢幕；嵌進卡片 / 文件盒子時給容器固定高度 + 設 --sw-video-feed-height: 100%。
• 靜音自動播放是預設：行動端「帶聲自動播」永遠被瀏覽器攔，muted="false" 只在有進場手勢（SPA 導航）時可能帶聲，被攔自動退回靜音。
• 三端：行動 / 平板原生 scroll-snap（零設定）；桌面自訂滾輪 + 鍵盤 + 可選箭頭。