@bi-nova/ui-weapp 1.1.3 → 1.2.0-beta.202608131817

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bi-nova/ui-weapp",
-  "version": "1.1.3",
+  "version": "1.2.0-beta.202608131817",
   "description": "BI Nova SDK WeChat Mini Program Components",
   "miniprogram": "src",
   "license": "ISC",

package/src/ad/README.md

@@ -73,6 +73,10 @@ yarn add @bi-nova/core @bi-nova/services @bi-nova/ui-weapp
 
 广告位配置由我方维护，通常包含实际投放渠道、广告素材、展示开关等信息。业务方一般不需要关心底层配置结构，只需要确保传入的 `ad-id` 与投放场景一致。
 
+### 小程序合法域名
+
+请在微信公众平台将 `https://nad.ehuoke.com` 配置为小程序的 `request 合法域名`。如果未配置，广告位配置请求会被微信拦截，组件无法获取可展示的广告内容。
+
 使用 `ad-id` 前，请确认 SDK 已完成以下初始化：
 
 1. 通过 `createNova` 创建 SDK 实例，并在微信小程序环境开启 `autoEnv: true`。
@@ -161,6 +165,8 @@ getApp().globalData.biNova.clearToken()
 
 开屏广告支持微信原生广告、自定义图片广告、自定义视频广告，并提供倒计时跳过和画中画能力。
 
