uni-app 微信小程式接入說明

uni-app 微信小程式接入說明

本文件適用於已使用 uni-app 開發微信小程式，並希望在小程式頁面中接入保利威直播觀看頁能力的開發者。

透過本方案，uni-app 專案編譯為微信小程式後，可在頁面中以原生微信小程式自訂元件的方式掛載保利威觀看元件，實現直播觀看、回放觀看、聊天室、觀看條件、互動接收等觀看頁能力。

方案說明

uni-app 微信小程式觀看元件屬於微信小程式端接入方案，元件最終運行在 mp-weixin 產物中。

如果專案只需低成本打開完整觀看頁，可優先評估微信小程式 WebView H5 觀看頁方案。如果專案只需播放器能力，可評估保利威微信小程式直播播放插件、直播播放自訂元件或直播播放核心 SDK。

接入前準備

1. 保利威帳號與頻道

接入前需要準備：

• 可正常登入的保利威直播帳號。
• 已建立的直播頻道。
• 用於測試的頻道 ID。

頻道的觀看條件、回放、聊天室、互動功能等能力，仍以保利威直播後台的頻道配置為準。

2. 微信小程式主體與資質

直播播放、連麥、插件使用等能力與微信小程式主體、服務類目、介面權限和插件權限相關。相關審核與開通動作需在客戶自己的微信小程式 AppID 下完成。

建議接入前確認以下事項：

• 小程式主體已完成微信認證，且非個人主體小程式。
• 小程式服務類目符合實際業務場景與微信審核要求。
• 已在微信公眾平台後台添加保利威觀看元件依賴的小程式插件。
• 如使用連麥能力，已確認 live-pusher、攝影機、麥克風等相關能力可用。
• 已在微信公眾平台與保利威直播後台完成必要的業務域名配置。
• 如功能涉及使用者資訊、攝影機、麥克風等能力，已依微信要求配置使用者隱私保護指引。

資質與類目要求會隨微信平台規則變化而調整，最終以微信公眾平台審核結果為準。

3. 取得元件包

接入方可透過以下兩種方式取得 polyv-live-watch 元件包。

從開源觀看頁專案建置時，可按以下步驟操作：

git clone https://gitee.com/polyv_ef/polyv-mp-live-watch-ui.git
cd polyv-mp-live-watch-ui
npm install
npm run build:uniapp-wxcomponents

建置完成後，元件包產生在：

dist-uniapp-wxcomponents/polyv-live-watch

將該目錄完整複製到 uni-app 專案：

src/wxcomponents/polyv-live-watch

本文後續範例以複製後的以下目錄結構為準：

src
  wxcomponents
    polyv-live-watch
      components
        watch-room
          watch-room.json
          watch-room.js
          watch-room.wxml
          watch-room.wxss
      polyv-live-watch.package.json

polyv-live-watch 是原生微信小程式自訂元件包，必須完整複製整個目錄，不要只複製 watch-room 單一元件。

快速接入

1. 複製元件包

將 polyv-live-watch 目錄複製到 uni-app 專案的 src/wxcomponents 下：

src/wxcomponents/polyv-live-watch

複製後，至少應存在以下入口檔案：

src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.json
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.js
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.wxml
src/wxcomponents/polyv-live-watch/components/watch-room/watch-room.wxss

2. 配置 manifest.json

在 manifest.json 的 mp-weixin 節點中開啟自訂元件支援，並宣告保利威觀看元件依賴的小程式插件：

{
  "mp-weixin": {
    "usingComponents": true,
    "plugins": {
      "polyv-live-plugin": {
        "version": "1.3.1",
        "provider": "wxfb2e591959a8bacf"
      },
      "polyv-player": {
        "version": "1.17.0",
        "provider": "wx4a350a258a6f7876"
      }
    }
  }
}

如果專案中已存在 mp-weixin 配置，只需合併 usingComponents 與 plugins，不要覆蓋專案原有的 appid、setting、permission 等配置。

3. 配置 pages.json

在需要展示觀看頁的 uni-app 頁面中註冊 polyv-watch-room 元件：

