Подключение плагина Mega к вашей мини-программе WeChat

Этот документ проведет вас через процесс подключения плагина Mega в среде мини-программы xr-frame.

Перед началом

• Обратитесь к руководству по разработке xr-frame и официальным примерам xr-frame, чтобы изучить, как использовать движок XR-3D, предоставленный WeChat. Содержание включает:
  • Способ внедрения компонента xr-frame в обычные страницы мини-программы WeChat.
  • Способ взаимодействия компонента xr-frame с традиционными компонентами мини-программы.
  • Как получить или создать элемент из сцены и изменить некоторые свойства, такие как Transform.
  • Загрузку и освобождение ресурсов, например, моделей GLTF.

Глобальная конфигурация

Добавьте зависимость от плагина Mega для мини-программ в глобальном конфигурационном файле app.json в корневой директории мини-программы и измените загрузку зависимостей на внедрение по требованию.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //используйте последнюю версию плагина
      "provider": "wx27fa3b52b5462e8f" // фиксированный id плагина Mega для мини-программ
    }
  }
}

Загрузка плагина

Вы можете импортировать плагин через интерфейс плагина и использовать некоторые его методы для проверки правильности загрузки плагина.

Например, получив EasyARWechatMiniprogramPlugin через интерфейс requirePlugin(string path), предоставляемый WeChat, используйте его метод 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. Обратитесь к официальной документации WeChat: 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) WeChat получается easyarPlugin — объект интерфейса, предоставляемого плагином. Затем вызывается его метод isMegaTrackerSupported для проверки доступности в текущей среде выполнения. Если недоступен, выводится предупреждение.

Импорт типов

Рекомендуется использовать Typescript для разработки.

Путь в демонстрационном проекте: /typings/types/easyar/lib.easyar.d.ts.

Скопируйте в аналогичный путь вашего проекта и добавьте ссылку через директиву с тремя слешами в /typings/types/index.d.ts:

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

Когда требуется использовать объекты типов, вы можете получить систему типов плагина EasyAR Mega для мини-программ WeChat IMegaSystem через метод getMegaSystem.

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

Затем вы можете использовать типы, предоставляемые IMegaSystem, для сравнения типов. Например, можно сравнить state с mega.SessionState.Running, чтобы определить, успешно ли инициализирована сессия:

const newState: easyar.SessionState = event.detail.value;
if (newState === mega.SessionState.Running) {
    console.log("Сессия EasyAR успешно инициализирована. Начало работы.");
}

Создание сцены 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>

Осторожно

planeMode в ar-system должен быть установлен в 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. Механизм распространения событий в xr-frame описан в механизме событий xr-frame

Плагин распространяет следующие события:

Название события	Тип параметра	Описание
SessionStateChange	SessionState	Срабатывает немедленно при изменении состояния Сессии. Параметр — новое состояние Сессии. Используется для обработки обратных вызовов начала и успешного завершения инициализации Сессии.
MegaLocalizationResult	MegaLocalizationResult	Срабатывает после завершения обновления кадра рендеринга, в котором получен результат локализации Mega. При срабатывании события все изменения Transform, управляемые EasyAR в этом кадре рендеринга, уже завершены.
PostSessionUpdate	Без параметров	Срабатывает немедленно после завершения обновления Сессии в этом кадре рендеринга. На этот момент все изменения Transform, управляемые EasyAR в кадре, уже завершены.

AR Сессия

Создание, запуск и завершение сессии описаны в разделе Управление процессом AR Сессии

Убедитесь в успешности инициализации через обратный вызов события sessionStateChange. Когда состояние становится Running, можно считать, что ARSession готова.

В WXML зарегистрируйте функцию onSessionStateChange() компонента xr-frame как обратный вызов события sessionStateChange с помощью bind:sessionStateChange="onSessionStateChange":

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

В функции обратного вызова onSessionStateChange() компонента xr-frame сравните состояние сессии с перечислениями SessionState, чтобы определить текущее состояние сессии.

onSessionStateChange(event) {
    const newState: easyar.SessionState = event.detail.value;
    console.log(`Состояние сессии EasyAR изменилось на: ${mega.SessionState[newState]}`);
    let displayInfoStr: string = "";
    if (newState === mega.SessionState.None) {
        displayInfoStr = "Сессия EasyAR неактивна.";
    } else if (newState === mega.SessionState.Initializing) {
        displayInfoStr = "Идет инициализация сессии EasyAR...";
    } else if (newState === mega.SessionState.Running) {
        displayInfoStr = "Сессия EasyAR успешно инициализирована. Начало работы.";
    }
    this.triggerEvent("sessionDisplayInfoEvent", displayInfoStr);
}

В приведенном коде после завершения инициализации в консоли должно быть напечатано: "Сессия EasyAR успешно инициализирована. Начало работы."

Связанные темы

• Полный рабочий пример проекта
• Управление процессом AR Сессии
• Описание демонстрационного проекта