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

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@bi-nova/ui-weapp",
+  "version": "1.1.1-beta.202605161224",
+  "description": "BI Nova SDK WeChat Mini Program Components",
+  "miniprogram": "src",
+  "license": "ISC",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/ad/README.md

@@ -0,0 +1,287 @@
+# WeApp 广告组件
+
+`packages/ui-weapp/src/ad` 提供微信小程序广告展示能力。业务侧统一使用 `bi-display-ad` 接入，并通过我方提供的广告位 ID 获取广告内容；组件内部会根据广告类型渲染 Banner 或开屏广告。
+
+## 组件说明
+
+| 组件 | 路径 | 说明 |
+| --- | --- | --- |
+| `bi-display-ad` | `ad/display/index` | 广告统一接入组件，根据 `type` 渲染 Banner 或开屏广告，并通过 `adId` 获取广告位配置。 |
+
+## 接入方式
+
+业务页面只需要接入 `bi-display-ad`，并传入由我方分配的 `ad-id`。广告形态由 `type` 控制，组件会根据 `ad-id` 自动获取并展示对应广告。
+
+### 安装依赖
+
+```bash
+npm install @bi-nova/core @bi-nova/services @bi-nova/ui-weapp
+```
+
+如果项目使用 pnpm 或 yarn，也可以按项目包管理器安装：
+
+```bash
+pnpm add @bi-nova/core @bi-nova/services @bi-nova/ui-weapp
+```
+
+```bash
+yarn add @bi-nova/core @bi-nova/services @bi-nova/ui-weapp
+```
+
+### 标准接入
+
+```json
+{
+  "usingComponents": {
+    "bi-display-ad": "/miniprogram_npm/@bi-nova/ui-weapp/ad/display/index"
+  }
+}
+```
+
+```xml
+<bi-display-ad
+  ad-id="ad_123456"
+  type="banner"
+  bind:load="handleAdLoad"
+  bind:error="handleAdError"
+  bind:close="handleAdClose"
+  bind:action="handleAdAction"
+  bind:openWebview="handleAdOpenWebview"
+/>
+```
+
+> 具体组件路径以项目构建后的 `miniprogram_npm` 目录为准。如果项目采用源码复制或 monorepo 直接引用方式，请按实际目录调整 `usingComponents` 路径。
+
+## 组件属性
+
+`bi-display-ad` 是广告组件的标准接入入口。业务侧仅需关注广告位 ID、广告类型和必要的展示控制参数。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `ad-id` | `string` | `''` | 我方分配的广告位 ID。组件会根据该 ID 获取广告位配置并展示广告。 |
+| `type` | `'banner' \| 'splash'` | `'banner'` | 广告类型。仅支持 `banner` 和 `splash`。 |
+| `show` | `boolean` | `true` | 是否展示广告。对开屏广告的显隐控制更常用。 |
+| `z-index` | `number` | `999` | 开屏广告容器层级。 |
+| `picture-in-picture` | `boolean` | `false` | 开屏广告跳过后是否进入画中画状态。 |
+| `check-native-splash` | `boolean` | `true` | 开屏广告是否先检查微信系统开屏广告状态，设置为 `false` 可用于真机调试或强制展示远程开屏广告。 |
+| `native-splash-cache` | `boolean` | `true` | 是否缓存微信系统开屏广告承接记录，用于短时间内连续扫码时跳过残留的微信开屏状态检查。 |
+| `jump-seconds` | `number` | `5` | 开屏广告倒计时秒数。 |
+
+## 广告位配置
+
+接入前需要先向我方申请广告位，并获取对应的 `ad-id`。业务页面传入 `ad-id` 后，组件会通过已注入的业务 SDK 获取该广告位的展示配置。
+
+广告位配置由我方维护，通常包含实际投放渠道、广告素材、展示开关等信息。业务方一般不需要关心底层配置结构，只需要确保传入的 `ad-id` 与投放场景一致。
+
+使用 `ad-id` 前，请确认 SDK 已完成以下初始化：
+
+1. 通过 `createNova` 创建 SDK 实例，并在微信小程序环境开启 `autoEnv: true`。
+2. 通过 `createServices` 注册服务插件，广告位配置能力由该插件提供。
+3. 在广告组件渲染前，将 SDK 实例挂载到 `app.biNova`。
+
+```js
+const { createNova } = require('@bi-nova/core')
+const { createServices } = require('@bi-nova/services')
+
+App({
+  onLaunch() {
+    const biNova = createNova({
+      appId: 'your-app-id',
+      autoEnv: true
+    })
+
+    biNova.use(createServices({
+      env: 'prod',
+      debug: false
+    }))
+
+    this.biNova = biNova
+  }
+})
+```
+
+### 登录态说明
+
+`bi-display-ad` 获取广告位配置不需要 token。仅接入广告组件时，业务方只需要创建并注入全局 `biNova` 实例，不需要等待用户登录。
+
+如果同一个 `biNova` 实例还会调用 `handleJdjrCashLoanFlow` 等需要登录态的服务，请在用户登录成功后写入 token：
+
+```js
+getApp().globalData.biNova.setToken(loginResult.token)
+```
+
+用户退出登录或 token 失效时清理：
+
+```js
+getApp().globalData.biNova.clearToken()
+```
+
+广告组件不会因为未写入 token 而阻塞广告配置请求。
+
+> `createNova` 中的 `appId` 用于 SDK 和小程序运行上下文初始化，广告配置请求以组件传入的 `ad-id` 为准。
+
+## Banner 广告
+
+通过 `bi-display-ad` 设置 `type="banner"` 即可展示 Banner 广告。
+
+```xml
+<bi-display-ad
+  ad-id="ad_123456"
+  type="banner"
+  bind:load="handleAdLoad"
+  bind:error="handleAdError"
+  bind:close="handleAdClose"
+  bind:action="handleAdAction"
+  bind:openWebview="handleAdOpenWebview"
+/>
+```
+
+`ad-id` 需要使用 Banner 类型广告位，具体广告位 ID 请向我方获取。
+
+## 开屏广告
+
+通过 `bi-display-ad` 设置 `type="splash"` 即可展示开屏广告。
+
+```xml
+<bi-display-ad
+  ad-id="launch_splash"
+  type="splash"
+  show="{{showSplash}}"
+  z-index="{{999}}"
+  picture-in-picture="{{true}}"
+  jump-seconds="{{5}}"
+  bind:load="handleAdLoad"
+  bind:error="handleAdError"
+  bind:close="handleAdClose"
+  bind:hide="handleAdHide"
+  bind:action="handleAdAction"
+  bind:openWebview="handleAdOpenWebview"
+/>
+```
+
+开屏广告支持微信原生广告、自定义图片广告、自定义视频广告，并提供倒计时跳过和画中画能力。
+
+建议承载开屏广告的页面在页面配置中设置 `"navigationStyle": "custom"`，隐藏默认导航栏后开屏广告展示更完整，整体视觉效果更好。
+
+```json
+{
+  "navigationStyle": "custom"
+}
+```
+
+`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'
+  }
+})
+```
+
+## 事件
+
+### 通用事件
+
+| 事件名 | 说明 | 事件详情 |
+| --- | --- | --- |
+| `load` | 广告加载完成 | `{ provider, type, adId? }` |
+| `error` | 广告加载、配置或跳转失败 | `{ provider?, type, adId?, errCode, errMsg }` |
+| `close` | 广告关闭 | `{ provider, type, adId? }` |
+| `action` | 自定义广告点击 | `{ provider, type, adId? }` |
+| `openWebview` | 自定义广告命中 WebView 跳转 | `{ provider, type, adId?, url }` |
+
+### 统一广告组件扩展事件
+
+| 事件名 | 说明 | 事件详情 |
+| --- | --- | --- |
+| `configload` | 广告位配置加载成功 | `{ type, adId, requestOptions, data }` |
+| `configerror` | 广告位配置加载失败或 SDK 未就绪 | `{ type, adId, errCode, errMsg }` |
+
+### 开屏广告扩展事件
+
+| 事件名 | 说明 | 事件详情 |
+| --- | --- | --- |
+| `hide` | 开屏广告进入画中画状态 | `{ provider, type }` |
+
+## WebView 跳转处理
+
+自定义广告配置 Web 地址时，组件只负责识别并抛出 `openWebview` 事件，业务侧需要自行跳转到承载 H5 的 WebView 页面。
+
+```js
+Page({
+  handleAdOpenWebview(event) {
+    const url = encodeURIComponent(event.detail.url)
+
+    wx.navigateTo({
+      url: `/pages/webview/index?url=${url}`
+    })
+  }
+})
+```
+
+## 错误码
+
+| 错误码 | 说明 |
+| --- | --- |
+| `DISPLAY_AD_SDK_NOT_READY` | 使用 `ad-id` 获取广告位配置时，未获取到可用的全局 SDK 实例。 |
+| `DISPLAY_AD_REMOTE_CONFIG_FAIL` | 广告位配置接口返回失败。 |
+| `DISPLAY_AD_REMOTE_CONFIG_EXCEPTION` | 广告位配置请求异常。 |
+| `UNSUPPORTED_DISPLAY_AD_TYPE` | `type` 不是 `banner` 或 `splash`。 |
+| `BI_BANNER_CUSTOM_MEDIA_LOAD_TIMEOUT` | Banner 自定义图片加载超时。 |
+| `BI_BANNER_CUSTOM_MEDIA_LOAD_FAIL` | Banner 自定义图片加载失败。 |
+| `BI_BANNER_NAVIGATE_MINI_PROGRAM_FAIL` | Banner 自定义广告跳转其他小程序失败。 |
+| `BI_BANNER_NAVIGATE_FAIL` | Banner 自定义广告跳转内部页面失败。 |
+| `BI_SPLASH_WECHAT_AD_LOAD_FAIL` | 微信开屏广告加载失败。 |
+| `BI_SPLASH_CUSTOM_MEDIA_LOAD_TIMEOUT` | 开屏自定义素材加载超时。 |
+| `BI_SPLASH_CUSTOM_MEDIA_LOAD_FAIL` | 开屏自定义素材加载失败。 |
+| `BI_SPLASH_NAVIGATE_MINI_PROGRAM_FAIL` | 开屏自定义广告跳转其他小程序失败。 |
+| `BI_SPLASH_NAVIGATE_FAIL` | 开屏自定义广告跳转内部页面失败。 |
+
+## 注意事项
+
+1. `ad-id` 由我方统一分配，请确保广告位类型与组件 `type` 保持一致。
+2. 开屏广告会优先检查微信系统开屏广告状态，避免和系统开屏广告重复展示。
+3. WebView 地址不会由组件直接打开，必须由业务页面监听 `openWebview` 后处理。
+4. 使用 `ad-id` 前，需要先把业务 SDK 实例挂载到 `app.biNova`。
+5. 开屏广告页面推荐设置 `"navigationStyle": "custom"`，避免默认导航栏占用展示空间，提升开屏展示效果。

