SwAdPreroll

广告位四要素

• 使用场景：视频播放前贴片阶段——放进 SwVideoPlayer / SwVideoFeed 的 #preroll-ad 插槽；倒计时 / 跳过 / 放行由播放器阶段状态机管，本组件只管内容与埋点
• 业界形态：IAB in-stream pre-roll（AdSDK v0.0.1 暂无对应格式，ad_type 用 framework 扩展值 preroll）
• 表现形态：贴片层内单图直出 / 多图轮播，fit=contain 完整显示（播放器黑底兜边），默认带「广告」合规角标
• 打点事件：adImpression（挂载即报——贴片层必然全屏可见，不走 IntersectionObserver）/ adClick；自动内置零配置，tracker gate 关闭静默 no-op

选错场景 = 埋点 ad_type / 时机全错。按场景选组件见 广告组件选型。

SwAdPreroll 是视频前贴片广告组件。与 SwAdBanner 同为图片类自渲染组件（单条直出、多条 SwCarousel 轮播），差异在贴片语境：曝光在挂载时直接上报（贴片层由播放器门控挂载 = 必然可见），图片默认 contain 铺满贴片层。

文案 + CTA overlay（opt-in）：item 带 title / description / cta / advertiser 任一时，自动在创意图上叠加「标题 + 副文案 + CTA 按钮」浮层（像真广告）；只给 image 则保持纯图、不变。CTA 是按钮样的 <span>（整张广告已是链接，点击落 link）。

标准用法（配合播放器贴片阶段）

<script setup lang="ts">
const { data: r } = await useFetch('/movie/detail/1')
// 旧后端 play_ads 协议（{ id, name, content, link }）一行归一
const items = computed(() => playAdsToSwAdItems(r.value?.play_ads))
</script>

<template>
  <SwVideoPlayer
    :links="r.play_links"
    :preroll-ad="items.length > 0"
    :preroll-ad-duration="+r.play_ads_time"
    :preroll-ad-auto-close="r.play_ads_auto_jump === 'y'"
  >
    <template #preroll-ad="{ skip }">
      <!-- @empty：广告数据异常时直接放行进正片，不让用户干等倒计时 -->
      <SwAdPreroll :items="items" slot-key="player_preroll" page-key="movie" @empty="skip()" />
    </template>
  </SwVideoPlayer>
</template>

system/info 的 ads.app_info_player_preroll 槽位与 play_ads 同形，同样用 playAdsToSwAdItems() 归一。

Props

Events

playAdsToSwAdItems

旧后端 play_ads 协议归一函数（auto-import）：

playAdsToSwAdItems(playAds: PlayAdProtocolItem[] | null | undefined): SwAdItem[]
// 映射：id→id(String) / name→name / content(图)→image / link→link
// null / undefined / 非数组 → []（配合 @empty 收口）

创意浮层 Token（--sw-ad-overlay-*）

广告创意上的标题 / 描述 / CTA 浮层由内部 AdOverlay 渲染，SwAdPopup / SwAdSplash 与本组件共用同一套旋钮：

注意事项

• 曝光时机与其它 SwAd* 不同：banner 等用 IntersectionObserver 进视口才报；本组件挂载即报——别把它放在贴片层以外的常规版面（会在不可见时误报曝光），常规版面用 SwAdBanner。
• 倒计时 / 跳过按钮 / 自动放行都是播放器贴片阶段的职责（prerollAdDuration / prerollAdAutoClose / slot 作用域 skip()），本组件不重复实现。
• 视频流贴片（贴片内容是视频而非图片）为 v2 预留，等真实需求。

相关

• SwVideoPlayer 前贴片阶段
• 广告底座与打点 · 广告组件选型