Integrasikan plugin Mega ke WeChat Mini Program Anda

Dokumen ini akan memandu Anda menyelesaikan integrasi plugin Mega dalam lingkungan Mini Program xr-frame.

Sebelum memulai

Rujuk panduan pengembangan xr-frame dan contoh resmi xr-frame untuk mempelajari cara menggunakan mesin XR-3D resmi WeChat, termasuk:
- Cara memasukkan komponen xr-frame ke halaman WeChat Mini Program biasa.
- Cara komunikasi antara komponen xr-frame dan komponen tradisional Mini Program.
- Cara mendapatkan atau membuat elemen dari scene dan mengubah sebagian properti seperti Transform.
- Memuat dan melepas resource, misalnya model GLTF.

Konfigurasi global

Tambahkan dependensi plugin Mega Mini Program ke file konfigurasi global app.json di direktori root Mini Program, lalu ubah dependency loading menjadi injeksi sesuai kebutuhan.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //gunakan versi plugin terbaru
      "provider": "wx27fa3b52b5462e8f" // id tetap plugin Mini Program Mega
    }
  }
}

Memuat plugin

Anda dapat memperkenalkan plugin melalui plugin interface, lalu langsung menggunakan sebagian metode plugin untuk memverifikasi apakah plugin sudah dimuat dengan benar.

Misalnya, setelah mendapatkan EasyARWechatMiniprogramPlugin melalui interface requirePlugin(string path) yang disediakan WeChat, gunakan metode isMegaTrackerSupported untuk menentukan apakah perangkat mendukungnya.

//jika file typings sudah diimpor
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//panggil isMegaTrackerSupported untuk menentukan apakah perangkat saat ini didukung; jika tidak, tampilkan prompt pop-up
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;
}

Dalam contoh ini, interface object yang diekspos plugin, yaitu easyarPlugin, pertama-tama diperoleh melalui interface requirePlugin(string path) yang disediakan WeChat. Setelah itu, metode isMegaTrackerSupported yang disediakan dipanggil untuk menentukan apakah lingkungan runtime saat ini tersedia. Jika tidak tersedia, dialog akan ditampilkan.

Memperkenalkan tipe

Disarankan menggunakan Typescript untuk pengembangan.

Path dalam project contoh: /typings/types/easyar/lib.easyar.d.ts.

Salin ke direktori yang sama dalam project Anda, lalu referensikan dengan triple-slash directive di /typings/types/index.d.ts:

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

Saat perlu menggunakan type object, Anda dapat memperoleh type system IMegaSystem dari plugin EasyAR Mega WeChat Mini Program melalui getMegaSystem.

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

Setelah itu, Anda dapat menggunakan tipe yang diekspos dalam IMegaSystem untuk perbandingan tipe. Misalnya, bandingkan state dengan mega.SessionState.Running untuk menentukan apakah session berhasil diinisialisasi:

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

Penyiapan scene xr-frame (WXML)

Dalam file WXML halaman, komponen xr-easyar-mega harus menjadi child node dari xr-scene dan mengikat id kamera serta tracker dengan benar. Jika id tidak diisi, komponen akan menggunakan komponen xr-camera dan xr-ar-tracker pertama yang ditemukan dalam scene.

<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>

Hati-Hati

planeMode pada ar-system harus diatur ke 1

Mendaftarkan event callback plugin 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>

Ikat event yang didistribusikan oleh proxy xr-frame Element di WXML. Untuk mekanisme distribusi event xr-frame, lihat mekanisme event xr-frame.

Event yang didistribusikan plugin adalah:

Nama event	Tipe parameter	Deskripsi
`SessionStateChange`	SessionState	Dipicu segera saat status Session berubah. Parameternya adalah status baru Session, digunakan untuk callback saat inisialisasi Session dimulai dan berhasil.
`MegaLocalizationResult`	MegaLocalizationResult	Dipicu setelah rendering frame yang menerima hasil localization Mega selesai diperbarui. Saat event dipicu, semua perubahan Transform yang dikontrol EasyAR dalam frame rendering tersebut sudah selesai.
`PostSessionUpdate`	Tanpa parameter	Dipicu segera setelah Session selesai diperbarui dalam frame rendering tersebut. Saat ini semua perubahan Transform yang dikontrol EasyAR dalam frame tersebut sudah selesai.

AR Session

Untuk pembuatan, startup, dan penghancuran session, lihat kontrol alur AR Session.

Gunakan callback event sessionStateChange untuk memastikan apakah inisialisasi berhasil. Ketika status berubah menjadi Running, ARSession dapat dianggap siap.

Di WXML, daftarkan fungsi onSessionStateChange() dalam komponen xr-frame sebagai callback event sessionStateChange melalui bind:sessionStateChange="onSessionStateChange":

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

Dalam fungsi callback onSessionStateChange() pada komponen xr-frame, bandingkan status session dengan setiap enum SessionState untuk menentukan status session saat ini.

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);
}

Dalam kode di atas, setelah inisialisasi selesai, console seharusnya mencetak "EasyAR Session initialized succeeded. Start running."

Table of Contents