+广告来源、展示顺序和加载失败后的降级均由广告位配置与组件自动处理。业务方不需要判断广告平台或实现兜底逻辑，只需通过 `load`、`error`、`close` 等事件接收最终状态。
+
 建议承载开屏广告的页面在页面配置中设置 `"navigationStyle": "custom"`，隐藏默认导航栏后开屏广告展示更完整，整体视觉效果更好。
 
 ```json
@@ -171,54 +177,6 @@ getApp().globalData.biNova.clearToken()
 
 `ad-id` 需要使用开屏类型广告位，具体广告位 ID 请向我方获取。
 
-## 广告素材能力
-
-以下字段由广告位配置生成，业务方通常不需要在页面中直接传入。这里仅用于说明广告素材支持的配置能力，便于和我方确认广告位需求。
-
-### 通用字段
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `image` / `imageUrl` | `string` | 图片素材地址。Banner 广告和开屏图片广告使用。 |
-| `title` | `string` | 广告标题。 |
-| `description` | `string` | 广告描述。 |
-| `buttonText` | `string` | 操作按钮文案。 |
-| `badgeText` / `adLabel` | `string` | 广告角标文案，默认 `广告`。 |
-| `loadTimeout` / `timeout` | `number` | 自定义素材加载超时时间，单位毫秒，最小值为 `1000`，默认 `5000`。 |
-
-### 开屏扩展字段
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `video` / `videoUrl` | `string` | 视频素材地址。存在时开屏广告按视频广告渲染。 |
-| `poster` | `string` | 视频封面地址。未传时优先使用 `image`。 |
-| `muted` | `boolean` | 视频是否静音。默认静音，传 `false` 可开启声音。 |
-| `jumpSeconds` | `number` | 当前广告独立倒计时秒数，优先级高于组件 `jump-seconds`。 |
-| `adSpec` / `spec` | `1 \| 2` | 广告规格，`1` 为横版，`2` 为竖版。 |
-| `width` / `videoWidth` | `number` | 素材宽度，用于推断广告规格。 |
-| `height` / `videoHeight` | `number` | 素材高度，用于推断广告规格。 |
-
-### 跳转字段
-
-| 跳转类型 | 字段 | 说明 |
-| --- | --- | --- |
-| 跳转其他小程序 | `appId` / `miniProgramAppId` / `jumpAppId` | 目标小程序 appId。 |
-| 跳转小程序内部页面 | `path` / `pagePath` / `jumpPath` / `targetUrl` | 当前小程序页面路径。 |
-| 打开 WebView | `url` / `webUrl` / `h5Url` / `jumpUrl` | H5 地址。组件不会直接打开 WebView，会触发 `openWebview` 事件交给业务处理。 |
-
-跳转优先级为：其他小程序 > 小程序内部页面 > WebView。
-
-### 示例
-
-```js
-Page({
-  data: {
-    bannerAdId: 'ad_123456',
-    splashAdId: 'launch_splash'
-  }
-})
-```
-
 ## 事件
 
 ### 通用事件
@@ -229,6 +187,7 @@ Page({
 | `error` | 接口请求失败或返回失败码；SDK 未初始化；广告素材加载失败；广告跳转失败 | `{ provider?, type, adId?, errCode, errMsg }` |
 | `close` | 广告关闭；远程配置成功但无可展示广告时也会触发         | `{ provider, type, adId?, reason? }`，无可展示广告时 `reason` 为 `noAd` |
 | `action` | 自定义广告点击                         | `{ provider, type, adId? }` |
+| `feedback` | 自研 Banner 反馈操作 | 不感兴趣：`{ provider, type, adId?, action: 'dislike', reason, reasonText }`；反馈问题：`{ provider, type, adId?, action: 'report' }` |
 | `openWebview` | 自定义广告命中 WebView 跳转              | `{ provider, type, adId?, url }` |
 
 ### 统一广告组件扩展事件
@@ -268,6 +227,7 @@ Page({
 | `DISPLAY_AD_REMOTE_CONFIG_FAIL` | 广告位配置接口返回失败。 |
 | `DISPLAY_AD_REMOTE_CONFIG_EXCEPTION` | 广告位配置请求异常。 |
 | `UNSUPPORTED_DISPLAY_AD_TYPE` | `type` 不是 `banner` 或 `splash`。 |
+| `BI_BANNER_WECHAT_AD_LOAD_FAIL` | 微信原生 Banner 加载失败；存在自研 Banner 时组件会自动降级。 |
 | `BI_BANNER_CUSTOM_MEDIA_LOAD_TIMEOUT` | Banner 自定义图片加载超时。 |
 | `BI_BANNER_CUSTOM_MEDIA_LOAD_FAIL` | Banner 自定义图片加载失败。 |
 | `BI_BANNER_NAVIGATE_MINI_PROGRAM_FAIL` | Banner 自定义广告跳转其他小程序失败。 |
@@ -285,3 +245,4 @@ Page({
 3. WebView 地址不会由组件直接打开，必须由业务页面监听 `openWebview` 后处理。
 4. 使用 `ad-id` 前，需要先把业务 SDK 实例挂载到 `app.biNova`。
 5. 开屏广告页面推荐设置 `"navigationStyle": "custom"`，避免默认导航栏占用展示空间，提升开屏展示效果。
+6. 请将 `https://nad.ehuoke.com` 配置为小程序的 `request 合法域名`，否则无法获取广告位配置。

package/src/ad/banner/index.js

@@ -3,7 +3,7 @@
  * @Author wutao
  * @Date 2026-04-10
  * @LastEditors wutao
