1 描述
2 安装
- 安装方法
- 依赖说明
3 使用手册
4 Change log
- 2.4.4
- 0.0.12
- 0.0.11
- 0.0.10
- 0.0.8
- 0.0.7
- 0.0.4
- 0.0.1
5 Interface
- 成员

1 描述

此为EnOS DTV SDK 使用说明文档利用此SDK可以在宿主页面和DTV创建的页面之间构建通信通道和调用方法，提供比如

切换显示模式
添加删除Widget
操作和控制表单
修改个人信息等

2 安装

安装方法

使用 yarn

yarn add @envision-digital/dtv-sdk

使用 npm

npm install @envision-digital/dtv-sdk

依赖说明

此SDK依赖对应的DTV版本，功能和提供的方法向前兼容，如果SDK版本高于对应的服务版本，部分功能或不可用

SDK版本	DTV 服务版本	说明
2.4.4	>= 2.4.4
0.0.12	>= SP202210
0.0.11	>= SP202208
0.0.10	>= SP202206

3 使用手册

3.1 SDK 全局配置与环境变量

3.1.1 全局配置

同域使用sdk，需确保开启同域调用开关

import {setConfig} from '@envision-digital/dtv-sdk';
setConfig({enableDirectCall: true});

配置项

enableDirectCall: 开启同域调用优化，默认关闭

3.1.2 环境变量

dtv_debug 开启日志打印

为保证性能，SDK 默认不再向控制台打印 api 调用信息，如需开启，可以：

在 localStorage 中设置标志 dtv_debug = true, 或者
在控制台输入 localStorage.setItem('dtv_debug', true)

3.2 DTV Dashboard 模块

3.2.1 以组件方式使用(推荐)

示例:

import React, {useRef, useEffect} from 'react';
import {Page} from '@envision-digital/dtv-sdk';

const DTVPage = Page.Component;

const Component = () => {
    const ref = useRef(null);

    useEffect(() => {
        const instance = ref.current.getDTVInstance(); 获取 SDK 实例
        const frame = ref.current.getDTVFrame(); 获取 IFrame 节点
        // ...
    }, []);

    return (
        <DTVPage
            ref={ref}
            baseUri='https://xxx/dt/enos/page'
            id='xxx'
            filters={{mdmId: 'xxx', startTime: 'xxx', endTime: 'xxx'}}
            responsiveMode='web'
        />
    )
}

类型定义:

interface PageRenderProps {
  id?: string; // 页面 id
  baseUri: string; // 对应环境路由
  filters?: Record<string, string|number>; // 过滤器传参，参考 changePage filters 参数
  responsiveMode?: 'mb' | 'web' | 'lg'; // 响应模式
  style?: React.CSSProperties; // 渲染页面 iframe 的样式
  defaultParams?: any[]; // 页面初始化传参，参考 changePage events 参数
  token?: string; // iam token
  subscribeActions?: actions; // 注册接收页面事件
  embedded?: boolean; // 嵌入模式
  defer?: boolean; // 延迟加载
  state?: string; // 额外 url 传参
  onError?: onErrorFn; // 监听发布页面返回错误等事件
}

type onErrorFn = (err: PageError) => void;

type PageError = {
    errType: ErrType;
}

enum ErrType {
    NO_EXIST_RELEASE_PAGE,
    // 待扩展
}

token传递说明:

为了安全考虑，token将不再在url中明文传递。同域使用sdk，需确保开启同域调用 setConfig({enableDirectCall: true})。

3.2.2 直接使用 SDK

import DTVPageSDK from '@envision-digital/dtv-sdk'

3.2.2.1 初始化页面实例

创建页面实例

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

参数：

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

3.2.2.2 class interface

详情见最后

3.2.2.3 接口

实例对象暴露的接口列表

subscribeActions

注册page页面的事件接收

示例：

instance.subscribeActions({ onWidgetDelete, onCancelEdit, onSavePage})

参数：

onWidgetDelete 当用户点击某个widget，想要移除widget时调用
- widgetId: 想要删除的widget的Id
onCancelEdit 当用户取消编辑编辑时调用
onSavePage 当用户保存当前编辑页面时调用, 入参为最新保存的页面id
onError 监听发布页面返回错误等事件

声明：

type onWidgetDeleteFn = (widgetId：stirng) => void;
type onCancelEditFn = (widgetId：stirng) => void;
type onSavePageFn = ({pageId: string}) => void;
type onErrorFn = (err: PageError) => void;

type PageError = {
    errType: ErrType;
}

enum ErrType {
    NO_EXIST_RELEASE_PAGE,
    // 待扩展
}

返回：无返回

switchToEdit

