如何将魔笔应用集成到 Web App 中_多端低代码开发平台魔笔(Mobi)-阿里云帮助中心

本文档介绍了如何利用魔笔提供的 Web SDK 将魔笔应用集成到 Web 应用中。

魔笔平台提供了 React、Vue 与 JavaScript 三种 Web SDK 集成方式，使开发者可以便捷地将魔笔应用集成到已有的 Web App 中。开发者可以根据已有应用的特点，任选其中一种集成方式。

登录访问

被集成应用，推荐参考下文使用 JWT 令牌鉴权，无法使用阿里云账号登录。

其他登录方式由于浏览器同源策略限制，在用户开启无痕访问的情况下可能会导致身份验证受限。

React SDK

安装

npm install @mobi-aliyun/runtime-embed-react

基本使用

import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL" />
    </div>
   )
}

export default App;

向魔笔应用注入动态数据

如果需要在宿主应用中共享一些数据给魔笔应用，可以采用如下方法：

参考宿主应用数据，在魔笔设计器中创建“宿主应用数据”。

在宿主应用中，向 SDK 传入对象类型的data属性，为key设置对应的值。

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
        data={{ sampleKey1: value}}
      />
    </div>
   )
}

export default App;

完成上述步骤后，每当宿主应用的value发生改变时，魔笔应用的globalHostAppData1.value都会同步改变。

向宿主应用发送消息

如果需要在魔笔应用中发送消息到宿主应用，可以采用如下方法：

在魔笔应用中，使用mobi.hostApp.postMessage构造消息。
1. mobi.hostApp.postMessage接收一个必选参数data，和一个可选参数origin，配置origin后，仅会向符合origin定义的目标发送消息。
2. mobi.hostApp.postMessage返回值类型为Promise<any>，可接收宿主应用messageHandler的返回值。

在宿主应用中，向 SDK 传递一个函数类型的messageHandler属性，接收一个任意类型的data，返回任意类型。

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
        data={{ sampleKey1: value}}
        messageHandler={(data) => {
          if(data.type === 'UPDATE_VALUE'){
            setValue(data.newValue);
          }
          return data.newValue;
        }}
      />
    </div>
   )
}

export default App;

静默登录

修改魔笔应用的登录配置为“JWT 令牌鉴权”

参考JWT 身份源，将获取到的auth_code、 refresh_token 和 expires_in 作为auth属性传入 SDK。

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';
const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
        data={{ sampleKey1: value}}
        messageHandler={(data) => {
          if(data.type === 'UPDATE_VALUE'){
            setValue(data.newValue);
          }
          return data.newValue;
        }}
        auth={{
          auth_code: 'xxxxx',
          refresh_token: 'xxxxx',
          expires_in: xxxxx
        }}
      />
    </div>
   )
}
export default App;

React SDK 属性参考

属性名	类型	描述
src	string	必填，被集成的魔笔应用的 URL。
data	object	可选，用于向魔笔应用分享数据，需要与魔笔应用内的“宿主应用数据”配合使用。
messageHandler	function	可选，用于接收魔笔应用发送的消息，需要与魔笔应用内的`mobi.hostApp.postMessage`配合使用。
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	可选，用于实现静默登录，需要自行获取 JWT 令牌，并在魔笔应用中启用“JWT 令牌鉴权”。
iframeOptions	{ sandbox?: string; allow?: string; }	可选，用于定制 iframe 的`sandbox`和`allow`属性，为保证魔笔应用可以正常运行，SDK 会默认注入两个`sandbox`属性：`allow-script`和`allow-same-origin`。
style	object	可选，用于定制 iframe 的样式。
customRouterHandler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	可选，作为魔笔 Copilot 应用内的功能路由回调，集成魔笔 Web 应用时，此配置项无效。

Vue SDK

安装

npm install @mobi-aliyun/runtime-embed-vue

基本使用

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
    />
  </div>
</template>

<style scoped></style>

向魔笔应用注入动态数据

参考宿主应用数据，在魔笔设计器中创建“宿主应用数据”。

在宿主应用中，向 SDK 传入对象类型的data属性，为key设置对应的值。

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
      :data="{ sampleKey1: value }"
    />
  </div>
</template>

<style scoped></style>

完成上述步骤后，每当宿主应用的value发生改变时，魔笔应用的globalHostAppData1.value都会同步改变。

向宿主应用发送消息

参考 React SDK，在魔笔应用中配置mobi.hostApp.postMessage。
在宿主应用中，向 SDK 传递一个函数类型的message-handler属性，接收一个任意类型的data，返回任意类型。

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
const messageHandler = (data) => {
  if (data.type === "UPDATE_VALUE") {
    value.value = data.newValue;
  }
  return data.newValue;
};
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
      :data="{ sampleKey1: value }"
      :message-handler="messageHandler"
    />
  </div>