- * @LastEditTime 2026-04-17
+ * @LastEditTime 2026-08-13 15:02:40
  */
 const {
   navigateCustomAd
@@ -13,26 +13,34 @@ Component({
   properties: {
     unitId: { type: String, value: '' },
     customAd: { type: Object, value: null },
+    priority: { type: String, value: 'wechat-first' },
     adIntervals: { type: Number, value: 30 }
   },
   data: {
     isWechatAd: false,
+    visible: false,
+    hasCustomMedia: false,
     customLoaded: false,
-    customFailed: false
+    customFailed: false,
+    feedbackVisible: false,
+    feedbackStage: 'primary',
+    dislikeReasons: [
+      { label: '与我无关', value: 'irrelevant' },
+      { label: '重复收到多次', value: 'repeated' },
+      { label: '内容太差', value: 'poorContent' }
+    ]
   },
   lifetimes: {
     attached() {
-      this.syncProvider(this.properties.unitId)
-      this.resetCustomLoadState()
+      this.syncAdSource(this.properties.unitId, this.properties.customAd, this.properties.priority)
     },
     detached() {
       this.clearCustomLoadTimeout()
     }
   },
   observers: {
-    'unitId, customAd'(nextUnitId) {
-      this.syncProvider(nextUnitId)
-      this.resetCustomLoadState()
+    'unitId, customAd, priority'(nextUnitId, nextCustomAd, nextPriority) {
+      this.syncAdSource(nextUnitId, nextCustomAd, nextPriority)
     }
   },
   methods: {
@@ -42,9 +50,17 @@ Component({
      * @returns {{provider: 'wechat' | 'custom', type: 'banner'}}
      */
     createEventDetail(provider) {
+      const customAd = provider === 'custom' && this.properties.customAd || null
+
       return {
         provider,
-        type: 'banner'
+        type: 'banner',
+        ...(customAd ? {
+          configId: customAd.configId,
+          placementId: customAd.placementId,
+          configName: customAd.configName,
+          advertPlatform: customAd.advertPlatform
+        } : {})
       }
     },
 
@@ -81,12 +97,128 @@ Component({
     },
 
     /**
-     * 根据 `unitId` 同步广告来源
+     * 同步 Banner 广告来源与展示状态
+     * @param {string} unitId 微信广告位 ID
+     * @param {Record<string, any> | null} customAd 自研广告配置
+     * @param {string} priority 广告展示优先级
+     * @returns {void}
+     */
+    syncAdSource(unitId, customAd, priority) {
+      const hasCustomMedia = Boolean(customAd && customAd.image)
+      const isWechatAd = this.shouldStartWechatAd(unitId, hasCustomMedia, priority)
+
+      this.clearCustomLoadTimeout()
+      this.resetProviderFailures()
+      this.setData({
+        isWechatAd,
+        visible: Boolean(unitId || hasCustomMedia),
+        hasCustomMedia,
+        customLoaded: false,
+        customFailed: false,
+        feedbackVisible: false,
+        feedbackStage: 'primary'
+      }, () => {
+        if (!isWechatAd && hasCustomMedia) {
+          this.startCustomLoadTimeout()
+        }
+      })
+    },
+
+    /**
+     * 根据广告配置和优先级判断是否首发微信广告
      * @param {string} unitId 微信广告位 ID
+     * @param {boolean} hasCustomMedia 是否存在自研 Banner 素材
+     * @param {string} priority 广告展示优先级
+     * @returns {boolean}
+     */
+    shouldStartWechatAd(unitId, hasCustomMedia, priority) {
+      if (!unitId) return false
+      if (!hasCustomMedia) return true
+      return !['custom-first', 'custom-only'].includes(priority)
+    },
+
+    /**
+     * 重置当前展示周期的广告来源失败记录
+     * @returns {void}
+     */
+    resetProviderFailures() {
+      this.failedProviders = {
+        wechat: false,
+        custom: false
+      }
+    },
+
+    /**
+     * 记录指定广告来源加载失败
+     * @param {'wechat' | 'custom'} provider 广告来源
      * @returns {void}
      */
-    syncProvider(unitId) {
-      this.setData({ isWechatAd: Boolean(unitId) })
+    markProviderFailed(provider) {
+      if (!this.failedProviders) this.resetProviderFailures()
+      this.failedProviders[provider] = true
+    },
+
+    /**
+     * 判断指定广告来源是否已经失败
+     * @param {'wechat' | 'custom'} provider 广告来源
+     * @returns {boolean}
+     */
+    hasProviderFailed(provider) {
+      return Boolean(this.failedProviders && this.failedProviders[provider])
+    },
+
+    /**
+     * 切换当前展示的广告来源
+     * @param {'wechat' | 'custom'} provider 目标广告来源
+     * @returns {void}
+     */
+    switchProvider(provider) {
+      const isWechatAd = provider === 'wechat'
+
+      this.clearCustomLoadTimeout()
+      this.setData({
+        isWechatAd,
+        visible: true,
+        customLoaded: false,
+        customFailed: false,
+        feedbackVisible: false,
+        feedbackStage: 'primary'
+      }, () => {
+        if (!isWechatAd) {
+          this.startCustomLoadTimeout()
+        }
+      })
+    },
+
+    /**
+     * 所有可用广告来源均失败后结束当前 Banner 展示流程
+     * @param {'wechat' | 'custom'} provider 最后失败的广告来源
+     * @param {Record<string, any>} errorDetail 错误详情
+     * @returns {void}
+     */
+    finishProviderFailure(provider, errorDetail) {
+      const hasWechatAd = Boolean(this.properties.unitId)
+      const hasCustomAd = Boolean(this.data.hasCustomMedia)
+      const reason = hasWechatAd && hasCustomAd
+        ? 'allProvidersFailed'
+        : provider === 'wechat'
+          ? 'wechatAdLoadFail'
+          : 'customMediaLoadFail'
+
+      this.clearCustomLoadTimeout()
+      this.setData({
+        visible: false,
+        customLoaded: false,
+        customFailed: provider === 'custom',
+        feedbackVisible: false,
+        feedbackStage: 'primary'
+      })
+      this.triggerEvent('close', {
+        provider,
+        type: 'banner',
+        reason,
+        error: errorDetail
+      })
     },
 
     /**
@@ -103,18 +235,11 @@ Component({
     },
 
     /**
-     * 重置自定义广告加载状态
+     * 启动自研 Banner 素材加载超时检测
      * @returns {void}
      */
-    resetCustomLoadState() {
+    startCustomLoadTimeout() {
       this.clearCustomLoadTimeout()
-      this.setData({
-        customLoaded: false,
-        customFailed: false
-      })
-
-      if (this.properties.unitId || !this.properties.customAd || !this.properties.customAd.image) return
-
       this.customLoadTimer = setTimeout(() => {
         this.handleCustomLoadTimeout()
       }, this.getCustomLoadTimeout())
@@ -137,6 +262,8 @@ Component({
      * @returns {void}
      */
     handleLoad(event) {
+      if (!this.data.isWechatAd) return
+
       this.triggerEvent('load', this.resolveEventDetail('wechat', event))
     },
 
@@ -146,7 +273,25 @@ Component({
      * @returns {void}
      */
     handleError(event) {
-      this.triggerEvent('error', this.resolveEventDetail('wechat', event))
+      if (!this.data.isWechatAd) return
+
+      const rawDetail = event && event.detail && typeof event.detail === 'object' ? event.detail : {}
+      const errorDetail = this.resolveEventDetail('wechat', event, {
+        errCode: 'BI_BANNER_WECHAT_AD_LOAD_FAIL',
+        errMsg: rawDetail.errMsg || '微信 Banner 广告加载失败',
+        rawErrCode: rawDetail.errCode,
+        rawErrMsg: rawDetail.errMsg
+      })
+
+      this.triggerEvent('error', errorDetail)
+      this.markProviderFailed('wechat')
+
+      if (this.data.hasCustomMedia && !this.hasProviderFailed('custom')) {
+        this.switchProvider('custom')
+        return
+      }
+
+      this.finishProviderFailure('wechat', errorDetail)
     },
 
     /**
@@ -155,6 +300,8 @@ Component({
      * @returns {void}
      */
     handleClose(event) {
+      if (!this.data.isWechatAd) return
+
       this.triggerEvent('close', this.resolveEventDetail('wechat', event))
     },
 
@@ -163,7 +310,7 @@ Component({
      * @returns {void}
      */
     handleCustomLoad() {
-      if (this.data.customLoaded) return
+      if (this.data.isWechatAd || this.data.customLoaded) return
 
       this.clearCustomLoadTimeout()
       this.setData({ customLoaded: true })
@@ -175,29 +322,48 @@ Component({
      * @returns {void}
      */
     handleCustomLoadTimeout() {
-      if (this.data.customLoaded || this.data.customFailed) return
+      if (this.data.isWechatAd || this.data.customLoaded || this.data.customFailed) return
 
-      this.setData({ customFailed: true })
-      this.triggerEvent('error', this.resolveEventDetail('custom', null, {
+      this.handleCustomMediaFail(null, {
         errCode: 'BI_BANNER_CUSTOM_MEDIA_LOAD_TIMEOUT',
         errMsg: 'Banner 广告素材加载超时'
-      }))
+      })
     },
 
     /**
-     * 处理自定义广告素材加载失败事件
-     * @param {Record<string, any>} event 素材错误事件
+     * 统一处理自研 Banner 素材加载失败
+     * @param {Record<string, any> | null} event 素材错误事件
+     * @param {Record<string, any>} detail 错误详情
      * @returns {void}
      */
-    handleCustomMediaError(event) {
-      if (this.data.customFailed) return
+    handleCustomMediaFail(event, detail) {
+      if (this.data.isWechatAd || this.data.customFailed) return
 
       this.clearCustomLoadTimeout()
+      const errorDetail = this.resolveEventDetail('custom', event, detail)
+
       this.setData({ customFailed: true })
-      this.triggerEvent('error', this.resolveEventDetail('custom', event, {
+      this.triggerEvent('error', errorDetail)
+      this.markProviderFailed('custom')
+
+      if (this.properties.unitId && !this.hasProviderFailed('wechat')) {
+        this.switchProvider('wechat')
+        return
+      }
+
+      this.finishProviderFailure('custom', errorDetail)
+    },
+
+    /**
+     * 处理自定义广告素材加载失败事件
+     * @param {Record<string, any>} event 素材错误事件
+     * @returns {void}
+     */
+    handleCustomMediaError(event) {
+      this.handleCustomMediaFail(event, {
         errCode: 'BI_BANNER_CUSTOM_MEDIA_LOAD_FAIL',
         errMsg: 'Banner 广告素材加载失败'
-      }))
+      })
     },
 
     /**
@@ -205,6 +371,11 @@ Component({
      * @returns {void}
      */
     handleCustomAction() {
+      if (this.data.feedbackVisible) {
+        this.closeFeedbackPanel()
+        return
+      }
+
       const actionDetail = this.createEventDetail('custom')
 
       this.triggerEvent('action', actionDetail)
@@ -215,8 +386,100 @@ Component({
      * 处理自定义广告关闭事件
      * @returns {void}
      */
-    handleCustomClose() {
-      this.triggerEvent('close', this.createEventDetail('custom'))
+    handleCustomClose(extraDetail) {
+      this.clearCustomLoadTimeout()
+      this.setData({
+        visible: false,
+        feedbackVisible: false,
+        feedbackStage: 'primary'
+      })
+      this.triggerEvent('close', {
+        ...this.createEventDetail('custom'),
+        ...extraDetail
+      })
+    },
+
+    /**
+     * 处理广告标识点击，切换反馈菜单显隐
+     * @returns {void}
+     */
+    handleBadgeTap() {
+      const feedbackVisible = !this.data.feedbackVisible
+
+      this.setData({
+        feedbackVisible,
+        feedbackStage: 'primary'
+      })
+    },
+
+    /**
+     * 拦截反馈浮层内部点击，避免触发 Banner 整体跳转
+     * @returns {void}
+     */
+    handleFeedbackPanelTap() {},
+
+    /**
+     * 关闭反馈菜单并重置一级菜单
+     * @returns {void}
+     */
+    closeFeedbackPanel() {
+      this.setData({
+        feedbackVisible: false,
+        feedbackStage: 'primary'
+      })
+    },
+
+    /**
+     * 处理一级反馈选项
+     * @param {Record<string, any>} event 点击事件
+     * @returns {void}
+     */
+    handleFeedbackOptionTap(event) {
+      const action = event && event.currentTarget && event.currentTarget.dataset && event.currentTarget.dataset.action
+
+      if (action === 'dislike') {
+        this.setData({ feedbackStage: 'dislike' })
+        return
+      }
+
+      if (action === 'report') {
+        this.closeFeedbackPanel()
+        this.triggerEvent('feedback', {
+          ...this.createEventDetail('custom'),
+          action: 'report'
+        })
+
+        if (typeof wx !== 'undefined' && typeof wx.showToast === 'function') {
+          wx.showToast({
+            title: '已收到您的反馈，我们会尽快处理~',
+            icon: 'none',
+            duration: 2000
+          })
+        }
+      }
+    },
+
+    /**
+     * 处理不感兴趣原因并关闭当前 Banner
+     * @param {Record<string, any>} event 点击事件
+     * @returns {void}
+     */
+    handleDislikeReasonTap(event) {
+      const dataset = event && event.currentTarget && event.currentTarget.dataset || {}
+      const reason = dataset.reason || ''
+      const reasonText = dataset.label || ''
+
+      this.triggerEvent('feedback', {
+        ...this.createEventDetail('custom'),
+        action: 'dislike',
+        reason,
+        reasonText
+      })
+      this.handleCustomClose({
+        reason: 'notInterested',
+        feedbackReason: reason,
+        feedbackReasonText: reasonText
+      })
     },
 
     /**

package/src/ad/banner/index.wxml

@@ -1,5 +1,5 @@
 <ad-custom
-  wx:if="{{isWechatAd && unitId}}"
+  wx:if="{{visible && isWechatAd && unitId}}"
   unit-id="{{unitId}}"
   ad-intervals="{{adIntervals}}"
   bind:load="handleLoad"
@@ -8,31 +8,50 @@
 />
 
 <view
-  wx:elif="{{customAd && customAd.image && !customFailed}}"
+  wx:elif="{{visible && !isWechatAd && customAd && customAd.image && !customFailed}}"
   class="bi-banner-ad"
 >
   <view class="bi-banner-ad__surface" bindtap="handleCustomAction">
-    <view class="bi-banner-ad__media">
-      <text class="bi-banner-ad__badge bi-banner-ad__badge--overlay">{{customAd.badgeText || '广告'}}</text>
-      <image
-        class="bi-banner-ad__image"
-        src="{{customAd.image}}"
-        mode="aspectFill"
-        bindload="handleCustomLoad"
-        binderror="handleCustomMediaError"
-      />
-    </view>
-    <view class="bi-banner-ad__content">
-      <view class="bi-banner-ad__body">
-        <text wx:if="{{customAd.title}}" class="bi-banner-ad__title">{{customAd.title}}</text>
+    <image
+      class="bi-banner-ad__image"
+      src="{{customAd.image}}"
+      mode="widthFix"
+      bindload="handleCustomLoad"
+      binderror="handleCustomMediaError"
+    />
+  </view>
+
+  <view class="bi-banner-ad__badge" catchtap="handleBadgeTap">
+    <text>{{customAd.badgeText || '广告'}}</text>
+    <view class="bi-banner-ad__badge-arrow"></view>
+  </view>
+
+  <view
+    wx:if="{{feedbackVisible}}"
+    class="bi-banner-ad__feedback-panel"
+    catchtap="handleFeedbackPanelTap"
+  >
+    <block wx:if="{{feedbackStage === 'primary'}}">
+      <view class="bi-banner-ad__feedback-source">由赞助商提供的内容</view>
+      <view class="bi-banner-ad__feedback-item" data-action="dislike" catchtap="handleFeedbackOptionTap">
+        不感兴趣
+      </view>
+      <view class="bi-banner-ad__feedback-item" data-action="report" catchtap="handleFeedbackOptionTap">
+        反馈问题
       </view>
-      <view class="bi-banner-ad__footer">
-        <text wx:if="{{customAd.description}}" class="bi-banner-ad__description">{{customAd.description}}</text>
-        <button class="bi-banner-ad__button" catchtap="handleCustomAction">
-          {{customAd.buttonText || '立即查看'}}
-        </button>
+    </block>
+
+    <block wx:else>
+      <view
+        wx:for="{{dislikeReasons}}"
+        wx:key="value"
+        class="bi-banner-ad__feedback-item"
+        data-reason="{{item.value}}"
+        data-label="{{item.label}}"
+        catchtap="handleDislikeReasonTap"
+      >
+        {{item.label}}
       </view>
-    </view>
+    </block>
   </view>
-  <button class="bi-banner-ad__close" catchtap="handleCustomClose">×</button>
 </view>