进入编辑模式

使用场景：运行态

示例：

instance.switchToEdit({enableOnlineEdit: true, disableDelete: true, disableEdit: true}): Promise<FunctionReturn>

参数：

enableOnlineEdit: 是否开启在线编辑功能，默认不开启
disableDelete: 是否禁用删除组件功能，默认不禁用
disableEdit: 是否禁用编辑组件功能，默认不禁用

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

switchToDisplay

回到只读模式使用场景：编辑态示例：

instance.switchToDisplay(): Promise<FunctionReturn>

参数：无

Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

getBusinessWidgets

获取可选的业务组件模板使用场景：编辑态示例：

instance.getBusinessWidgets(): Promise<BusinessWidgetsReturn>

参数：无

code: 0 | 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 = 0,  
    error = 1
}

refreshPage

重新渲染整个页面，一般在保存之后，可能需要调用使用场景：运行态示例：

instance.refreshPage(): Promise<FunctionReturn>

参数：无

Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

saveLayout

保存布局修改使用场景：编辑态示例：

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

参数：

isSaveNew: 是否保存为新页面

Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

changePage

修改页面展示的内容，页面id 使用场景：运行态

示例：

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

参数：

export type PageChangeParams = {
    id: string;
    filters: {
        [key: string]: string;
    };
    events?: EventOption[], // 详见 dispatchEvent 方法
    dataType?: 'normal' | 'mock' | 'cache'
}

changeFilter

改变页面filter

使用场景：运行态

示例：

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

参数：

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

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 方法

dispatchEvent

向 DTV 组件派发事件

使用场景：运行态

示例：

instance.dispatchEvent({
    cageCode: 'MTD',
    eventType: 'container.changeCurrentTab',
    payload: {tabIndex: 1}
}: EventOption | EventOption[]);

参数：

interface EventOption {
    eventType: string; // 事件类型
    cageCode?: string; // 组件标识码
    payload?: any; // 事件携带信息
}

组件最新的事件支持信息联系 DTV 相关方获取

getWidgetsList

获取页面中组件及隐藏区组件列表

使用场景：编辑态

示例：

instance.getWidgetsList(pageId: string): Promise<WidgetsListReturn>

参数：

pageId：需要获取的组件及隐藏区组件列表的pageId

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

type WidgetsList = {
    widgetId: string;
    name: string;
    visible: boolean;
}

interface WidgetsListReturn extends FunctionReturn {    
    data: WidgetsList[] | [];
}

setWidgetVisible

设置组件是否隐藏

使用场景：编辑态

示例：

instance.setWidgetVisible(widgetId: string, visible： boolean): Promise<FunctionReturn>

参数：

widgetId: 需要设置的组件的id
visible: 需要将所选组件设为隐藏时为false，设置为不隐藏时为true

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

setToken

设置dtv_sdk_token

示例：

instance.setToken(token: string)

参数：

token: 传递dtv_sdk_token

说明：

使用iframe且为同域场景，需在iframe onload阶段调用setToken方法传递token，若token发生更新，也可调用该方法更新token。
使用iframe且为非同域场景，建议升级使用DTV Component。

3.3 DTV Form Builder 模块

3.3.1 以组件方式使用-运行态(推荐)

示例:

import React, {useRef, useEffect} from 'react';
import {Form} from '@envision-digital/dtv-sdk';

const DTVForm = Form.Component;

const Component = () => {
    const ref = useRef(null);

    useEffect(() => {
        const instance = ref.current.getDTVInstance(); // 获取 SDK 实例
        const frame = ref.current.getDTVFrame(); // 获取 IFrame 节点
        // ...
    }, []);

    return (
        <DTVForm
            ref={ref}
            baseUri='https://xxx/dt/enos/form'
            id='xxx'
        />
    )
}

类型定义:

interface FormRenderProps {
  id?: string; // 表单页面 id
  baseUri: string; // 对应环境路由
  formMode?: FORM_MODE; // 表单页面初始展示模式
  formSchema?: FormSchema; // 表单的Schema， FormSchema & id 二选一填写，都填写已id 为准
  formData?: any; // 表单页面初始值
  style?: React.CSSProperties; // 渲染表单页面 iframe 的样式
  token?: string; // iam token
  state?: string; // 额外 url 传参
  options?: FormOptions; // 表单运行的其他配置内容
  styleCode?: string; // 表单额外的样式
  onChange?: onChangeFn; // 注册表单data发生变化时的响应事件
  onAction?: onActionFn; // 表单本身渲染按钮，用户点击按钮后触发该事件
}

type FormOptions = {
  layout?: 'vertical' | 'horizontal' // 表单的布局
  labelWrap?: boolean; // 表单label是否折行
}

