Integrare il plugin Mega nel proprio WeChat Mini Program

Questo documento guida l'utente nel completare l'integrazione del plugin Mega nell'ambiente Mini Program basato su xr-frame.

Prima di iniziare

• Consultare la guida allo sviluppo xr-frame e gli esempi ufficiali di xr-frame per imparare a usare il motore XR-3D ufficiale di WeChat, inclusi:
  • il modo di introdurre il componente xr-frame in una normale pagina WeChat Mini Program;
  • la comunicazione tra il componente xr-frame e i componenti tradizionali del Mini Program;
  • come ottenere o creare un elemento dalla scene e modificarne alcune proprietà, ad esempio Transform;
  • il caricamento e il rilascio di resource, come i modelli GLTF.

Configurazione globale

Aggiungere la dipendenza dal plugin Mega Mini Program nel file di configurazione globale app.json nella directory root del Mini Program e cambiare il dependency loading in iniezione on demand.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //usa la versione piu recente del plugin
      "provider": "wx27fa3b52b5462e8f" // id fisso del plugin Mini Program Mega
    }
  }
}

Caricare il plugin

È possibile introdurre il plugin tramite la plugin interface e usare direttamente alcuni metodi del plugin per verificare che sia stato caricato correttamente.

Ad esempio, dopo aver ottenuto EasyARWechatMiniprogramPlugin tramite l'interface requirePlugin(string path) fornita da WeChat, usare il metodo isMegaTrackerSupported per determinare se il dispositivo è supportato.

//se il file typings e gia stato importato
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//chiama isMegaTrackerSupported per determinare se il dispositivo corrente e supportato; in caso contrario mostra un popup
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;
}

In questo esempio, tramite l'interface requirePlugin(string path) fornita da WeChat viene prima ottenuto easyarPlugin, cioè l'interface object esposto dal plugin. Successivamente viene chiamato il metodo isMegaTrackerSupported fornito per determinare se l'ambiente runtime corrente è disponibile. Se non è disponibile, viene mostrata una finestra modale.

Introdurre i tipi

Per lo sviluppo si consiglia di usare Typescript.

Percorso nel progetto di esempio: /typings/types/easyar/lib.easyar.d.ts.

Copiarlo nella stessa directory del progetto e referenziarlo in /typings/types/index.d.ts con una direttiva triple-slash:

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

Quando è necessario usare type object, è possibile ottenere il type system IMegaSystem del plugin EasyAR Mega WeChat Mini Program tramite getMegaSystem.

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

In seguito si possono usare i tipi esposti in IMegaSystem per i confronti di tipo. Ad esempio, è possibile confrontare state con mega.SessionState.Running per determinare se la session è stata inizializzata correttamente:

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

Configurazione della scene xr-frame (WXML)

Nel file WXML della pagina, il componente xr-easyar-mega deve essere un child node di xr-scene e deve associare correttamente gli id della camera e del tracker. Se id non viene compilato, il componente userà i primi componenti xr-camera e xr-ar-tracker trovati nella 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>

Attenzione

Il planeMode di ar-system deve essere impostato su 1

Registrare gli event callback del 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> 

Nel WXML associare gli event distribuiti dal proxy xr-frame Element. Per il meccanismo di distribuzione degli event di xr-frame, consultare il meccanismo event di xr-frame.

Gli event distribuiti dal plugin sono:

Nome event	Tipo parametro	Descrizione
SessionStateChange	SessionState	Attivato immediatamente quando lo stato della Session cambia. Il parametro è il nuovo stato della Session e viene usato per gestire i callback di inizio e successo dell'inizializzazione della Session.
MegaLocalizationResult	MegaLocalizationResult	Attivato dopo che il rendering frame che ha ricevuto il risultato di Mega localization ha completato l'aggiornamento. Quando l'event viene attivato, tutte le modifiche Transform controllate da EasyAR in quel rendering frame sono già completate.
PostSessionUpdate	Nessun parametro	Attivato subito dopo che la Session ha completato l'aggiornamento in quel rendering frame. In questo momento tutte le modifiche Transform controllate da EasyAR nel frame sono già completate.

AR Session

Per creazione, avvio e distruzione della session, vedere controllo del flusso AR Session.

Usare il callback dell'event sessionStateChange per confermare se l'inizializzazione è riuscita. Quando lo stato diventa Running, ARSession può essere considerata pronta.

Nel WXML, registrare la funzione onSessionStateChange() nel componente xr-frame come callback dell'event sessionStateChange tramite bind:sessionStateChange="onSessionStateChange":

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

Nella funzione callback onSessionStateChange() del componente xr-frame, confrontare lo stato della session con i vari enum di SessionState per determinare lo stato corrente della 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);
}

Nel codice sopra, dopo il completamento dell'inizializzazione, la console dovrebbe stampare "EasyAR Session initialized succeeded. Start running."

Argomenti correlati

• Progetto di esempio completo eseguibile
• Controllo del flusso AR Session
• Descrizione del progetto di esempio