@bi-nova/ui-weapp 1.1.1-beta.202605161224

package/src/ad/splash/index.js

@@ -0,0 +1,782 @@
+/**
+ * @Description 开屏广告组件
+ * @Author wutao
+ * @Date 2026-04-10
+ * @LastEditors wutao
+ * @LastEditTime 2026-05-13
+ */
+const {
+  navigateCustomAd
+} = require('../utils')
+
+Component({
+  properties: {
+    unitId: { type: String, value: '' },
+    customAd: { type: Object, value: null },
+    show: { type: Boolean, value: true },
+    zIndex: { type: Number, value: 999 },
+    pictureInPicture: { type: Boolean, value: false },
+    checkNativeSplash: { type: Boolean, value: true },
+    jumpSeconds: { type: Number, value: 5 }
+  },
+  data: {
+    isWechatAd: false,
+    visible: false,
+    showPiP: false,
+    remainingSeconds: 0,
+    mediaUrl: '',
+    posterUrl: '',
+    isImage: true,
+    adSpec: 2,
+    hasCustomMedia: false,
+    customLoaded: false,
+    skipStyle: '',
+    adBadgeText: '广告',
+    contentStyle: '',
+    badgeStyle: '',
+    pipAnimating: false,
+    nativeSplashActive: false
+  },
+  lifetimes: {
+    attached() {
+      /** 系统开屏状态重试次数 */
+      this.checkSplashNum = 0
+      this.initSkipStyle()
+      this.initSafeAreaStyle()
+      this.syncAdSource(this.properties.unitId, this.properties.customAd)
+      this.syncVisible(this.properties.show)
+    },
+    detached() {
+      this.clearAllTimers()
+    }
+  },
+  observers: {
+    'unitId, customAd'(nextUnitId, nextCustomAd) {
+      this.syncAdSource(nextUnitId, nextCustomAd)
+      this.syncVisible(this.properties.show)
+    },
+    show(nextShow) {
+      this.syncVisible(nextShow)
+    },
+    checkNativeSplash() {
+      this.restartNativeSplashCheck()
+    }
+  },
+  methods: {
+    /**
+     * 微信系统开屏检测开关变更后重新同步展示状态
+     * @returns {void}
+     */
+    restartNativeSplashCheck() {
+      this.clearAllTimers()
+      this.checkSplashNum = 0
+      this.setData({
+        nativeSplashActive: false
+      })
+      this.syncVisible(this.properties.show)
+    },
+
+    /**
+     * 创建开屏广告事件基础数据
+     * @param {'wechat' | 'custom'} provider 广告提供方
+     * @returns {{provider: 'wechat' | 'custom', type: 'splash'}}
+     */
+    createEventDetail(provider) {
+      return {
+        provider,
+        type: 'splash'
+      }
+    },
+
+    /**
+     * 合并广告事件数据
+     * @param {'wechat' | 'custom'} provider 广告提供方
+     * @param {Record<string, any>} [event] 原始事件对象
+     * @param {Record<string, any>} [extraDetail] 附加事件数据
+     * @returns {Record<string, any>}
+     */
+    resolveEventDetail(provider, event, extraDetail) {
+      const baseDetail = this.createEventDetail(provider)
+      const detail = event && event.detail && typeof event.detail === 'object' ? event.detail : null
+
+      if (detail) {
+        return {
+          ...baseDetail,
+          ...detail,
+          ...extraDetail
+        }
+      }
+
+      if (event && typeof event === 'object') {
+        return {
+          ...baseDetail,
+          ...event,
+          ...extraDetail
+        }
+      }
+
+      return {
+        ...baseDetail,
+        ...extraDetail
+      }
+    },
+
+    /**
+     * 同步广告来源与媒体数据
+     * @param {string} unitId 微信广告位 ID
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @returns {void}
+     */
+    syncAdSource(unitId, customAd) {
+      /** 是否为微信原生广告 */
+      const isWechatAd = Boolean(unitId)
+      /** 主媒体地址 */
+      const mediaUrl = this.getMediaUrl(customAd)
+      /** 视频封面地址 */
+      const posterUrl = this.getPosterUrl(customAd, mediaUrl)
+      /** 是否存在自定义媒体 */
+      const hasCustomMedia = Boolean(mediaUrl)
+      /** 是否为图片媒体 */
+      const isImage = this.getIsImage(customAd, mediaUrl)
+      /** 广告规格，1 横版，2 竖版 */
+      const adSpec = this.getAdSpec(customAd)
+      /** 广告角标文案 */
+      const adBadgeText = this.getAdBadgeText(customAd)
+
+      this.setData({
+        isWechatAd,
+        mediaUrl,
+        posterUrl,
+        hasCustomMedia,
+        isImage,
+        adSpec,
+        adBadgeText
+      })
+    },
+
+    /**
+     * 同步组件显隐状态
+     * @param {boolean} nextShow 是否展示
+     * @returns {void}
+     */
+    syncVisible(nextShow) {
+      if (!nextShow) {
+        this.clearAllTimers()
+        this.setData({
+          visible: false,
+          showPiP: false,
+          remainingSeconds: 0,
+          customLoaded: false,
+          pipAnimating: false,
+          nativeSplashActive: false
+        })
+        return
+      }
+
+      this.checkSplashNum = 0
+      this.resetVisibleState()
+      this.checkSplashAdStatus()
+    },
+
+    /**
+     * 重置组件可见状态
+     * @returns {void}
+     */
+    resetVisibleState() {
+      /** 当前倒计时秒数 */
+      const remainingSeconds = this.getJumpSeconds()
+      /** 当前展示周期是否已由微信系统开屏广告承接 */
+      const nativeSplashActive = Boolean(this.properties.checkNativeSplash && this.data.nativeSplashActive)
+      /** 是否允许展示组件 */
+      const visible = !nativeSplashActive && Boolean(this.properties.unitId || this.data.hasCustomMedia)
+
+      this.clearAllTimers()
+      this.setData({
+        visible,
+        showPiP: false,
+        remainingSeconds,
+        customLoaded: false,
+        pipAnimating: false
+      }, () => {
+        this.startWechatCountDownIfNeeded()
+      })
+
+      if (visible && !this.properties.unitId && this.data.hasCustomMedia) {
+        this.startCustomLoadTimeout()
+      }
+    },
+
+    /**
+     * 获取跳过倒计时秒数
+     * @returns {number}
+     */
+    getJumpSeconds() {
+      /** 自定义广告跳过秒数 */
+      const customSeconds = this.properties.customAd && this.properties.customAd.jumpSeconds
+      /** 最终生效跳过秒数 */
+      const fallbackSeconds = customSeconds != null ? customSeconds : this.properties.jumpSeconds
+      return Math.min(99, Math.max(0, Number(fallbackSeconds) || 0))
+    },
+
+    /**
+     * 获取广告媒体地址
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @returns {string}
+     */
+    getMediaUrl(customAd) {
+      if (!customAd) return ''
+      return customAd.image || customAd.video || ''
+    },
+
+    /**
+     * 获取广告封面地址
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @param {string} mediaUrl 主媒体地址
+     * @returns {string}
+     */
+    getPosterUrl(customAd, mediaUrl) {
+      if (!customAd) return ''
+      return customAd.poster || customAd.image || mediaUrl || ''
+    },
+
+    /**
+     * 判断媒体是否为图片
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @param {string} mediaUrl 主媒体地址
+     * @returns {boolean}
+     */
+    getIsImage(customAd, mediaUrl) {
+      if (!customAd) return true
+      if (customAd.video) return false
+      if (customAd.image) return true
+      return /\.(jpg|jpeg|png|gif|bmp|webp|svg|ico)$/i.test(String(mediaUrl || '').trim())
+    },
+
+    /**
+     * 获取广告规格
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @returns {number}
+     */
+    getAdSpec(customAd) {
+      if (!customAd) return 2
+
+      /** 显式传入的广告规格 */
+      const adSpec = Number(customAd.adSpec || customAd.spec || 0)
+      if (adSpec === 1 || adSpec === 2) return adSpec
+
+      /** 媒体宽度 */
+      const width = Number(customAd.videoWidth || customAd.width || 0)
+      /** 媒体高度 */
+      const height = Number(customAd.videoHeight || customAd.height || 0)
+
+      if (width > 0 && height > 0) {
+        return width > height ? 1 : 2
+      }
+
+      return customAd.video ? 1 : 2
+    },
+
+    /**
+     * 获取广告角标文案
+     * @param {Record<string, any> | null} customAd 自定义广告数据
+     * @returns {string}
+     */
+    getAdBadgeText(customAd) {
+      if (!customAd) return '广告'
+      return customAd.badgeText || customAd.adLabel || '广告'
+    },
+
+    /**
+     * 初始化跳过按钮位置样式
+     * @returns {void}
+     */
+    initSkipStyle() {
+      /** @type {{top?: number, right?: number, height?: number, left?: number}} */
+      const menuButtonRect =
+        typeof wx.getMenuButtonBoundingClientRect === 'function'
+          ? wx.getMenuButtonBoundingClientRect()
+          : {}
+      /** @type {{windowWidth?: number, windowHeight?: number, screenHeight?: number}} */
+      const windowInfo =
+        typeof wx.getWindowInfo === 'function'
+          ? wx.getWindowInfo()
+          : typeof wx.getSystemInfoSync === 'function'
+            ? wx.getSystemInfoSync()
+            : {}
+
+      /** 是否可按原生菜单胶囊对齐 */
+      const isFullScreen = windowInfo.windowHeight === windowInfo.screenHeight
+      /** 默认顶部距离 */
+      const defaultTop = 16
+      /** 默认右侧距离 */
+      const defaultRight = 16
+      /** 默认左侧距离 */
+      const defaultLeft = 16
+      /** 默认高度 */
+      const defaultHeight = 32
+      /** 跳过按钮顶部偏移 */
+      const top = isFullScreen && menuButtonRect.top ? menuButtonRect.top : defaultTop
+      /** 跳过按钮高度 */
+      const height = isFullScreen && menuButtonRect.height ? menuButtonRect.height : defaultHeight
+      /** 跳过按钮水平定位样式 */
+      const horizontalStyle = isFullScreen ? `left:${defaultLeft}px` : `right:${defaultRight}px`
+
+      this.setData({
+        skipStyle: [
+          `top:${top}px`,
+          horizontalStyle,
+          `height:${height}px`,
+          `line-height:${height}px`,
+          `border-radius:${Math.round(height / 2)}px`
+        ].join(';')
+      })
+    },
+
+    /**
+     * 初始化安全区相关样式
+     * @returns {void}
+     */
+    initSafeAreaStyle() {
+      /** @type {{safeArea?: {bottom?: number}, screenHeight?: number, windowHeight?: number}} */
+      const systemInfo =
+        typeof wx.getWindowInfo === 'function'
+          ? wx.getWindowInfo()
+          : typeof wx.getSystemInfoSync === 'function'
+            ? wx.getSystemInfoSync()
+            : {}
+      /** 底部安全区高度 */
+      const safeBottom = Math.max(
+        0,
+        Number(systemInfo.screenHeight || 0) - Number(systemInfo.safeArea && systemInfo.safeArea.bottom || systemInfo.windowHeight || 0)
+      )
+      /** 内容区底部间距 */
+      const contentBottom = safeBottom > 0 ? safeBottom + 42 : 84
+      /** 角标底部间距 */
+      const badgeBottom = safeBottom > 0 ? safeBottom + 88 : 130
+
+      this.setData({
+        contentStyle: `bottom:${contentBottom}px;`,
+        badgeStyle: `bottom:${badgeBottom}px;`
+      })
+    },
+
+    /**
+     * 启动广告倒计时
+     * @returns {void}
+     */
+    startCountDown() {
+      // 倒计时可能由容器展示兜底、微信广告 load 回调等多个入口触发；已启动、不可见或画中画状态下不重复处理。
+      if (this.countDownTimer || !this.data.visible || this.data.showPiP) return
+
+      if (this.data.remainingSeconds <= 0) {
+        this.handleSkip()
+        return
+      }
+
+      this.countDownTimer = setInterval(() => {
+        /** 下一秒剩余时间 */
+        const nextSeconds = this.data.remainingSeconds - 1
+
+        if (nextSeconds <= 0) {
+          this.clearCountDown()
+          this.setData({ remainingSeconds: 0 })
+          this.handleSkip()
+          return
+        }
+
+        this.setData({ remainingSeconds: nextSeconds })
+      }, 1000)
+    },
+
+    /**
+     * 清理倒计时实例
+     * @returns {void}
+     */
+    clearCountDown() {
+      if (this.countDownTimer) {
+        clearInterval(this.countDownTimer)
+        this.countDownTimer = null
+      }
+    },
+
+    /**
+     * 获取自定义广告素材加载超时时间
+     * @returns {number}
+     */
+    getCustomLoadTimeout() {
+      /** @type {Record<string, any> | null} 自定义广告数据 */
+      const customAd = this.properties.customAd
+      /** 自定义超时时间，单位毫秒 */
+      const timeout = customAd && (customAd.loadTimeout || customAd.timeout)
+
+      return Math.max(1000, Number(timeout) || 5000)
+    },
+
+    /**
+     * 启动自定义广告素材加载超时检测
+     * @returns {void}
+     */
+    startCustomLoadTimeout() {
+      this.clearCustomLoadTimeout()
+      this.customLoadTimer = setTimeout(() => {
+        this.handleCustomLoadTimeout()
+      }, this.getCustomLoadTimeout())
+    },
+
+    /**
+     * 清理自定义广告素材加载超时定时器
+     * @returns {void}
+     */
+    clearCustomLoadTimeout() {
+      if (this.customLoadTimer) {
+        clearTimeout(this.customLoadTimer)
+        this.customLoadTimer = null
+      }
+    },
+
+    /**
+     * 清理系统开屏状态重试定时器
+     * @returns {void}
+     */
+    clearSplashStatusRetry() {
+      if (this.splashStatusTimer) {
+        clearTimeout(this.splashStatusTimer)
+        this.splashStatusTimer = null
+      }
+    },
+
+    /**
+     * 清理画中画动画延迟定时器
+     * @returns {void}
+     */
+    clearPiPTransitionTimer() {
+      if (this.pipTransitionTimer) {
+        clearTimeout(this.pipTransitionTimer)
+        this.pipTransitionTimer = null
+      }
+    },
+
+    /**
+     * 清理组件内全部定时器
+     * @returns {void}
+     */
+    clearAllTimers() {
+      this.clearCountDown()
+      this.clearCustomLoadTimeout()
+      this.clearSplashStatusRetry()
+      this.clearPiPTransitionTimer()
+    },
+
+    /**
+     * 微信原生广告确认展示后启动倒计时兜底，避免 ad-custom load 回调偶发未触发时卡在初始秒数
+     * @returns {void}
+     */
+    startWechatCountDownIfNeeded() {
+      // 微信原生广告 load 回调在重新编译、缓存恢复等场景下可能不稳定；只要原生广告容器已展示，就允许兜底启动倒计时。
+      if (!this.properties.show || !this.properties.unitId || !this.data.visible || this.data.showPiP) return
+
+      this.startCountDown()
+    },
+
+    /**
+     * 设置开屏广告可见状态并按需启动微信原生广告倒计时
+     * @param {boolean} visible 是否展示开屏广告
+     * @returns {void}
+     */
+    setVisibleAndStartWechatCountDownIfNeeded(visible) {
+      this.setData({
+        visible: Boolean(visible)
+      }, () => {
+        this.startWechatCountDownIfNeeded()
+      })
+    },
+
+    /**
+     * 检查系统开屏广告状态
+     * @returns {void}
+     */
+    checkSplashAdStatus() {
+      if (!this.properties.show) return
+
+      if (!this.properties.checkNativeSplash) {
+        this.setData({
+          visible: Boolean(this.properties.unitId || this.data.hasCustomMedia),
+          nativeSplashActive: false
+        }, () => {
+          this.startWechatCountDownIfNeeded()
+        })
+        return
+      }
+
+      if (this.data.nativeSplashActive) {
+        this.setData({ visible: false })
+        return
+      }
+
+      if (!wx.getShowSplashAdStatus || this.checkSplashNum >= 3) {
+        this.setVisibleAndStartWechatCountDownIfNeeded(Boolean(this.properties.unitId || this.data.hasCustomMedia))
+        return
+      }
+
+      wx.getShowSplashAdStatus({
+        success: (result) => {
+          if (result.code === -1) {
+            this.checkSplashNum += 1
+            this.clearSplashStatusRetry()
+            this.splashStatusTimer = setTimeout(() => {
+              this.splashStatusTimer = null
+              this.checkSplashAdStatus()
+            }, 300)
+            return
+          }
+
+          if (result.code === 1) {
+            this.clearAllTimers()
+            this.setData({
+              visible: false,
+              nativeSplashActive: true
+            })
+            this.triggerEvent('load', this.resolveEventDetail('wechat', null, { nativeSplash: true }))
+            return
+          }
+
+          this.setVisibleAndStartWechatCountDownIfNeeded(Boolean(this.properties.unitId || this.data.hasCustomMedia))
+        },
+        fail: () => {
+          this.setVisibleAndStartWechatCountDownIfNeeded(Boolean(this.properties.unitId || this.data.hasCustomMedia))
+        }
+      })
+    },
+
+    /**
+     * 处理微信广告加载完成事件
+     * @param {Record<string, any>} event 广告加载事件
+     * @returns {void}
+     */
+    handleLoad(event) {
+      this.startCountDown()
+      this.triggerEvent('load', this.resolveEventDetail('wechat', event))
+    },
+
+    /**
+     * 处理广告错误事件
+     * @param {Record<string, any>} event 广告错误事件
+     * @returns {void}
+     */
+    handleError(event) {
+      const rawDetail = event && event.detail && typeof event.detail === 'object' ? event.detail : {}
+      const errorDetail = this.resolveEventDetail('wechat', event, {
+        errCode: 'BI_SPLASH_WECHAT_AD_LOAD_FAIL',
+        errMsg: rawDetail.errMsg || '微信开屏广告加载失败',
+        rawErrCode: rawDetail.errCode,
+        rawErrMsg: rawDetail.errMsg
+      })
+
+      this.triggerEvent('error', errorDetail)
+      this.fallbackFromWechatAd(errorDetail)
+    },
+
+    /**
+     * 微信广告加载失败后的降级处理
+     * @param {Record<string, any>} errorDetail 微信广告错误详情
+     * @returns {void}
+     */
+    fallbackFromWechatAd(errorDetail) {
+      if (!this.data.isWechatAd) return
+
+      this.clearAllTimers()
+
+      if (this.data.hasCustomMedia) {
+        this.setData({
+          isWechatAd: false,
+          visible: true,
+          showPiP: false,
+          remainingSeconds: this.getJumpSeconds(),
+          customLoaded: false,
+          pipAnimating: false
+        })
+        this.startCustomLoadTimeout()
+        return
+      }
+
+      this.setData({
+        visible: false,
+        showPiP: false,
+        remainingSeconds: 0,
+        customLoaded: false,
+        pipAnimating: false
+      })
+      this.triggerEvent('close', {
+        provider: 'wechat',
+        type: 'splash',
+        reason: 'wechatAdLoadFail',
+        error: errorDetail
+      })
+    },
+
+    /**
+     * 处理自定义广告加载完成事件
+     * @returns {void}
+     */
+    handleCustomLoad() {
+      if (this.data.customLoaded) return
+
+      this.clearCustomLoadTimeout()
+      this.setData({ customLoaded: true })
+      this.startCountDown()
+      this.triggerEvent('load', this.createEventDetail('custom'))
+    },
+
+    /**
+     * 处理自定义广告素材加载超时事件
+     * @returns {void}
+     */
+    handleCustomLoadTimeout() {
+      if (this.data.customLoaded) return
+
+      this.handleCustomMediaFail(null, {
+        errCode: 'BI_SPLASH_CUSTOM_MEDIA_LOAD_TIMEOUT',
+        errMsg: '开屏自定义广告素材加载超时'
+      })
+    },
+
+    /**
+     * 统一处理自定义广告素材失败事件
+     * @param {Record<string, any> | null} event 素材错误事件
+     * @param {Record<string, any>} detail 错误详情
+     * @returns {void}
+     */
+    handleCustomMediaFail(event, detail) {
+      this.clearAllTimers()
+      this.setData({
+        visible: false,
+        showPiP: false,
+        remainingSeconds: 0,
+        customLoaded: false,
+        pipAnimating: false
+      })
+      this.triggerEvent('error', this.resolveEventDetail('custom', event, detail))
+    },
+
+    /**
+     * 处理自定义广告素材加载失败事件
+     * @param {Record<string, any>} event 素材错误事件
+     * @returns {void}
+     */
+    handleCustomMediaError(event) {
+      this.handleCustomMediaFail(event, {
+        errCode: 'BI_SPLASH_CUSTOM_MEDIA_LOAD_FAIL',
+        errMsg: '开屏自定义广告素材加载失败'
+      })
+    },
+
+    /**
+     * 处理广告点击事件
+     * @returns {void}
+     */
+    handleAction() {
+      /** @type {'wechat' | 'custom'} 当前广告来源 */
+      const provider = this.data.isWechatAd ? 'wechat' : 'custom'
+      /** @type {Record<string, any>} 点击事件载荷 */
+      const actionDetail = this.createEventDetail(provider)
+
+      this.triggerEvent('action', actionDetail)
+
+      if (provider === 'custom') {
+        this.handleCustomNavigation(actionDetail)
+      }
+    },
+
+    /**
+     * 处理自定义广告跳转逻辑
+     * @param {Record<string, any>} actionDetail 点击事件载荷
+     * @returns {void}
+     */
+    handleCustomNavigation(actionDetail) {
+      /** @type {Record<string, any> | null} 自定义广告数据 */
+      const customAd = this.properties.customAd
+
+      if (!customAd) return
+
+      navigateCustomAd({
+        customAd: this.properties.customAd,
+        actionDetail,
+        onOpenWebview: (detail) => {
+          this.triggerEvent('openWebview', detail)
+        },
+        onError: (detail) => {
+          this.triggerEvent('error', detail)
+        },
+        resolveEventDetail: (provider, event, extraDetail) => this.resolveEventDetail(provider, event, extraDetail),
+        miniProgramErrorCode: 'BI_SPLASH_NAVIGATE_MINI_PROGRAM_FAIL',
+        navigateErrorCode: 'BI_SPLASH_NAVIGATE_FAIL'
+      })
+    },
+
+    /**
+     * 统一处理广告关闭逻辑
+     * @param {Record<string, any>} detail 关闭事件数据
+     * @returns {void}
+     */
+    handleClose(detail) {
+      this.clearAllTimers()
+      this.setData({
+        visible: false,
+        showPiP: false,
+        remainingSeconds: 0,
+        customLoaded: false,
+        pipAnimating: false
+      })
+      this.triggerEvent('close', detail || { type: 'splash' })
+    },
+
+    /**
+     * 处理微信广告关闭事件
+     * @param {Record<string, any>} event 微信广告关闭事件
+     * @returns {void}
+     */
+    handleWechatClose(event) {
+      this.handleClose(this.resolveEventDetail('wechat', event))
+    },
+
+    /**
+     * 处理跳过与画中画逻辑
+     * @returns {void}
+     */
+    handleSkip() {
+      /** @type {'wechat' | 'custom'} 当前广告来源 */
+      const provider = this.data.isWechatAd ? 'wechat' : 'custom'
+
+      if (this.properties.pictureInPicture) {
+        this.clearCountDown()
+        this.clearCustomLoadTimeout()
+        this.clearPiPTransitionTimer()
+        this.setData({ pipAnimating: true })
+        this.pipTransitionTimer = setTimeout(() => {
+          this.pipTransitionTimer = null
+          this.setData({
+            showPiP: true,
+            pipAnimating: false
+          })
+          this.triggerEvent('hide', this.createEventDetail(provider))
+        }, 280)
+        return
+      }
+
+      this.handleClose({ type: 'splash', provider })
+    },
+
+    /**
+     * 关闭画中画广告
+     * @returns {void}
+     */
+    handlePiPClose() {
+      this.handleClose({
+        type: 'splash',
+        provider: this.data.isWechatAd ? 'wechat' : 'custom'
+      })
+    }
+  }
+})
+
+