type FormSchema = {
  form: any;
  schema: any;
  actionMeta?: any;
}

token传递说明:

为了安全考虑，token将不再在url中明文传递。同域使用sdk，需确保开启同域调用 setConfig({enableDirectCall: true})。

3.3.2 以组件方式使用-设计器态

示例:

import React, {useRef, useEffect} from 'react';
import {Form} from '@envision-digital/dtv-sdk';

const FormDesinger = Form.DesingerComponent;

const Component = () => {
    const ref = useRef(null);

    useEffect(() => {
        const instance = ref.current.getDTVInstance(); // 获取 SDK 实例
        const frame = ref.current.getDTVFrame(); // 获取 IFrame 节点
        // ...
    }, []);

    return (
        <FormDesinger
            ref={ref}
            baseUri='https://xxx/dt/enos/form'
            id='xxx'
            targetPage='editor'
        />
    )
}

类型定义:

interface FormDesignerRenderProps {
  id: string; // 表单页面 id
  baseUri: string; // 对应环境路由
  style?: React.CSSProperties; // 渲染表单页面 iframe 的样式
  token?: string; // iam token
  state?: string; // 额外 url 传参
  targetPage: Target; // 指定渲染的目标页面
  onReturn: () => void; // 注册页面返回时的响应事件
  onPublish: () => void; // 注册发布页面后的响应事件
  beforeSave: (formSchema) => Promise; // 用户点击保存时调用，方便第三方校验表单schema, 校验成功返回Promise.resolve(), 校验是否需返回错误信息Promise.reject({msg: 'xxx'})
}

type Target = {
    EDITOR: 'editor'; // 渲染表单编辑页
    DETAIL: 'detail'; // 渲染表单详情页（版本管理页）
}

3.3.3 通过方法调用

import {Form as DTVFormSDK} from '@envision-digital/dtv-sdk'

初始化页面实例：

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

参数：

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

3.3.4 方法列表

详情见最后实例对象暴露的接口列表

changeForm

切换表单id，表单状态及表单数据时使用

使用场景：运行态和设计态

示例：

instance.changeForm({
    id: string
}): Promise<FunctionReturn>


type FormChangeParams = {
    id?: string;
    formSchema?: FormSchema;
    formMode?: FORM_MODE;
    formData?: any;
    options?: FormOptions;
    styleCode?: string;
}

参数：

id: 需要修改的表单id
formSchema: 表单的schema，FormSchema & id 二选一填写，都填写以 id 为准
formMode: 切换表单状态(只读态或输入态)
formData: 表单接收的外部数据

Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

enum FORM_MODE {
    INPUT = 'input', // 输入态
    READ_ONLY = 'readOnly' // 只读态
}

getFormData

获取表单数据

使用场景：运行态

示例：

instance.getFormData(formId: string): Promise<FunctionReturn>

参数：

formId: 表单id

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

validateFormData

校验表单

使用场景：运行态

示例：

instance.validateFormData(formId: string): Promise<FunctionReturn>

参数：

formId: 表单id

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

onSubmit

提交表单数据方法，校验表单后，返回当前表单的数据

使用场景：运行态

示例：

instance.onSubmit(): Promise<FunctionReturn>

参数：无

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

beforeSave

用户点击保存时调用（仅限同域调用），方便第三方校验表单schema, 校验成功返回Promise.resolve(), 校验是否需返回错误信息Promise.reject({msg: 'xxx'})

使用场景：设计态

示例：

instance.beforeSave(beforeSaveFn): Promise<FunctionReturn>

type beforeSaveFn = (formSchema) => Promise

参数：

beforeSaveFn: 真正保存前校验表单的方法

返回： Promise<FunctionReturn>

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

enum status {   
    success = 0,  
    error = 1
}

subscribeActions

注册form的事件接收

示例：

instance.subscribeActions({
    onAction: ({data, actionKey}) => {},
    onChange: (formData) => {},
    onReturn: () => {},
    onPublish: () => {}
})

参数：

onAction 表单渲染按钮场景下，用户点击表单按钮后调用, 运行态使用
- data: 表单提交的实体信息
- actionKey: 用户点击的按钮的key
onChange 表单数据发生变化时调用, 运行态使用
- formData: 表单当前数据
onReturn 用户点击返回按钮时调用，设计态使用
onPublish 用户发布页面后调用，设计态使用

声明：

type onActionFn = ({data: any, actionKey: string}) => void;
type onChangeFn = (formData: object) => void;
type onReturnFn = () => void;
type onPublishFn = () => void;

返回：无返回

4 Change log

2.4.6

