山海鲸可视化

Element类

Element 对象对应一个组件、子组件或子看板，下面统称为组件。二开代码被绑定在哪个组件上，这个组件的 Element 对象就会赋值给这个类的 elememt 属性。

通过此对象可以操作对应的组件，获取设置项、修改设置项、数据联动、监听事件等。

Element 对象由系统创建并绑定，用户无需构造。

class Button {
  init() {
    console.log(this.element.name);
  }
}
export default Button;

1.基础属性和方法

name

获取组件的名称。

readonly name: string

getOption()

获取组件的设置项。

/**
 * 获取某个设置项的值
 * @param paths 设置项的路径表达
 * @returns 该设置项的值
 */
getOption(paths: string | string[]): any

setOption()

修改组件的设置项。

/**
 * 修改某个设置项的值
 * @param paths 设置项的路径表达
 * @param value 设置项的值
 */
setOption(paths: string | string[], value: any): void

2.数据相关方法

applyLinkage()

让组件触发数据联动。

/**
 * 触发联动
 * @param linkage 联动条件
 */
applyLinkage(linkage:{name:string,value:any} | {name:string,value:any}[]): void

withdrawLinkage()

让组件取消数据联动。

/**
 * 取消联动
 * @param names 可选。要取消的联动的key数组，不传则取消所有联动
 */
withdrawLinkage(names?: string[]): void

getFullData()

获取组件的数据。已弃用，建议使用 readData 替代。

/**
 * @deprecated 使用readData替代
 * 获取组件的数据
 * @param paths 数据设置项的路径表达
 * @param encode 获取数据的格式（json或array），默认为json
 * @returns 返回该组件勾选的数据
 */
getFullData(paths: string | string[], encode?: "json" | "array"): any

readData()

读取数据。从 v4.2.0 开始支持。

/**
 * 读取数据
 * @since 4.2.0
 * @param paths 设置项的路径表达，支持多项
 * @param callback 数据读取完时回调
 * @param options
   * * dataFormat 可选值有"row", "column", "object"。默认值为"row"
   * 对于以下示例表格数据:
   * | A  | B  | C  |
   * | a1 | b1 | c1 |
   * | a2 | b2 | c2 |
   * | a3 | b3 | c3 |
   * 返回结果如下
   * "object" : [{A:"a1", B:"b1", C:"c1"}, {A:"a2", B:"b2", C:"c2"}, {A:"a3", B:"b3", C:"c3"}]
   * "row" : [[a1, b1, c1], [a2, b2, c2], [a3, b3, c3]]
   * "column" : [[a1, a2, a3], [b1, b2, b3], [c1, c2, c3]]
 * * callbackOnDataChanged 为true时，监听数据变化，每次数据变化时都会回调callback
 */
readData(paths: string | string[] | string[][], callback: ReadDataCallback, options?: ReadDataOptions): any[];

readDataAsync()

异步读取数据。从 v4.2.0 开始支持。

/**
 * 异步读取数据
 * @since 4.2.0
 * @param paths 设置项的路径表达，支持多项
 * @param options
 * * dataFormat 可选值有"row", "column", "object"。默认值为"row"
 * 对于以下示例表格数据:
 * | A  | B  | C  |
 * | a1 | b1 | c1 |
 * | a2 | b2 | c2 |
 * | a3 | b3 | c3 |
 * 返回结果如下
 * "object" : [{A:"a1", B:"b1", C:"c1"}, {A:"a2", B:"b2", C:"c2"}, {A:"a3", B:"b3", C:"c3"}]
 * "row" : [[a1, b1, c1], [a2, b2, c2], [a3, b3, c3]]
 * "column" : [[a1, a2, a3], [b1, b2, b3], [c1, c2, c3]]
 * @returns resolve数据读取结果的Promise
 */
readDataAsync(paths: string | string[] | string[][], options?: ReadDataAsyncOptions): Promise<any[]>

3.事件相关方法

addEventListener()

添加组件的事件监听。

/**
 * 添加事件监听
 * @param name 事件类型
 * @param callback 回调函数
 */
addEventListener(name: string, callback: Callback): void;

type Event = {
  type: string,//事件类型
}
type MessageEvent = Event & {
  origin: string,//消息发送者来源
  source: {
    postMessage: (data: any) => void,//给消息发送者回复消息
    fromSelf: boolean,//当前为iframe组件，并且消息来源于此iframe
  },
}

type Callback = (ev: Event) => void

removeEventListener()

移除组件的事件监听。

/**
 * 删除事件监听
 * @param name 事件类型
 * @param callback 可选。回调函数
 */
removeEventListener(name: string, callback?: Callback): void

