淘宝开放平台

登录
文档中心 > 基础技术

基础技术

前端SDK使用

更新时间：2024/06/13 访问次数：8384

想要使用官方提供的组件能力之前一定要引入官方提供的前端cdn资源。

SDK CDN 引入

https://o.alicdn.com/merchant-modular-open/modular-open-sdk/dist/index.umd.es5.production.js

https://o.alicdn.com/merchant-modular-open/modular-open-sdk/dist/index.umd.es5.production.css


引入 CDN 资源示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport"
      content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
    <!-- 这里是 CDN 引入的代码，包含 js 和 css，都需要引入 -->
    <script src="https://o.alicdn.com/merchant-modular-open/modular-open-sdk/dist/index.umd.es5.production.js"></script>
    <link href="https://o.alicdn.com/merchant-modular-open/modular-open-sdk/dist/index.umd.es5.production.css" rel="stylesheet" />         
    <!-- 这里是 CDN 引入的代码，包含 js 和 css，都需要引入 -->         
  </head>
  <body>
    <div>your html element</div>
  </body>
</html>

SDK 使用

在引入 CDN 资源完成后，你会发现全局（window）多了一个 taobaoModularOpen变量。组件开放的所有能力都挂载在这个taobaoModularOpen变量上。

注意：该 sdk 使用 umd 格式打包，这意味着如果在 sdk cdn 引入之前，存在 AMD 的加载器，则会使用 AMD 加载器进行加载模块，此时模块不会被加载到 window上，需要自行在 AMD 加载器中进行处理。

初始化 SDK

使用

taobaoModularOpen.create

作用

初始化方法。

该方法只需要调用一次，通过该方法可以获取一个 sdk 实例，可以保存该实例到内存中，方便后续使用。

方法签名

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
interface TaobaoModularOpenCreate {
  (options: TaobaoModularOpenOptions): Promise<{ open: () => Promise<void> }>;
}
 
interface TaobaoModularOpenOptions {
  appKey: string;
 
  // 用来获取 secToken, 需要从接入的前端发起请求, 发送给自己应用的服务端, 服务端再发起请求到 TOP, 请求的响应数据也要回传回来
  // top method: "taobao.top.sec.token.get"
  getSecToken: GetSecToken;
 
  // 用来获取 clientToken, 需要从接入的前端发起请求, 发送给自己应用的服务端, 服务端再发起请求到 TOP, 请求的响应数据也要回传回来
  // top method: "taobao.top.client.token.get"
  getClientToken: GetClientToken;
}
 
export type GetSecToken = (args: {
  oeid: string;
  ieid: string;
}) => Promise<{
  token: string;
openId: string;
}>;
 
export interface GetClientToken {
  (args: {
    oeid: string;
    ieid: string;
    secToken: string;
  }): Promise<string>;
}

入参

参数名

是否必传

参数描述

appKey

是

应用的 appKey

getClientToken

是

用来获取 top 提供的 client_token

getSecToken

是

用来获取 top 提供的 sec_token

返回值

字段名

字段类型

字段描述

open

Function

打开组件的方法

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const taobaoModularOpenInst = await window.taobaoModularOpen.create({
  appKey: "your-appKey",
  getClientToken: async ({ oeid, ieid }) => {
    console.log("获取到参数", oeid, ieid);
    // 注意这里要向自己的服务端发送请求, 服务端则需要向 TOP 发送请求, method: "taobao.top.client.token.get"
    const response = await requestFromServer({ oeid, ieid });
 
    return response.token;
  },
  getSecToken: async ({ oeid, ieid, secToken }) => {
    console.log("获取到参数", oeid, ieid, secToken);
    // 注意这里要向自己的服务端发送请求, 服务端则需要向 TOP 发送请求, method: "taobao.top.sec.token.get"
    const response = await requestFromServer({ secToken });
 
    return {
      token: response.token,
      openId: response.openId,
    };
  },
});

SDK 实例使用

open

作用

用于打开一个平台能力。

方法签名

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
type open = (opt: {
  // 平台能力名称, 视具体的能力而定
  name: string;
  // 打开能力时需要携带的参数, 视具体的能力而定
  data: Record<string, any>;
  // 平台能力的交互类型
  // - Hover: 以 hover 的状态悬浮在提供的目标元素上
  // - Target: 渲染到提供的元素内部
  // - Drawer: 在右侧打开一个抽屉进行渲染
  interactionType: "Hover" | "Target" | "Drawer";
  // 要渲染的目标元素, 当 interactionType 为 Drawer 时，传递 document.body 即可。
  target: HTMLElement;
  // 能力渲染时的一些 UI 设置，比如宽、高。视具体的情况而定，调整到最适配、用户体验最佳即可。
  containerConfig: {
    width: string; // 比如 "355px"
    height: string; // 比如 "150px"
  }
}) => Promise<{
  // 用来接受能力组件的事件。具体事件名以及作用视具体接入的能力而定
  registerAction: (event: string; callback: (args: any) => void) => void;
}>

入参

参数名

描述

示例

name

能力组件名称，每个能力唯一

"commodity-quality-score"

data

传递给能力组件的参数

{ itemid: "123456" }

interactionType

组件交互类型，三种

— Hover hover 在元素上

— Target 渲染在元素内部

— Drawer 抽屉打开

"Drawer"

target

目标元素，Hover 和 Target 传入对应的元素即可，Drawer 传 document.body 即可

document.body

containerConfig

能力组件的 UI 设置，包含宽高设置，可以根据自己应用情况进行调整

{ width: "360px", height: "200px" }

返回值

字段名

描述

示例

registerAction

用来注册能力组件的事件回调
1
2
3
registerAction("issueClick", (arg) => {
  console.log("接收到事件", arg);
})

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const { registerAction } = await taobaoModularOpenInst.open({
  name: "commodity-quality-score",
  interactionType: "Drawer",
  target: document.body,
  data: {
    itemId: "123456"
  },
  containerConfig: {
    width: "300px",
    height: "200px"
  }
});
 
registerAction("issueClick", (arg) => {
  console.log("接收到能力组件的事件", arg);
})

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部