將 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