</template>

<style scoped></style>

静默登录

参考 React SDK，在魔笔应用中配置“JWT 令牌鉴权”。
参考JWT 身份源，将获取到的auth_code、 refresh_token 和 expires_in 作为auth属性传入 SDK。

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
const messageHandler = (data) => {
  if (data.type === "UPDATE_VALUE") {
    value.value = data.newValue;
  }
  return data.newValue;
};
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
      :data="{ sampleKey1: value }"
      :message-handler="messageHandler"
      :auth="{
        auth_code: 'xxxxx',
        refresh_token: 'xxxxx',
        expires_in: xxxxx,
      }"
    />
  </div>
</template>

<style scoped></style>

Vue SDK 属性参考

属性名	类型	描述
src	string	必填，被集成的魔笔应用的 URL。
data	object	可选，用于向魔笔应用分享数据，需要与魔笔应用内的“宿主应用数据”配合使用。
message-handler	function	可选，用于接收魔笔应用发送的消息，需要与魔笔应用内的`mobi.hostApp.postMessage`配合使用。
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	可选，用于实现静默登录，需要自行获取 JWT 令牌，并在魔笔应用中启用“JWT 令牌鉴权”。
iframe-options	{ sandbox?: string; allow?: string; }	可选，用于定制 iframe 的`sandbox`和`allow`属性，为保证魔笔应用可以正常运行，SDK 会默认注入两个`sandbox`属性：`allow-script`和`allow-same-origin`。
style	object	可选，用于定制 iframe 的样式。
custom-router-handler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	可选，作为魔笔 Copilot 应用内的功能路由回调，集成魔笔 Web 应用时，此配置项无效。

JavaScript SDK

安装

npm install @mobi-aliyun/runtime-embed-javascript

基本使用

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      const mobiEmbed = createMobiEmbed({
        src: "形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL"
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

向魔笔应用注入动态数据

参考宿主应用数据，在魔笔设计器中创建“宿主应用数据”。
在宿主应用中，向 SDK 传入对象类型的data属性，为key设置对应的值。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      const mobiEmbed = createMobiEmbed({
        src: "形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL",
        data: { sampleKey1: "init" },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

通过修改 SDK 的data属性，实现数据的变化。

import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
const mobiEmbed = createMobiEmbed({
  src: "形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL",
  data: { sampleKey1: "init" },
});
setTimeout(() => {
  mobiEmbed.data = { sampleKey1: "updated" };
}, 5000);

向宿主应用发送消息

参考 React SDK，在魔笔应用中配置mobi.hostApp.postMessage。

在宿主应用中，向 SDK 传递一个函数类型的messageHandler属性，接收一个任意类型的data，返回任意类型。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      const mobiEmbed = createMobiEmbed({
        src: "形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL",
        data: { sampleKey1: "init" },
        messageHandler: (data) => {
          if (data.type === "UPDATE_VALUE") {
            mobiEmbed.data = { sampleKey1: data.newValue };
          }
          return data.newValue;
        },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

静默登录

参考 React SDK，在魔笔应用中配置“JWT 令牌鉴权”。
参考JWT 身份源，将获取到的auth_code、 refresh_token 和 expires_in 作为auth属性传入 SDK。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      const mobiEmbed = createMobiEmbed({
        src: "形如'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'的魔笔应用 URL",
        data: { sampleKey1: "init" },
        messageHandler: (data) => {
          if (data.type === "UPDATE_VALUE") {
            mobiEmbed.data = { sampleKey1: data.newValue };
          }
          return data.newValue;
        },
        auth: {
          auth_code: "xxxxx",
          refresh_token: "xxxxx",
          expires_in: xxxxx,
        },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

JavaScript SDK 属性参考

属性名	类型	描述
src	string	必填，被集成的魔笔应用的 URL。
data	object	可选，用于向魔笔应用分享数据，需要与魔笔应用内的“宿主应用数据”配合使用。
messageHandler	function	可选，用于接收魔笔应用发送的消息，需要与魔笔应用内的`mobi.hostApp.postMessage`配合使用。
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	可选，用于实现静默登录，需要自行获取 JWT 令牌，并在魔笔应用中启用“JWT 令牌鉴权”。
iframeOptions	{ sandbox?: string; allow?: string; }	可选，用于定制 iframe 的`sandbox`和`allow`属性，为保证魔笔应用可以正常运行，SDK 会默认注入两个`sandbox`属性：`allow-script`和`allow-same-origin`。
style	string	可选，用于定制 iframe 的样式。
customRouterHandler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	可选，作为魔笔 Copilot 应用内的功能路由回调，集成魔笔 Web 应用时，此配置项无效。