將 mega 插件接入您的微信小程序

本文檔將帶您完成 mega 插件在 xr-frame 小程序環境下的接入。

開始之前

參考 xr-frame 開發指南及 xr-frame 官方樣例學習如何使用微信官方提供的 XR-3D 引擎，內容包括：
- 常規微信小程序頁面中引入 xr-frame 元件的方式。
- xr-frame 元件與小程序傳統元件的通訊方式。
- 如何從場景中獲取或建立一個元素並修改部分屬性比如 Transform。
- 載入和釋放資源，例如 GLTF 模型。

全域配置

在小程序根目錄下的 app.json 全域配置檔案中新增對 mega 小程序插件的依賴，並將依賴載入改為按需注入。

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //使用最新的插件版本
      "provider": "wx27fa3b52b5462e8f" // mega 小程序插件固定 id
    }
  }
}

載入插件

您可以透過插件介面引入插件，直接使用插件的部分方法以驗證插件是否已經被正確載入。

例如使用透過微信提供的 requirePlugin(string path) 介面拿到 EasyARWechatMiniprogramPlugin 後，使用它的 isMegaTrackerSupported 方法判斷裝置是否支援。

//如果已經引入了 typings 檔案
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//呼叫 isMegaTrackerSupported 判斷當前裝置是否支援，若不支援則彈窗提示
if (!easyarPlugin.isMegaTrackerSupported()) {
    const message = `當前裝置不支援 VK v1 和 v2，請參考微信官方文件：https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/visionkit/plane.html`;
    wx.showModal({
        title: "裝置不支援",
        content: message,
        showCancel: false,
    });
    console.error(message);
    return;
}

這個例子中首先透過微信提供的 requirePlugin(string path) 介面拿到了 easyarPlugin 即插件暴露的介面物件，之後呼叫了其提供的 isMegaTrackerSupported 方法判斷當前執行環境下是否可用。若不可用則彈窗提示。

引入型別

建議使用 Typescript 進行開發。

樣例工程中的路徑：/typings/types/easyar/lib.easyar.d.ts 。

拷貝到工程相同目錄，並在 /typings/types/index.d.ts 中以三斜線指令引用：

/// <reference path="./easyar/lib.easyar.d.ts" />

當需要使用型別物件時，可以透過 getMegaSystem 獲取 easyar mega 微信小程序插件的型別系統 IMegaSystem。

const mega: easyar.IMegaSystem = easyarPlugin.getMegaSystem();

之後可以使用 IMegaSystem 中暴露的型別進行型別比較，例如可以用 state 比較與 mega.SessionState.Running 是否相等判斷 session 是否初始化成功：

const newState: easyar.SessionState = event.detail.value;
if (newState === mega.SessionState.Running) {
    console.log("easyar session initialized succeeded. start running.");
}

xr-frame 場景搭建（wxml）

在頁面的 wxml 檔案中，xr-easyar-mega 元件必須作為 xr-scene 的子節點，並正確繫結相機與追蹤器的 id ，若不填寫 id 則元件會使用在場景中第一個查找到的 xr-camera 和 xr-ar-tracker 元件。

<xr-scene id="xr-scene" ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">
    <xr-easyar-mega
        id="easyar-mega"
        camera-id="xrCamera"
        ar-tracker-id="xrARTracker"
    ></xr-easyar-mega>
    <xr-node>
        <xr-ar-tracker id="xrARTracker" mode="Plane"></xr-ar-tracker>
        <xr-camera id="xrCamera" node-id="xrCamera" clear-color="0.925 0.925 0.925 1" background="ar" is-ar-camera></xr-camera>
    </xr-node>
    <xr-shadow id="shadow-root" node-id="xrShadow"></xr-shadow>
</xr-scene>

注意

ar-system 的 planeMode 必須設定為 1

註冊 mega 插件的事件回呼

<xr-easyar-mega
    id="easyar-mega"
    camera-id="xrCamera"
    ar-tracker-id="xrARTracker"
    bind:sessionStateChange="onSessionStateChange"
    bind:megaLocalizationResult="onMegaLocalizationResult"
    bind:postSessionUpdate="onPostSessionUpdate"
></xr-easyar-mega>

在 wxml 中繫結 xr-frame element 代理分發的事件，xr-frame 的事件分發機制請參考 xr-frame 事件機制

插件分發的事件有：

事件名稱	參數型別	說明
`sessionStateChange`	SessionState	session 狀態改變時立即觸發。參數為 session 新的狀態，用於處理 session 初始化開始與成功的回呼。
`megaLocalizationResult`	MegaLocalizationResult	收到 mega 定位結果的渲染幀完成更新後觸發。事件觸發時，該渲染幀內所有受 easyar 控制的 transform 變化已經完成。
`postSessionUpdate`	無參數	session 在該渲染幀完成更新後立即觸發。此時該幀內所有受 easyar 控制的 transform 變化已經完成。

ar session

session 的建立，啟動及銷燬請見 ar session 流程控制

透過 sessionStateChange 事件回呼確認初始化是否成功。當狀態變為 Running 時，即可認為 arsession 已就緒。

在 wxml 中透過 bind:sessionStateChange="onSessionStateChange" 將 xr-frame 元件中的 onSessionStateChange() 函式註冊為 sessionStateChange 事件的回呼：

<xr-easyar-mega
    bind:sessionStateChange="onSessionStateChange"
></xr-easyar-mega>

在 xr-frame 元件中的回呼函式 onSessionStateChange() 中將 session 狀態與 SessionState 的各個列舉進行比較可判斷 session 當前狀態。

onSessionStateChange(event) {
    const newState: easyar.SessionState = event.detail.value;
    console.log(`easyar session state changed to: ${mega.SessionState[newState]}`);
    let displayInfoStr: string = "";
    if (newState === mega.SessionState.None) {
        displayInfoStr = "easyar session is inactive.";
    } else if (newState === mega.SessionState.Initializing) {
        displayInfoStr = "easyar session is initializing...";
    } else if (newState === mega.SessionState.Running) {
        displayInfoStr = "easyar session initialized succeeded. start running.";
    }
    this.triggerEvent("sessionDisplayInfoEvent", displayInfoStr);
}

上述程式碼中，初始化完成後控制檯應列印 "easyar session initialized succeeded. start running."

Table of Contents