emit()

触发组件上的事件。

/**
 * 触发事件
 * @param name 事件类型
 * @param data 可选。事件关联的数据
 */
emit(name: string, data?: any): void

3.1 所有事件列表

以下事件都可以被 addEventListener 监听到，部分事件可以直接用 emit 方法触发，具体请查看对应事件的描述。

data-changed 事件

当数据变化时触发。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("data-changed", (ev: Event)=>{
  const paths: string | string[] = ev.paths;
  //paths为发生变化的option的paths
});

option-changed 事件

当设置项变化时触发。

注意：为了防止大规模监听带来的性能下降，只有被读取过的字段才会触发回调。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
//！！！！！注意 先读取该属性，才能监听到该属性的变化
const optionValue = this.element.getOption(["XXXXXX"]);
element.addEventListener("option-changed", (ev: Event)=>{
  const paths = ev.paths;
  //处理数据变化时的逻辑
  if(Paths.equals(paths,["XXXXXX"])){
    // Your code here
  }
});

message 事件

收到 postMessage 事件时触发。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("message", (ev: MessageEvent)=>{
  const { data, origin, source } = ev;
  //data为收到的数据
  //origin为消息来源字符串
  //source可以用来回复消息
  source.postMessage({msg: "test"});
});

click 事件

当对应的组件被鼠标单击时触发。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("click", (ev: Event)=>{
  const data = ev.data;
});

主动发送 click 事件，可以触发元素的点击，对于 3d 元素还会触发元素的选中状态的切换。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.emit("click");

mouseenter 事件

当鼠标进入对应的组件时触发。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("mouseenter", (ev: Event)=>{
  const data = ev.data;
});

主动发送 mouseenter 事件，可以触发元素的鼠标进入事件

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.emit("mouseenter");

mouseleave 事件

当鼠标离开对应的组件时触发。

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("mouseleave", (ev: Event)=>{
  const data = ev.data;
});

主动发送 mouseleave 事件，可以触发元素的鼠标进入事件

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.emit("mouseleave");

自定义事件

可以自定义事件名称，然后通过交互来触发，或者通过 emit 方法来触发。

通过如下代码添加自定义事件：

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.addEventListener("my-test-event", (ev: Event)=>{
  const data = ev.data;
  //如果通过下面的emit触发，则data为{test:123}
});

通过相同的 element 对象，调用 emit 方法来触发自定义事件：

//注意：二开代码仅支持js，为了方便说明类型，这里示例代码使用了ts
let element = ...;
element.emit("my-test-event", {test:123});

也可以通过设置交互来触发：

4.其他方法

isEmpty()

判断 element 是否与组件建立关联。

/**
 * element与组件是否建立关联
 * @returns 是否建立关联
 */
isEmpty(): boolean

getMountedInstance()

获取组件暴露的 instance 对象。通过该对象可实现一些高级功能。

/**
 * 获取组件暴露的instance对象。
 * @returns 返回组件暴露的对象，未暴露时返回空对象
 */
getMountedInstance(): any

以下组件暴露了 instance 对象：

ECharts 图表组件暴露了 ECharts 实例对象，参见echarts 文档。

getExtensionInstances()

获取当前元素的所有扩展的实例列表，从 v4.2.0 开始支持。

/**
 * 获取当前元素的所有扩展的实例列表
 * @returns 所有扩展的实例列表
 */
getExtensionInstances(): Array<Object>

getExtensionInstance()

获取当前元素的所有扩展的第一个实例，从 v4.2.0 开始支持

/**
 * 获取当前元素的所有扩展的第一个实例
 * @returns 所有扩展的第一个实例
 */
getExtensionInstance(): Object

getChildren()

获取当前元素的子元素列表，从 v4.2.0 开始支持。

/**
 * 获取当前元素的子元素列表
 * @returns 子元素列表
 */
getChildren(): Array<Element>

getParent()

获取当前元素的子元素列表，从 v4.2.0 开始支持。

/**
 * 获取当前元素的父元素
 * @returns 父元素
 */
getParent(): Element

clone()

将当前的元素动态复制出来一个，注意该方法是一个异步方法，目前只有鲸孪生中的元素可以使用该方法，从 v4.2.0 开始支持。

/**
 * 将当前的元素动态复制出来一个
 * @param name 克隆出来元素的名字
 * @returns 返回promise
 */
clone(name: string): Promise<Element>

remove()

删除当前元素，注意只有被 clone 出来的元素才可以被删除。非 clone 出来的元素调用该方法将无任何效果，从 v4.2.0 开始支持。

/**
 * 删除当前元素
 * @returns void
 */
remove(): void


回到顶部 滚到底部