Integrar o plugin Mega ao seu WeChat Mini Program

Este documento orienta você a concluir a integração do plugin Mega no ambiente de Mini Program com xr-frame.

Antes de começar

• Consulte o guia de desenvolvimento do xr-frame e os exemplos oficiais do xr-frame para aprender a usar o mecanismo XR-3D oficial fornecido pelo WeChat, incluindo:
  • a forma de introduzir o componente xr-frame em uma página comum do WeChat Mini Program;
  • a comunicação entre o componente xr-frame e os componentes tradicionais do Mini Program;
  • como obter ou criar um elemento da scene e modificar algumas propriedades, como Transform;
  • carregar e liberar resources, por exemplo modelos GLTF.

Configuração global

Adicione a dependência do plugin Mega Mini Program ao arquivo de configuração global app.json no diretório raiz do Mini Program e altere o dependency loading para injeção sob demanda.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //use a versao mais recente do plugin
      "provider": "wx27fa3b52b5462e8f" // id fixo do plugin de Mini Program Mega
    }
  }
}

Carregar o plugin

Você pode introduzir o plugin pela plugin interface e usar diretamente alguns métodos do plugin para verificar se ele foi carregado corretamente.

Por exemplo, depois de obter EasyARWechatMiniprogramPlugin por meio da interface requirePlugin(string path) fornecida pelo WeChat, use o método isMegaTrackerSupported para determinar se o dispositivo é compatível.

//se o arquivo typings ja tiver sido importado
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//chame isMegaTrackerSupported para determinar se o dispositivo atual e compativel; se nao for, mostre um aviso 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;
}

Neste exemplo, primeiro é obtido easyarPlugin, isto é, o objeto de interface exposto pelo plugin, por meio da interface requirePlugin(string path) fornecida pelo WeChat. Em seguida, é chamado o método isMegaTrackerSupported fornecido por ele para determinar se o ambiente de execução atual está disponível. Se não estiver disponível, uma janela modal será exibida.

Introduzir tipos

Recomenda-se usar Typescript para desenvolvimento.

Caminho no projeto de exemplo: /typings/types/easyar/lib.easyar.d.ts.

Copie para o mesmo diretório do projeto e referencie em /typings/types/index.d.ts com uma diretiva triple-slash:

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

Quando for necessário usar type objects, você pode obter o type system IMegaSystem do plugin EasyAR Mega WeChat Mini Program por meio de getMegaSystem.

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

Depois, é possível usar os tipos expostos em IMegaSystem para comparações de tipo. Por exemplo, compare state com mega.SessionState.Running para determinar se a session foi inicializada com sucesso:

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

Configuração da scene xr-frame (WXML)

No arquivo WXML da página, o componente xr-easyar-mega deve ser um child node de xr-scene e deve vincular corretamente os id da câmera e do tracker. Se o id não for preenchido, o componente usará os primeiros componentes xr-camera e xr-ar-tracker encontrados na 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>

Cuidado

O planeMode de ar-system deve ser definido como 1

Registrar callbacks de evento do 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> 

No WXML, vincule os eventos distribuídos pelo proxy xr-frame Element. Para o mecanismo de distribuição de eventos do xr-frame, consulte o mecanismo de eventos do xr-frame.

Os eventos distribuídos pelo plugin são:

Nome do evento	Tipo de parâmetro	Descrição
SessionStateChange	SessionState	Acionado imediatamente quando o estado da Session muda. O parâmetro é o novo estado da Session, usado para processar os callbacks de início e sucesso da inicialização da Session.
MegaLocalizationResult	MegaLocalizationResult	Acionado depois que o frame de rendering que recebeu o resultado de Mega localization termina de atualizar. Quando o evento é acionado, todas as alterações de Transform controladas pela EasyAR nesse frame de rendering já foram concluídas.
PostSessionUpdate	Sem parâmetros	Acionado imediatamente depois que a Session termina de atualizar nesse frame de rendering. Nesse momento, todas as alterações de Transform controladas pela EasyAR nesse frame já foram concluídas.

AR Session

Para criação, inicialização e destruição da session, consulte controle de fluxo de AR Session.

Confirme se a inicialização foi bem-sucedida por meio do callback do evento sessionStateChange. Quando o estado muda para Running, a ARSession pode ser considerada pronta.

No WXML, registre a função onSessionStateChange() no componente xr-frame como callback do evento sessionStateChange por meio de bind:sessionStateChange="onSessionStateChange":

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

Na função callback onSessionStateChange() do componente xr-frame, compare o estado da session com cada enum de SessionState para determinar o estado atual da 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);
}

No código acima, após a conclusão da inicialização, o console deve imprimir "EasyAR Session initialized succeeded. Start running."

Tópicos relacionados

• Projeto de exemplo completo executável
• Controle de fluxo de AR Session
• Descrição do projeto de exemplo