DTV SDK 文档

⚠️ DTV SDK 已经迁移到 @envision-digital/dtv-sdk，请前往新页面获取最新版本信息。

描述

利用此SDK可以在宿主页面和DTV创建的页面之间构建通信通道，提供比如

• 切换显示模式
• 添加删除Widget
• 修改个人信息等

安装

使用 yarn

yarn add enos-dtv-sdk

使用 npm

npm install enos-dtv-sdk

引用

import DTVPage from 'enos-dtv-sdk'

Usage

初始化页面实例

创建页面实例

const instance = new DTVPage(pageId: string, targetWindow: Window);

参数

• pageId: 对应渲染页面的id，识别和校验数据(安全考虑)
• targetWindow: 渲染了DTV页面的window实例，用来定位页面

class interface

详情见最后

接口

实例对象暴露的接口列表

subscribeActions

注册page页面的事件接收

示例

instance.subscribeActions({ onWidgetEdit,  onWidgetDelete,  onWidgetSave,  onWidgetCancel,  onPageChage})

参数

• onWidgetEdit 当用户点击某个widget开始编辑时调用
  • widgeId: 编辑的widget的id
  • link： 编辑的渲染页面URL
• onWidgetDelete 当用户点击某个widget，想要移除widget时调用
  • widgetId: 想要删除Widget的Id
• onWidgetSave 当某个用户进入widget编辑态， 保存编辑时调用
  • widgetId：这次保存的widget的id
  • status: 这次保存的状态，成功或者失败
• onWidgetCancel 当某个用户进入widget编辑态，取消编辑时调用
  • widgetId: 取消编辑的widget的Id
• onPageChage 当用户修改了页面的profile(改变了filter，改变了背景等)是调用
  • profile: 记录一些用户行为对于页面的改变

声明

type PageProfile = {    
    filters: any[];
}

type onWidgetEditFn = (widgetId: string, link: string) => void; 
type onWidgetDeleteFn = (widgetId：stirng) => void;
type onWidgetSaveFn = (widgetId, status: status) => void;
type onWidgetCancelFn= (widgetId： string) => void;
type onPageChangeFn = (profile: PageProfile) => void;

返回

无返回

switchToEdit

进入编辑模式

示例

instance.switchToEdit(): Promise<FunctionReturn>

参数

无

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

switchToDisplay

回到只读模式

示例

instance.switchToDisplay(): Promise<FunctionReturn>

参数

无

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

getBusinessWidgets

获取可选的业务组件模板

示例

instance.getBusinessWidgets(): Promise<BusinessWidgetsReturn>

参数

无

返回

• code: -1 | 1; 标记请求成功或者失败
• message: string； 如果成功则为空，如果失败，会有失败的message
• data: 返回的数据，格式如下

type BusinessWidgetTemplate = {   
    name: string;    
    id: string;    
    tags: string[];    
    thumbnail: string; // a url
}

interface BusinessWidgetsReturn extends FunctionReturn {    
    data: BusinessWidgetTemplate[] | [];
}

addWidgetFromTemplate

添加 business widget到当前 page

示例

instance.addWidgetFromTemplate(templateId: string): Promise<FunctionReturn>

参数

• templateId: 需要添加的business widget Id

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

refreshWidget

重新渲染page中的某个widget，一般需要在widget修改之后调用

示例

instance.refreshWidget(widgetId：string): Promise<FunctionReturn>

参数

• widgetId： 需要刷新的widget的ID

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

refreshPage

重新渲染整个页面，一般在保存之后，可能需要调用

示例

instance.refreshPage(): Promise<FunctionReturn>

参数

无

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

saveLayout

保存布局修改

示例

instance.saveLayout(isSaveNew: boolean): Promise<FunctionReturn>

参数

• isSaveNew: 是否保存为新页面

返回

Promise<FunctionReturn>

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

enum status {   
    success = 1,  
    error = -1
}

changePage

修改页面展示的内容，页面ID

示例

instance.changePage({
    id: 'new-page-id',
    filters: {
        test: 'app-portal'
    }
});

参数

export type PageChangeParams = {
    id: string;
    filters: {
        [key: string]: string;
    };
}

changeFilter

改变页面filter

示例

instance.changeFilter({test: 'apim-web'});

参数

type filters = {
    [key:string]: string
}

deleteWidget

删除组件

示例

instance.deleteWidget(widgetId: string, widgetType?: string): Promise<FunctionReturn>

参数

• widgetId: 组件id
• widgetType: 组件类型

cancelEdit

退出编辑态

示例

instance.cancelEdit(): Promise<FunctionReturn>

参数

无

on

绑定通用事件处理函数

示例

instance.on(eventType: EventType, handler: EventHandler)

参数

• eventType: 事件类型
• handler: 事件处理函数

type EventType = 'custom' | '...'; // 待扩展

type EventInfo = {   
    source: 'dtd' | 'dtm';
    pageId: string;
    timestamp: string;
    eventType: string; // 事件类型
    payload: any; // 事件携带信息，依据事件类型而定
}

interface EventHandler {
    (eventInfo: EventInfo): void
}

off

解绑通用事件处理函数

示例

instance.off(eventType, handler: EventHandler)

参数

参考 on 方法

版本依赖

|SDK 版本 | DTV 版本| | :-| :- | |0.0.10 | >= SP202206|

Change log

0.0.10

• 增加 on 和 off 方法用于监听 DT 通用事件

0.0.8

• 修改saveLayout方法，接收参数 isSaveNew

0.0.7

• 修改switchToedit方法，接受参数{disableDelete: boolean, disableEdit: boolean}

0.0.4

• 添加changePage 接口，可以实时修改展示的页面
• 添加修改外部filter接口，无缝修改数据

V0.0.1

• 初始化接口

Interface

成员

enum PageMode {  
  DISPLAY = 0,   
  EDIT = 1,  
  INPLACE_EDIT = 2,  
  PREVIEW = 3
}

type PageProfile = {    
    filters: any[];
}

type onWidgetEditFn = (widgetId: string, link: string) => void;
type onWidgetDeleteFn = (widgetId) => void;
type onWidgetSaveFn = (widgetId, status: status) => void;
type onWidgetCancelFn= (widgetId) => void;
type onPageChangeFn = (profile: PageProfile) => void;


type actions = {    
    onWidgetEdit: onWidgetEditFn;   
    onWidgetDelete: onWidgetDeleteFn;   
    onWidgetSave: onWidgetSaveFn;    
    onWidgetCancel: onWidgetCancelFn;    
    onPageChange: onPageChangeFn
}

type BusinessWidgetTemplate = {   
    name: string;    
    id: string;    
    tags: string[];    
    thumbnail: string; // a url
}

type FunctionReturn = {    
    code: status;   // 请求是否成功
    message?: string;    // 请求失败的message
    data?: any // 请求返回的数据
}

interface BusinessWidgetsReturn extends FunctionReturn {    
    data: BusinessWidgetTemplate[] | [];
}


enum status {   
    success = 1,  
    error = -1
}


interface SDKConsumer {   
    targetWindow: Window;   
    pageId: string;    
    mode: PageMode = PageMode.DISPLAY;    
    onWidgetEdit: onWidgetEditFn;   
    onWidgetDelete: onWidgetDeleteFn;    
    onWidgetSave: onWidgetSaveFn;   
    onWidgetCancel: onWidgetCancelFn;    
    onPageChange: onPageChangeFn;
 }