{
  "path": "pages/polyv-watch/index",
  "style": {
    "navigationBarTitleText": "直播观看",
    "usingComponents": {
      "polyv-watch-room": "/wxcomponents/polyv-live-watch/components/watch-room/watch-room"
    }
  }
}

路徑以 uni-app 編譯後的微信小程式根目錄為基準，通常使用 /wxcomponents/... 形式。

4. 在頁面中掛載元件

以下範例為 Vue 3 寫法。Vue 2 專案可按相同的參數與事件名稱改寫。

<script setup lang="ts">
import { onLoad, onUnload, onShareAppMessage } from '@dcloudio/uni-app'
import { reactive } from 'vue'

const configs = reactive({
  channelId: '',
  forceLayout: 'portrait',
})

onLoad((query) => {
  configs.channelId = typeof query?.channelId === 'string' ? query.channelId : ''
})

onUnload(() => {
  const pages = getCurrentPages()
  const currentPage = pages[pages.length - 1]
  const room = currentPage?.selectComponent?.('#polyvWatchRoom')
  room?.destroy?.()
})

onShareAppMessage(() => ({}))

function handleReady(event) {
  console.log('polyv watch ready', event.detail)
}

function handleViewChange(event) {
  console.log('polyv watch view change', event.detail)
}

function handleWebview(event) {
  const url = event.detail?.url

  if (!url) {
    return
  }

  uni.navigateTo({
    url: `/pages/webview/index?url=${encodeURIComponent(url)}`,
  })
}

function handleLoginRequired(event) {
  console.log('polyv watch login required', event.detail)
}
</script>

<template>
  <view class="polyv-watch-page">
    <polyv-watch-room
      id="polyvWatchRoom"
      class="polyv-watch-room-host"
      :configs="configs"
      @ready="handleReady"
      @view-change="handleViewChange"
      @webview="handleWebview"
      @login-required="handleLoginRequired"
    />
  </view>
</template>

<style>
page {
  height: 100%;
}

.polyv-watch-page {
  height: 100vh;
  min-height: 100vh;
  overflow: hidden;
}

.polyv-watch-room-host {
  display: block;
  width: 100%;
  height: 100%;
  min-height: 100vh;
}
</style>

頁面只需掛載一次 polyv-watch-room。進入引導頁、觀看頁或錯誤頁的過程由元件內部處理，不需要宿主頁面根據事件重新掛載元件。

參數說明

polyv-watch-room 透過 configs 接收初始化配置。

如後續交付包新增配置項，以對應版本的元件包說明為準。

事件說明

uni-app Vue 模板中建議使用 kebab-case 綁定事件。例如元件內部事件 viewChange，模板中寫作 @view-change；loginRequired 寫作 @login-required。

觀看流程與宿主邊界

本方案中，觀看頁主體由元件內部承載：

polyv-watch-room
  loading
  splash
  watch
  error

元件內部會根據頻道配置與觀看條件決定展示引導頁、授權頁、觀看頁或錯誤頁。宿主 uni-app 頁面只負責提供容器、傳入配置與處理跨出元件邊界的事件。

元件內部處理的行為包括：

• 進入引導或授權檢視。
• 進入觀看檢視。
• 展示錯誤檢視。
• 播放器、聊天室、互動元件等觀看頁內部狀態流轉。

宿主頁面需要處理的行為包括：

• 開啟業務方自己的 WebView 頁面。
• 跳轉到業務方自己的登入頁。
• 依業務方規則配置小程式分享。
• 依業務方規則處理頁面級路由與埋點。

不要在收到 viewChange 後再次建立或掛載新的觀看元件，否則可能導致元件重複初始化、聊天室重複連線或播放狀態異常。

樣式與資源說明

polyv-live-watch 元件包已內建觀看頁所需的業務 WXSS 與靜態資源。接入方通常不需要額外引入保利威原始專案的全域樣式。

宿主頁面建議只提供容器高度：

