SwAdPause

广告位四要素
使用场景：视频暂停时弹出的可关闭广告（CTV / 流媒体黄金广告位——用户主动停下、注意力在屏幕）。渲染进 SwVideoPlayer 的 #pause-ad 插槽，slotKey 例 play_pause
业界形态：Pause Ad / Pause Screen Ad（AdSDK 格式 pause）
表现形态：居中 / 角落卡片 + 可关闭 ✕；不全屏死挡——暂停画面仍部分可见，点卡片外画面恢复播放即关
打点事件：adImpression（展示即报）/ adClick / 关闭；自动内置零配置，gate 关闭静默 no-op
选错场景 = 埋点 ad_type / 时机全错。按场景选组件见广告组件选型。

SwAdPause 是暂停广告位组件，属广告底座「播放器场景」自渲染组件。触发与门控（gating）由播放器负责——SwVideoPlayer 开 pause-ad 后，用户暂停 → 播放器内置 gating（延迟去抖 / 过滤系统暂停 / eligibility / 与付费墙互斥）全通过 → 显 #pause-ad 插槽。本组件只管创意 + 频控 + 埋点：挂载即「有效暂停时机」，按 useAdFrequency 频控决定是否展示，命中则渲染创意卡 + 曝光埋点。

⚠️ 与付费墙 #paywall 严格区分：付费墙 = 变现 / 不可关 / 全屏死挡 / 试看播完触发；本组件 = 广告 / 可关 / 不挡恢复 / 暂停触发。

Props

名称	类型	必填	默认值	说明
`items`	`SwAdItem[]`	✓	—	广告创意（取首条；`image` 必填，可带 `title` / `cta` / `link`）
`slotKey`	`string`	✓	—	广告位键 → `ad_slot_key`
`slotName`	`string`		`undefined`	广告位名 → `ad_slot_name`
`pageKey`	`string`		`undefined`	页面键 → `page_key`
`pageName`	`string`		`undefined`	页面名 → `page_name`
`ratio`	`string`		`'16/9'`	创意图宽高比
`frequency`	`AdFrequencyStrategy`		`'session'`	频控策略（`'session'` 每会话一次 / `'always'` 每次都弹 / `'Nm'`·`'Nh'`·`'Nd'` 每 N 分·时·天一次）
`frequencyKey`	`string`		`undefined`	频控存储键（默认用 `slotKey`）
`closable`	`boolean`		`true`	显示关闭 ✕
`showAdLabel`	`boolean`		`undefined`	「广告」合规角标；不传时跟随全局 `swiftConfig.ad.showLabel`（默认 `true`，暂停广告建议保持开启）

Events

名称	携带	说明
`empty`	—	首条无 `image` 或频控未命中（不渲染）
`impression`	`items: SwAdItem[]`	曝光（展示即报，自动埋点）
`click`	`item: SwAdItem`	点击创意（自动埋点）
`close`	—	点 ✕ 关闭（业务接 slot 的 `close` 收起播放器覆盖层）

用法（渲染进播放器 `#pause-ad` 插槽）

SwAdPause 不独立使用，业务把它放进 SwVideoPlayer 的 #pause-ad 插槽；插槽作用域 { close } 用于关闭：

<SwVideoPlayer :url="videoUrl" type="m3u8" pause-ad @pause-ad="onPauseExposure">
  <template #pause-ad="{ close }">
    <SwAdPause :items="pauseAds" slot-key="play_pause" @close="close" />
  </template>
</SwVideoPlayer>

<!-- 可调项：ratio 创意宽高比；frequency 频控（调试用 0 = 每次暂停都弹）；
     frequency-key 显式频控键——默认取 slot-key，发版换 key 可重置老用户频控；
     closable=false 隐藏 ✕（只能点卡片外恢复播放收起）；
     show-ad-label 不传时跟随全局 ad.showLabel（默认 true，「广告」合规角标，建议保留） -->
<SwAdPause
  :items="pauseAds"
  slot-key="play_pause"
  ratio="16/9"
  frequency="always"
  frequency-key="play-pause-v2"
  :closable="false"
  @close="close"
/>

<script setup>
const pauseAds = [
  { id: 'pa-1', image: '/ad/pause.jpg', title: '限时会员 5 折', cta: '立即开通', link: '/vip' },
]
function onPauseExposure() {
  // 播放器层「有效暂停时机」钩子（与组件 adImpression 独立）
}
</script>

频控

frequency 复用 useAdFrequency：

'session'（默认）：每会话弹一次。
N（数字）：N 天弹一次。
0：每次有效暂停都弹（无频控）。

更细的「每会话 N 次 / 分钟级 cooldown」待真实消费者校准后再加，当前 v1 不引入（YAGNI）。

关闭与恢复

点 ✕：emit('close')，业务接插槽 close() 收起覆盖层；视频保持暂停态（不自动恢复）。
点卡片外画面：覆盖层 wrapper pointer-events:none，点击穿透到画面恢复播放 → 播放器 video:play 自动收起暂停广告（恢复即关）。
频控未命中：emit('empty') 不渲染，透明覆盖层不阻断点击，照常可恢复播放。

样式定制 Token

以下 CSS 变量可在业务侧覆盖（fallback 即默认值）：

变量	默认值	说明
`--sw-ad-pause-card-bg`	`rgb(17 17 20 / 96%)`	创意卡背景
`--sw-ad-pause-card-shadow`	`0 8px 32px rgb(0 0 0 / 45%)`	创意卡投影
`--sw-ad-pause-title-color`	`rgb(255 255 255 / 92%)`	标题文字色
`--sw-ad-pause-cta-bg`	`var(--primary)`	CTA 按钮底色（可填品牌渐变）
`--sw-ad-pause-cta-color`	`rgb(255 255 255)`	CTA 按钮文字色
`--sw-ad-pause-close-bg`	`rgb(0 0 0 / 45%)`	关闭钮底色
`--sw-ad-pause-close-color`	`rgb(255 255 255)`	关闭钮图标色

注意事项

gating 由播放器管：延迟去抖、过滤系统暂停（拖拽 / 缓冲 / 切后台 / 前贴片期 / 完播）、eligibility、与付费墙互斥都在 SwVideoPlayer 内置，本组件挂载即视为有效暂停时机，详见 SwVideoPlayer · 暂停广告。
不挡恢复控件：创意卡居中、卡片外区域可点恢复播放——业务别把卡片做成全屏遮罩。
埋点内置（ad_type=pause），受 tracker 双重 gate。
Demo 说明：本组件渲染进播放器插槽、依赖播放器暂停态触发，独立 Demo 无代表性；可运行 Demo 见 SwVideoPlayer 暂停广告场景（PauseAdDemo，暂停触发 + 恢复即关；故本页按 docs 约定不单列 DemoBox）。