小編精選 - 技術文章翻譯 · 05月14日

H5 嵌入微信／支付寶／抖音小程序 WebView：呼叫原生能力完整方案

H5 嵌入微信／支付寶／抖音小程式 WebView：呼叫原生能力完整方案

一、前言

在業務開發中，經常會把H5 頁面透過 web-view 元件嵌入到微信、支付寶、抖音小程式中。一般瀏覽器 H5 的 <input type="file"> 在各小程式 WebView 中存在相容性差、權限限制、無法啟動相機／相簿、不支援影片等問題。

各平台均提供了專屬 JS-SDK，讓 WebView 內的 H5 可以呼叫小程式原生能力（拍照、選相簿、定位、授權、分享等）。本文以選擇圖片／拍照為核心範例，統一講解微信、支付寶、抖音三端的實作原理、接入方式、程式碼範例、差異比較。

二、核心通用原理

H5 執行在小程式 web-view 容器內；
引入對應平台JS-SDK，建立 H5 ↔ 小程式通訊橋梁；
呼叫平台提供的原生 API，喚起相簿選擇／相機拍照；
回傳 success 取得本機暫存檔；
將暫存檔上傳至伺服器／OSS，生成永久網路位址。

重要前提：

小程式後台設定 業務網域／WebView 合法網域；

H5 網域需設定 HTTPS；

三端都不建議使用原生 input-file，優先用平台 SDK。

三、微信小程式 WebView H5 呼叫選圖

1. 注意

需要引入微信 JSSDK；
必須由後端產生簽章，前端 wx.config 設定；
僅支援圖片，不支援直接選取影片；
支援相簿、拍照。

2. 接入方式

引入 SDK：CDN 或 npm weixin-js-sdk
後端產生 timestamp、nonceStr、signature
H5 設定 wx.config
呼叫 wx.chooseImage

3. 完整範例程式碼

html 體驗AI代碼助手 代碼解讀複製代碼<!-- 引入微信JSSDK -->
<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
<button id="btn">微信選圖／拍照</button>
<script>
// 1. 從後端取得設定參數
async function getWxConfig() {
  const url = location.href.split('#')[0];
  const res = await fetch(`/api/wx-jssdk-config?pageUrl=${encodeURIComponent(url)}`);
  return await res.json();
}

// 2. 初始化wx.config
async function initWx() {
  const config = await getWxConfig();
  wx.config({
    debug: false,
    appId: config.appId,
    timestamp: config.timestamp,
    nonceStr: config.nonceStr,
    signature: config.signature,
    jsApiList: ['chooseImage', 'getLocalImgData']
  });
}

// 3. 選圖／拍照
document.getElementById('btn').addEventListener('click', () => {
  wx.chooseImage({
    count: 1,
    sourceType: ['album', 'camera'], // 相簿 + 拍照
    success: (res) => {
      // res.localIds 為圖片本機 ID 陣列
      console.log('選擇圖片成功', res.localIds);

      // 進一步取得 base64 預覽／上傳
      wx.getLocalImgData({
        localId: res.localIds[0],
        success: (imgRes) => {
          console.log('圖片 Base64', imgRes.localData);
          // 可用於預覽、表單提交、上傳伺服器
        }
      });
    },
    fail: (err) => {
      console.error('選擇圖片失敗', err);
    }
  });
});

// 初始化
initWx();
</script>

4. 關鍵說明

appId 用微信公眾號 AppID，不是小程式；
timestamp/nonceStr/signature 由後端透過 SHA1 簽章產生，前端不可硬編碼；
只能選圖片，影片需透過 postMessage 轉發給小程式原生處理。

四、支付寶小程式 WebView H5 呼叫選擇圖片

1. 注意

無需後端簽章、無需複雜 config；
監聽 AlipayJSBridgeReady 就緒即可呼叫；
SDK 僅支援圖片，不支援直接選取影片；

2. 接入方式

CDN 引入支付寶 JSAPI；
等待 JSBridge 就緒；
呼叫 ap.chooseImage。

3. 完整範例程式碼

html 體驗AI代碼助手 代碼解讀複製代碼<!-- 引入支付寶JS-SDK -->
<script src="https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.min.js"></script>
<button id="aliBtn">支付寶選圖／拍照</button>
<script>
// 等待支付寶JS橋就緒
function alipayReady(cb) {
  if (window.AlipayJSBridge) {
    cb();
    return;
  }
  document.addEventListener('AlipayJSBridgeReady', cb, false);
}

document.getElementById('aliBtn').addEventListener('click', () => {
  alipayReady(() => {
    ap.chooseImage({
      count: 1,
      sourceType: ['album', 'camera'],
      success: (res) => {
        console.log('支付寶選圖成功', res.localIds);
        // res.localIds 可用於預覽、上傳
      },
      fail: (err) => {
        console.error('支付寶選圖失敗', err);
      }
    });
  });
});
</script>

4. 關鍵說明

無簽章、無設定，即可直接使用；
僅圖片，影片需由 H5 發訊息給小程式原生 my.chooseVideo 處理。

五、抖音小程式 WebView H5 呼叫選擇圖片

1. 注意

無需簽章設定；
透過 tt.miniProgram 呼叫小程式原生能力；
僅支援圖片，不支援 H5 直接選取影片；
透過 UA 判斷是否在抖音小程式環境。

2. 接入方式

CDN 引入抖音 JS-SDK；
判斷抖音環境；
呼叫 tt.miniProgram.chooseImage。

3. 完整範例程式碼

html 體驗AI代碼助手 代碼解讀複製代碼<!-- 引入抖音JS-SDK -->
<script src="https://lf3-cn-beijing.volces.com/obj/open-platform/ttjsapi/ttjsapi-1.0.0.min.js"></script>
<button id="ttBtn">抖音選圖／拍照</button>
<script>
// 判斷是否在抖音小程式WebView
function isDouyinMiniProgram() {
  return navigator.userAgent.toLowerCase().includes('toutiaomicroapp');
}

document.getElementById('ttBtn').addEventListener('click', () => {
  if (!isDouyinMiniProgram()) {
    alert('請在抖音小程式內開啟');
    return;
  }

  tt.miniProgram.chooseImage({
    count: 1,
    sourceType: ['album', 'camera'],
    success: (res) => {
      console.log('抖音選圖成功', res.tempFilePaths);
      // 暫存路徑可用於預覽、上傳
    },
    fail: (err) => {
      console.error('抖音選圖失敗', err);
    }
  });
});
</script>

六、三端核心差異對照表

表格

平台是否需要後端簽章SDK 引入方式選圖 API直接支援影片額外要求微信小程式需要CDN/npmwx.chooseImage❌ 不支援公眾號 AppID + JSSDK 簽章支付寶小程式不需要CDNap.chooseImage❌ 不支援監聽 JSBridge 就緒抖音小程式不需要CDNtt.miniProgram.chooseImage❌ 不支援UA 判斷環境七、擴充：影片選擇統一方案（三端通用）

三端 H5 SDK均不支援直接選擇影片，統一方案：

H5 透過 postMessage 發送指令給小程式；
小程式原生呼叫對應影片 API：
- 微信：wx.chooseMedia
- 支付寶：my.chooseVideo
- 抖音：tt.chooseMedia
小程式拿到影片暫存路徑，上傳之後，再透過 postMessage 回傳給 H5；
H5 接收後預覽。