• page 設定 height: 100%。
• 頁面根節點設定 height: 100vh。
• polyv-watch-room 宿主節點設定 display: block、width: 100%、height: 100%。

不建議在 uni-app 專案的全域樣式中覆蓋 polyv-live-watch 元件包內部類名，例如播放器、聊天室、互動卡片、圖示、按鈕等業務類名。全域覆蓋可能造成圖示尺寸異常、文字省略失效、彈層錯位、按鈕狀態異常等問題。

如果接入後出現明顯樣式異常，建議依以下順序排查：

1. 確認複製的是完整的 polyv-live-watch 目錄。
2. 確認舊版本元件包已被完整覆蓋，不存在新舊檔案混用。
3. 確認 src/wxcomponents/polyv-live-watch 下的 common、assets、package-watch、package-splash 等目錄完整存在。
4. 確認宿主頁面沒有覆蓋元件包內部業務類名。
5. 使用微信開發者工具檢查最終 mp-weixin 產物中元件、WXSS 與圖片資源是否存在。

建置與預覽

完成接入後，執行 uni-app 微信小程式建置指令。例如：

pnpm build:mp-weixin

實際指令以專案使用的套件管理工具與專案腳本為準，也可能是 npm run build:mp-weixin 或 HBuilderX 內建建置。

建置完成後，使用微信開發者工具開啟 dist/build/mp-weixin 目錄，並使用客戶自己的 AppID 進行預覽與真機除錯。

建議至少完成以下驗證：

• 能透過頻道 ID 開啟觀看頁。
• 無條件觀看、驗證碼觀看、登記觀看、白名單觀看等觀看條件依頻道配置正常展示。
• 直播或回放可正常播放。
• 聊天室可正常連線、接收與發送訊息。
• 按讚、簽到、卡片推播、條件抽獎、商品庫等互動能力依頻道配置正常展示。
• WebView 連結可透過 webview 事件交給宿主頁面處理。
• 如使用連麥能力，真機上可正常申請連麥，並能獲得攝影機、麥克風授權。
• 小程式分享、頁面返回、頁面銷毀後再次進入等流程正常。

常見問題

1. 這是完整的 uni-app 多端 SDK 嗎？

不是。本方案只面向 uni-app 編譯到微信小程式後的 mp-weixin 端。App、H5、支付寶小程式、抖音小程式等端側不在本方案涵蓋範圍內。

2. 是否必須由客戶小程式完成資質與插件配置？

是。微信服務類目、插件添加、介面權限、隱私協議與審核結果都綁定到客戶自己的小程式 AppID，不能由保利威測試 AppID 代替。

3. viewChange 事件觸發後是否需要宿主頁面跳轉？

不需要。viewChange 只是通知宿主目前內部檢視變化。觀看流程由 polyv-watch-room 內部承載，宿主頁面不需要根據 viewChange 重新路由或重新掛載觀看元件。

4. 為什麼點擊商品、廣告或外部連結時需要宿主處理？

這類行為已經離開觀看元件邊界，目標頁面通常屬於客戶自己的業務頁面。元件會透過事件把連結或業務資訊拋給宿主頁面，宿主頁面再使用 uni.navigateTo、uni.redirectTo 或自有路由方案處理。

5. 微信開發者工具可以預覽，但真機不可用怎麼辦？

優先檢查以下配置：

• 目前預覽使用的是否為客戶自己的 AppID。
• 微信公眾平台後台是否已添加所需插件。
• 小程式服務類目與介面權限是否滿足目前功能要求。
• request、socket、upload、download、web-view 等業務域名是否已配置。
• 保利威直播後台是否已配置目前小程式的存取域名或相關開發者資訊。
• 真機是否已允許攝影機、麥克風等權限。

相關文件

• 小程式方案選擇指南
• 微信小程式觀看頁 SDK（新版）產品介紹
• 微信小程式觀看頁 SDK（新版）快速上手
• 保利威雲直播小程式播放插件
• 微信觀看小程式 SDK 類目申請資質要求
• uni-app 小程式自訂元件支援
• uni-app 微信小程式插件使用說明