package/src/ad/banner/index.js

@@ -0,0 +1,243 @@
+/**
+ * @Description Banner 广告组件
+ * @Author wutao
+ * @Date 2026-04-10
+ * @LastEditors wutao
+ * @LastEditTime 2026-04-17
+ */
+const {
+  navigateCustomAd
+} = require('../utils')
+
+Component({
+  properties: {
+    unitId: { type: String, value: '' },
+    customAd: { type: Object, value: null },
+    adIntervals: { type: Number, value: 30 }
+  },
+  data: {
+    isWechatAd: false,
+    customLoaded: false,
+    customFailed: false
+  },
+  lifetimes: {
+    attached() {
+      this.syncProvider(this.properties.unitId)
+      this.resetCustomLoadState()
+    },
+    detached() {
+      this.clearCustomLoadTimeout()
+    }
+  },
+  observers: {
+    'unitId, customAd'(nextUnitId) {
+      this.syncProvider(nextUnitId)
+      this.resetCustomLoadState()
+    }
+  },
+  methods: {
+    /**
+     * 创建 Banner 事件基础数据
+     * @param {'wechat' | 'custom'} provider 广告提供方
+     * @returns {{provider: 'wechat' | 'custom', type: 'banner'}}
+     */
+    createEventDetail(provider) {
+      return {
+        provider,
+        type: 'banner'
+      }
+    },
+
+    /**
+     * 合并广告事件数据
+     * @param {'wechat' | 'custom'} provider 广告提供方
+     * @param {Record<string, any>} [event] 原始事件对象
+     * @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
+      }
+    },
+
+    /**
+     * 根据 `unitId` 同步广告来源
+     * @param {string} unitId 微信广告位 ID
+     * @returns {void}
+     */
+    syncProvider(unitId) {
+      this.setData({ isWechatAd: Boolean(unitId) })
+    },
+
+    /**
+     * 获取自定义广告素材加载超时时间
+     * @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}
+     */
+    resetCustomLoadState() {
+      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())
+    },
+
+    /**
+     * 清理自定义广告加载超时定时器
+     * @returns {void}
+     */
+    clearCustomLoadTimeout() {
+      if (this.customLoadTimer) {
+        clearTimeout(this.customLoadTimer)
+        this.customLoadTimer = null
+      }
+    },
+
+    /**
+     * 处理广告加载完成事件
+     * @param {Record<string, any>} event 广告加载事件
+     * @returns {void}
+     */
+    handleLoad(event) {
+      this.triggerEvent('load', this.resolveEventDetail('wechat', event))
+    },
+
+    /**
+     * 处理广告错误事件
+     * @param {Record<string, any>} event 广告错误事件
+     * @returns {void}
+     */
+    handleError(event) {
+      this.triggerEvent('error', this.resolveEventDetail('wechat', event))
+    },
+
+    /**
+     * 处理广告关闭事件
+     * @param {Record<string, any>} event 广告关闭事件
+     * @returns {void}
+     */
+    handleClose(event) {
+      this.triggerEvent('close', this.resolveEventDetail('wechat', event))
+    },
+
+    /**
+     * 处理自定义广告加载完成事件
+     * @returns {void}
+     */
+    handleCustomLoad() {
+      if (this.data.customLoaded) return
+
+      this.clearCustomLoadTimeout()
+      this.setData({ customLoaded: true })
+      this.triggerEvent('load', this.createEventDetail('custom'))
+    },
+
+    /**
+     * 处理自定义广告素材加载超时事件
+     * @returns {void}
+     */
+    handleCustomLoadTimeout() {
+      if (this.data.customLoaded || this.data.customFailed) return
+
+      this.setData({ customFailed: true })
+      this.triggerEvent('error', this.resolveEventDetail('custom', null, {
+        errCode: 'BI_BANNER_CUSTOM_MEDIA_LOAD_TIMEOUT',
+        errMsg: 'Banner 广告素材加载超时'
+      }))
+    },
+
+    /**
+     * 处理自定义广告素材加载失败事件
+     * @param {Record<string, any>} event 素材错误事件
+     * @returns {void}
+     */
+    handleCustomMediaError(event) {
+      if (this.data.customFailed) return
+
+      this.clearCustomLoadTimeout()
+      this.setData({ customFailed: true })
+      this.triggerEvent('error', this.resolveEventDetail('custom', event, {
+        errCode: 'BI_BANNER_CUSTOM_MEDIA_LOAD_FAIL',
+        errMsg: 'Banner 广告素材加载失败'
+      }))
+    },
+
+    /**
+     * 处理自定义广告点击事件
+     * @returns {void}
+     */
+    handleCustomAction() {
+      const actionDetail = this.createEventDetail('custom')
+
+      this.triggerEvent('action', actionDetail)
+      this.handleCustomNavigation(actionDetail)
+    },
+
+    /**
+     * 处理自定义广告关闭事件
+     * @returns {void}
+     */
+    handleCustomClose() {
+      this.triggerEvent('close', this.createEventDetail('custom'))
+    },
+
+    /**
+     * 处理自定义广告跳转逻辑
+     * @param {Record<string, any>} actionDetail 点击事件载荷
+     * @returns {void}
+     */
+    handleCustomNavigation(actionDetail) {
+      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_BANNER_NAVIGATE_MINI_PROGRAM_FAIL',
+        navigateErrorCode: 'BI_BANNER_NAVIGATE_FAIL'
+      })
+    }
+  }
+})

package/src/ad/banner/index.json

@@ -0,0 +1,3 @@
+{
+  "component": true
+}

package/src/ad/banner/index.wxml

@@ -0,0 +1,38 @@
+<ad-custom
+  wx:if="{{isWechatAd && unitId}}"
+  unit-id="{{unitId}}"
+  ad-intervals="{{adIntervals}}"
+  bind:load="handleLoad"
+  bind:error="handleError"
+  bind:close="handleClose"
+/>
+
+<view
+  wx:elif="{{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>
+      </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>
+      </view>
+    </view>
+  </view>
+  <button class="bi-banner-ad__close" catchtap="handleCustomClose">×</button>
+</view>