Wings Engine

Element Class

An Element object corresponds to a component or sub-component, collectively referred to as a component. The second development code that is bound to a component will have its Element object assigned to the element property of that class.

Through this object, you can operate on the corresponding component, such as getting and setting properties, modifying settings, data linkage, listening to events, and more.

The Element object is created and bound by the system, so users do not need to construct it themselves.

1
2
3
4
5
6
class Button {
  init() {
    console.log(this.element.name);
  }
}
export default Button;

name

Getting the Component Name

1
readonly name: string

getOption()

Getting Component Settings

1
2
3
4
5
6
/**
 * Getting the Value of a Specific Setting
 * @param paths Path expression of the setting
 * @returns Value of the setting
 */
getOption(paths: string | string[]): any

setOption()

Modifying Component Settings

1
2
3
4
5
6
/**
 * Modifying the Value of a Specific Setting
 * @param paths Path expression of the setting
 * @param value Value of the setting
 */
setOption(paths: string | string[], value: any): void

applyLinkage()

Triggering Data Linkage

1
2
3
4
5
/**
 * Trigger Linkage
 * @param linkage Linkage conditions
 */
applyLinkage(linkage:{name:string,value:any} | {name:string,value:any}[]): void

withdrawLinkage()

Cancelling Data Linkage

1
2
3
4
5
/**
 * Cancel Linkage
 * @param names Optional: Array of keys for the linkages to cancel; if not provided, all linkages are canceled.
 */
withdrawLinkage(names?: string[]): void

getFullData()

Getting Component Data (Deprecated, Use readData Instead)

1
2
3
4
5
6
7
8
/**
 * @deprecated Use readData Instead
 * Get component data
 * @param paths Path expression of the data setting
 * @param encode Format of the data to be retrieved (json or array), default is json
 * @returns Return the selected data of the component
 */
getFullData(paths: string | string[], encode?: "json" | "array"): any

readData()

Reading Data

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
 * Reading Data
 * @param paths Path Expression of the Setting, Supporting Multiple Items
 * @param callback Callback when data reading is complete
 * @param options
   * * dataFormat Optional values: "row", "column", "object". Default value is "row"
   * For the following example table data:
   * | A  | B  | C  |
   * | a1 | b1 | c1 |
   * | a2 | b2 | c2 |
   * | a3 | b3 | c3 |
   * The return result is as follows
   * "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 When set to true, listen for data changes; callback will be triggered on each data change
 */
readData(paths: string | string[] | string[][], callback: ReadDataCallback, options?: ReadDataOptions): any[];

readDataAsync()

Asynchronous Data Reading

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
 * Asynchronous Data Reading
 * @param paths Path Expression of the Setting, Supporting Multiple Items
 * @param options
 * * dataFormat Optional values: "row", "column", "object". Default value is "row"
 * For the following example table data:
 * | A  | B  | C  |
 * | a1 | b1 | c1 |
 * | a2 | b2 | c2 |
 * | a3 | b3 | c3 |
 * The return result is as follows
 * "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 of the data reading result
 */
readDataAsync(paths: string | string[] | string[][], options?: ReadDataAsyncOptions): Promise<any[]>

addEventListener()

Adding Event Listeners to Components

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
 * Adding Event Listeners
 * @param name Event Type
 * @param callback Callback function
 */
addEventListener(name: string, callback: Callback): void;

type Event = {
  type: string,//Event Type
}
type MessageEvent = Event & {
  origin: string,//Source of the message sender
  source: {
    postMessage: (data: any) => void,//Reply to the message sender
    fromSelf: boolean,//Current is an iframe component, and the message source is from this iframe
  },
}

type Callback = (ev: Event) => void

data-changed event

Triggering on Data Change

1
2
3
4
5
6
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("data-changed", (ev: Event)=>{
  const paths: string | string[] = ev.paths;
  //paths for the options that have changed
});

option-changed event

Triggering on Setting Change

Note: To prevent performance degradation due to large-scale listening, only fields that have been read will trigger callbacks.