support esm

2.4.5

一些优化

2.4.4

不再通过url传递token，且提供了setToken方法。使用DTV Component和iframe分别参考说明操作
DTVPage新增onError方法，用于监听发布页面返回等错误
不再使用onWidgetEdit, onWidgetSave, onWidgetCancel, onPageChage注册事件
新增onCancelEdit, onSavePage注册事件
修改switchToEdit方法，新增参数{enableOnlineEdit: boolean}
不再使用deleteWidget方法
不再使用refreshWidget方法
定义了部分方法的使用场景
修改DTVPage组件引用方式
新增DTVForm、FormDesinger组件使用方法
新增changeForm, getFormData, validateFormData, onAction，onChange，onChange，onReturn，onPublish, onReturn，onPublish, beforeSave表单页面相关方法

0.0.12

增加 getWidgetsList 方法用于获取页面中组件及隐藏区组件列表
增加 setWidgetVisible 方法用于设置组件是否隐藏
增加 DTVPage 组件
增加 SDK 配置功能

0.0.11

增加 dispatchEvent 方法用于向 DTV 组件派发消息
changePage 增加 events 传参

0.0.10

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

0.0.8

修改saveLayout方法，接收参数 isSaveNew

0.0.7

修改switchToEdit方法，新增接受参数{disableDelete: boolean, disableEdit: boolean}

0.0.4

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

0.0.1

初始化接口

5 Interface

成员

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

type PageProfile = {    
    filters: any[];
}

type onWidgetDeleteFn = (widgetId) => void;
type onCancelEditFn = (widgetId：stirng) => void;
type onSavePageFn = ({pageId: string}) => void;
type onSubmit = ({data: any, actionKey: string}) => void;

type onActionFn = ({data: any, actionKey: string}) => void;
type onChangeFn = (formData: object) => void;
type onReturnFn = () => void;
type onPublishFn = () => void;
type onErrorFn = (err: PageError) => void;

type PageError = {
    errType: ErrType;
}

enum ErrType {
    NO_EXIST_RELEASE_PAGE,
    // 待扩展
}

type actions = {    
    onWidgetDelete: onWidgetDeleteFn;   
    onCancelEdit: onCancelEditFn;
    onSavePage: onSavePageFn;
}

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

type WidgetsList = {
    widgetId: string;
    name: string;
    visible: boolean;
}

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

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

interface WidgetsListReturn extends FunctionReturn {    
    data: WidgetsList[] | [];
}

type PageChangeParams = {
    id: string;
    filters: {
        [key: string]: string;
    };
    events?: EventOption[], // 详见 dispatchEvent 方法
    dataType?: 'normal' | 'mock' | 'cache'
}

type FormChangeParams = {
    id?: string;
    formMode?: FORM_MODE;
    formData?: any;
    formSchema?: FormSchema;
    options?: FormOptions;
    styleCode?: string;
}

enum status {   
    success = 0,  
    error = 1
}

enum FORM_MODE {
    INPUT = 'input', // 输入态
    READ_ONLY = 'readOnly' // 只读态
}

interface SDKConsumer {   
    targetWindow: Window;   
    pageId: string;    
    mode: PageMode = PageMode.DISPLAY;    
    onWidgetDelete: onWidgetDeleteFn;    
    onCancelEdit: onCancelEditFn;
    onSavePage: onSavePageFn;
}

@envision-digital/dtv-sdk

1 描述

2 安装

安装方法

依赖说明

3 使用手册

3.1 SDK 全局配置与环境变量

3.1.1 全局配置

配置项

3.1.2 环境变量

dtv_debug 开启日志打印

3.2 DTV Dashboard 模块

3.2.1 以组件方式使用(推荐)

示例:

类型定义:

token传递说明:

3.2.2 直接使用 SDK

3.2.2.1 初始化页面实例

3.2.2.2 class interface

3.2.2.3 接口

subscribeActions

switchToEdit

switchToDisplay

getBusinessWidgets

addWidgetFromTemplate

refreshPage

saveLayout

changePage

changeFilter

cancelEdit

on

off

dispatchEvent

getWidgetsList

setWidgetVisible

setToken

3.3 DTV Form Builder 模块

3.3.1 以组件方式使用-运行态(推荐)

token传递说明:

3.3.2 以组件方式使用-设计器态

3.3.3 通过方法调用

3.3.4 方法列表

changeForm

getFormData

validateFormData

onSubmit

beforeSave

subscribeActions

4 Change log

2.4.6

2.4.5

2.4.4

0.0.12

0.0.11

0.0.10

0.0.8

0.0.7

0.0.4

0.0.1

5 Interface

成员

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads