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。