工程配置¶

EasyAR插件基于微信小程序及其3D引擎 XR-Frame 运行，请在使用前确保 您已熟悉3D引擎基本知识和小程序本身的开发流程 。

如果您对于微信小程序的基本开发流程还不了解，请先查看微信小程序开发文档。

如果您对微信小程序的3D引擎 XR-Frame 还不了解，请先查看微信小程序XR-Frame文档。

微信小程序全局配置中添加插件引用¶

在app.json中添加插件配置

"lazyCodeLoading": "requiredComponents",
"plugins": {
    "easyar-wechat-miniprogram": {
        "version": "2.0.0",
        "provider": "wx27fa3b52b5462e8f"
    }
}

使用插件提供的类型¶

EasyAR Mega 微信小程序插件为 TypeScript 提供了类型定义文件

Sample工程中的路径: /typings/types/easyar/lib.easyar.d.ts 。

拷贝到工程相同目录，并在 /typings/types/index.d.ts 中以三斜杠指令引用：

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

当需要使用类型对象时，可以通过插件接口获取EasyAR Mega 微信小程序插件的类型系统

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

之后可以使用mega中的类型进行比较，例如:

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

云服务API认证¶

使用EasyAR插件创建MegaTracker时支持传入APIToken/APIKey+Secret两种方式进行云服务API认证。

关于如何获取APIToken，请见获取security token

使用APIToken创建Session, 并定期更新:

const mega: easyar.IMegaSystem = easyarPlugin.getMegaSystem();
const megaElement = scene.getElementById('easyar-mega');
const megaComponent = megaElement.getComponent("easyar-mega") as easyar.EasyARMegaComponent;

const tokenAccess = new mega.TokenAccessData(
    settings.MegaTrackerAppID,
    settings.MegaTrackerServerAddress,
    apiToken
);
const megaTrackerConfigs: easyar.MegaTrackerConfigs = {
    access: tokenAccess
};
const sessionConfigs: easyar.SessionConfigs = {
    megaTrackerConfigs: megaTrackerConfigs,
    licenseKey: settings.EasyARLicenseKey
};
session = megaComponent.createSession(sessionConfigs);

...
//当Token过期后通过MegaTracker的updateToken更新
session.megaTracker.updateToken(newToken);

使用APIKey和APISecret创建MegaTracker:

const apiKeyAccess = new mega.APIKeyAccessData(
    settings.MegaTrackerAppID,
    settings.MegaTrackerServerAddress,
    settings.EasyARAPIKey,
    settings.EasyARAPISecret
);
const megaTrackerConfigs: easyar.MegaTrackerConfigs = {
    access: apiKeyAccess
};
const sessionConfigs: easyar.SessionConfigs = {
    megaTrackerConfigs: megaTrackerConfigs,
    licenseKey: settings.EasyARLicenseKey
};
session = megaComponent.createSession(sessionConfigs);

确保正确的场景设置¶

由于插件需要使用小程序提供的AR系统相关功能，请确保正确的场景设置，否则将可能影响xr-frame引擎的运行以及插件的使用。

<xr-scene id="xr-scene" ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">
    <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>

备注

plane mode必须设置为1

WXML中添加EasyAR-Mega标签¶

在你需要使用Mega服务的wxml文件中添加，属性说明请查看 API参考手册。

<xr-easyar-mega
    id="easyar-mega"
    camera-id="xrCamera"
    ar-tracker-id="xrARTracker"
></xr-easyar-mega>

xr-easyar-session 标签作为 XR-Frame 场景中的一个 Element ，必须添加到 xr-scene 标签的下面。

将前面配置的 xr-camera 和 xr-ar-tracker 的id分别设置到 xr-easyar-session 上的 camera-id 和 ar-tracker-id 。

若不填写id则EasyARSession会使用在场景中第一个查找到的 xr-camera 和 xr-ar-tracker 组件。

属性说明请参考 EasyARSessionDataMapping

WXML中绑定插件事件¶

<xr-easyar-mega
    id="easyar-mega"
    camera-id="xrCamera"
    ar-tracker-id="xrARTracker"
    bind:sessionStateChange="displaySessionInfo"
    bind:megaLocalizationResult="displayLocalizationResult"
    bind:postSessionUpdate="displayPerRenderframeInfo"
></xr-easyar-mega>

在wxml中绑定XRFrame Element代理分发的事件，XRFrame的事件分发机制请参考 XRFrame事件机制。

插件触发的事件 SessionEvent 。

SessionStateChange事件

参数类型:

easyar.SessionState
说明:

Session状态改变时立即触发，参数为Session新的状态，用于处理Session初始化开始与初始化成功的回调。

MegaLocalizationResult

参数类型:

easyar.MegaLocalizationResult
说明:

Mega定位结果返回时立即触发，参数为Mega定位结果信息。

PostSessionUpdate

参数类型:

无参数
说明:

Session在该渲染帧完成更新后立即触发，该事件触发时，该帧内所有受EasyAR控制的transform变化已经完成。

实现事件回调¶

事件的handler被定义在组件的method内

/** 用于打印Session初始化状态的回调 */
displaySessionInfo(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("sessionInfoEvent", displayInfoStr);
},
// 用于打印定位结果信息的回调
displayLocalizationResult(event) {
    let res: easyar.MegaLocalizationResult = event.detail.value;
    console.log(`Mega localization result status is: ${mega.MegaLocalizerStatus[res.status]}`);
}