SwAdPopup

廣告位四要素
使用場景：業務行為觸發的全螢幕彈窗——點按鈕 / 退出挽留 / 短影片流每滑 N 條彈一次（SwVideoFeed @change 計數 → popupRef.open()）；slotKey 例 feed_popup
業界形態：Interstitial / Vignette（AdSDK 格式 popup）
表現形態：全螢幕遮罩 + 單圖逐個彈（sequential）或故事流輪播（carousel）+ 倒數可關
打點事件：adImpression（彈層展示即報，ad_type=popup）/ adClick；自動內建零組態，gate 關閉靜默 no-op
⚠️ 進站自動彈的開屏用 SwAdSplash，不是本元件（trigger=onload 模式已移除）。選錯場景 = 埋點 ad_type / 時機全錯，見廣告元件選型。

SwAdPopup 是業務觸發的全螢幕彈窗廣告位元件——業務拿 ref 呼叫 open() / close()，元件不自動彈。與 SwAdSplash（進站自動彈）共享同一彈窗核心，區別只在觸發方式（手動 vs 進站自動）+ frequency 預設值（0 vs session）+ ad_type（popup vs splash）。多創意支援順序展示或故事流輪播。內建曝光 / 點擊埋點。

文案 + CTA overlay（opt-in）：item 帶 title / description / cta / advertiser 任一時，自動在創意圖上疊加「標題 + 副文案 + CTA 按鈕」浮層（像真廣告）；只給 image 則保持純圖、不變。CTA 是按鈕樣的 <span>（整張廣告已是連結，點擊落 link）。

加载中...

Props

名稱	類型	必填	預設值	說明
`items`	`SwAdItem[]`	✓	—	廣告創意陣列
`slotKey`	`string`	✓	—	廣告位鍵 → `ad_slot_key`
`slotName`	`string`		`undefined`	廣告位名 → `ad_slot_name`
`pageKey`	`string`		`undefined`	頁面鍵 → `page_key`
`pageName`	`string`		`undefined`	頁面名 → `page_name`
`ratio`	`string`		`'3/4'`	彈窗創意寬高比
`overlay`	`boolean`		`true`	是否顯示遮罩
`mode`	`'sequential' \| 'carousel'`		`'sequential'`	多創意：順序逐個 / 故事流輪播
`frequency`	`AdFrequencyStrategy`		`'always'`	頻控策略，預設 `'always'` 不限頻（業務自己 gate `open()` 時機）；想疊 cap 傳 `'session'` / `'7d'` 這類
`frequencyKey`	`string`		`undefined`	頻控儲存鍵（預設用 `slotKey`）
`showAdLabel`	`boolean`		`undefined`	「廣告」合規角標；不傳時跟隨全域 `swiftConfig.ad.showLabel`（預設 `true`），顯式傳值始終優先
`autoplayDelay`	`number`		`3000`	`carousel` 模式輪播間隔（ms）
`closableAfter`	`number`		`0`	倒數 N 毫秒後才可關閉（防誤關，0 = 立即可關）
`loop`	`boolean`		`true`	`carousel` 模式是否循環

Events

名稱	攜帶	說明
`open`	—	彈窗打開
`close`	—	彈窗關閉
`empty`	—	`items` 為空（不彈）
`impression`	`items: SwAdItem[]`	曝光（自動埋點）
`click`	`item: SwAdItem`	點擊創意（自動埋點）
`error`	—	渲染 / 載入錯誤

暴露方法（`ref`）

方法	說明
`open()`	打開彈窗（業務在觸發時機呼叫；若傳了 `frequency` 且未命中則靜默不彈）
`close()`	關閉彈窗

故事流輪播 + 可選頻控

mode="carousel" 多創意故事流輪播，配 closableAfter 倒數、autoplayDelay 切換間隔。frequency 預設 'always' 不限頻（每次 open() 都彈）；業務想疊 cap（如 feed「每滑 N 條但每會話最多一輪」）傳 frequency="session"：

加载中...

<!-- 手動觸發 -->
<SwAdPopup ref="popupRef" :items="ads" slot-key="promo" />
<SwButton @click="popupRef?.open()">查看活動</SwButton>

<!-- 短影片流每滑 5 條彈一次、每會話最多一輪 -->
<SwAdPopup ref="feedPopup" :items="ads" slot-key="feed_popup" frequency="session" />
<!-- SwVideoFeed @change: if (++count % 5 === 0) feedPopup.value?.open() -->

<!-- 非模態（overlay=false 不鎖背景）+ 輪播到最後一張停住（loop=false）+
     frequency-key 顯式頻控鍵：預設取 slot-key，發版換 key 可重置老用戶頻控 -->
<SwAdPopup :items="ads" slot-key="promo" mode="carousel" :overlay="false" :loop="false" frequency-key="promo-2026q3" />

樣式訂製 Token

彈層核心 AdPopupBase 的旋鈕（SwAdSplash 與本元件共用同一套，fallback 即預設值）：

變數	預設值	說明
`--sw-ad-popup-overlay-bg`	`rgb(0 0 0 / 60%)`	彈層遮罩底色
`--sw-ad-popup-topbar-gradient`	`linear-gradient(180deg, rgb(0 0 0 / 50%) 0%, rgb(0 0 0 / 0%) 100%)`	頂欄漸層遮罩（承托關閉鈕 / 序號）
`--sw-ad-popup-seq-color`	`rgb(255 255 255 / 90%)`	輪播序號文字色
`--sw-ad-popup-seq-border`	`rgb(255 255 255 / 60%)`	輪播序號描邊色
`--sw-ad-popup-bar-track`	`rgb(255 255 255 / 25%)`	進度條軌道色
`--sw-ad-popup-bar-fill`	`var(--primary)`	進度條已播段顏色
`--sw-ad-popup-nav-bg`	`rgb(0 0 0 / 35%)`	左右翻頁鈕底色
`--sw-ad-popup-nav-color`	`rgb(255 255 255)`	左右翻頁鈕圖示色
`--sw-ad-popup-pill-bg`	`rgb(255 255 255 / 12%)`	膠囊按鈕底色（如「跳過」）
`--sw-ad-popup-pill-bg-hover`	`rgb(255 255 255 / 22%)`	膠囊按鈕 hover 底色
`--sw-ad-popup-pill-color`	`rgb(255 255 255)`	膠囊按鈕文字色

創意上的標題 / 描述 / CTA 浮層由內部 AdOverlay 算繪，旋鈕是 --sw-ad-overlay-*（三個廣告元件共用），清單見 SwAdPreroll · 創意浮層 Token。

注意事項

觸發時機業務自管 —— 元件不自動彈，業務拿 ref 在合適時機呼叫 open()（點擊 / 退出意圖 / feed 滑動計數等）。
frequency 預設 'always' 不限頻；傳 'session' / N 天可疊加頻控 cap（useAdFrequency，未命中時 open() 靜默不彈）。
closableAfter > 0 時倒數內禁止關閉（防誤觸），到點出現關閉按鈕。
埋點內建（ad_type=popup），受 tracker 雙重 gate。