1
2
3
4
5
6
7
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
//！！！！！Note: Read the property first to be able to listen to changes of that property.
const optionValue = this.element.getOption(["XXXXXX"]);
element.addEventListener("option-changed", (ev: Event)=>{
  //Handling Data Change Logic
});

message event

Triggered when a postMessage event is received.

1
2
3
4
5
6
7
8
9
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("message", (ev: MessageEvent)=>{
  const { data, origin, source } = ev;
  //data represents the received data.
  //origin is the message source string.
  //source can be used to reply to the message.
  source.postMessage({msg: "test"});
});

click event

Triggered when the corresponding component is clicked by the mouse.

1
2
3
4
5
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("click", (ev: Event)=>{
  const data = ev.data;
});

mouseenter event

Triggered when the mouse enters the corresponding component.

1
2
3
4
5
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("mouseenter", (ev: Event)=>{
  const data = ev.data;
});

mouseleave event

Triggered when the mouse leaves the corresponding component.

1
2
3
4
5
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("mouseleave", (ev: Event)=>{
  const data = ev.data;
});

Custom Events

Custom event names can be defined and triggered either through interactions or by using the emit method.

To add a custom event, use the following code:

1
2
3
4
5
6
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.addEventListener("my-test-event", (ev: Event)=>{
  const data = ev.data;
  //If triggered via the emit method below, data will be {test:123}.
});

You can trigger a custom event using the same element object by calling the emit method:

1
2
3
//Note: Second development code only supports JS. For convenience, the example code uses TS here.
let element = ...;
element.emit("my-test-event", {test:123});

Custom events can also be triggered by setting interactions:

removeEventListener()

Remove the event listener from the component.

1
2
3
4
5
6
/**
 * Delete the event listener.
 * @param name Event Types
 * @param callback Optional. Callback function.
 */
removeEventListener(name: string, callback?: Callback): void

emit()

Trigger an event on the component.

1
2
3
4
5
6
/**
 * Trigger Event
 * @param name Event Type
 * @param data Optional. Data associated with the event.
 */
emit(name: string, data?: any): void

isEmpty()

Determine if element is associated with the component.

1
2
3
4
5
/**
 * element Association with Component
 * @returns Check if it is associated.
 */
isEmpty(): boolean

getMountedInstance()

Get the instance object exposed by the component. This object can be used to perform some advanced functions.

1
2
3
4
5
/**
 * Get the instance object exposed by the component.
 * @returns Returns the object exposed by the component; returns an empty object if not exposed.
 */
getMountedInstance(): any

The following components expose an instance object:

The ECharts chart component exposes the ECharts instance object; refer to the ECharts documentation.

getExtensionInstances()

Get the list of all extended instances for the current element.

1
2
3
4
5
/**
 * Get the list of all extended instances for the current element.
 * @returns All Extended Instances List
 */
getExtensionInstances(): Array<Object>

getExtensionInstance()

Get the first extended instance of the current element.

1
2
3
4
5
/**
 * Get the first extended instance of the current element.
 * @returns First Extended Instance
 */
getExtensionInstance(): Object

getChildren()

Get the list of child elements of the current element.

1
2
3
4
5
/**
 * Get the list of child elements of the current element.
 * @returns Child Elements List
 */
getChildren(): Array<Element>

getParent()

Get the parent elements of the current element.

1
2
3
4
5
/**
 * Get the parent elements of the current element.
 * @returns Parent Element
 */
getParent(): Element

clone()

Dynamically clone the current element. Note that this method is asynchronous and currently only applicable to elements in 3D mode.

1
2
3
4
5
6
/**
 * Dynamically clone the current element.
 * @param name Cloned Element Name
 * @returns Returns a promise.
 */
clone(name: string): Promise<Element>

remove()

Delete the current element. Note that only cloned elements can be deleted. Calling this method on non-cloned elements will have no effect.

1
2
3
4
5
/**
 * Delete the current element.
 * @returns void
 */
remove(): void

Copyright © 2024  Hangzhou Duosuan Technology Co., Ltd.

Top Bottom