DataV-Board custom development tutorial-DataV(DataV)-阿里云帮助中心

DataV-Board provides a custom development feature for creating complex and flexible dashboard effects. This feature is only available to Premium Edition users.

Scenarios

If the built-in features of DataV-Board do not meet your business requirements, you can write JavaScript code (Hook scripts) for custom development. This feature offers more freedom and flexibility than the Blueprint Editor, which lets you customize dashboards as needed.

Display effect optimization: Use Hook scripts to customize CSS styles for enhanced visual effects.
Data processing and transformation: Use Hook scripts to process and transform data on the frontend to meet specific business logic requirements.
Dynamic content updates: Use Hook scripts to enable dynamic content updates and real-time data display on your dashboards.
Advanced animation effects: Use Hook scripts to add complex animation effects and enhance the visual appeal of your dashboards.
Event Response: Responds to user interactions, such as clicks and hovers, to enhance dashboard interactivity.

Limits

This feature is only available to Premium Edition users. If you are not a Premium Edition user, you must first upgrade your product.

Procedure

Access the DataV console.
On the target dashboard page, click global search, and enter the keyword hook to open the hook editor.

Note
Only Premium Edition users can access the editor. Ensure that you are subscribed to the Premium Edition.
On the custom development code editor page, write your code, and click Save.
Go to the preview page to check the result. If you are satisfied with the result, publish the dashboard.

Hook API

Function body

By default, Hook code uses the CommonJS structure. You must expose an execution function globally. The function body is as follows:

/**
 * @param {IStage} stage 
 */
module.exports = (stage) => {

};

The stage utility object

The input parameter `stage` is a utility object passed during the dashboard runtime. Its type is as follows:

Stage object interface definition

interface IStage {
  get: (id: string) => ICompatibleComponent | undefined;
  getAll: () => Record<string, ICompatibleComponent | undefined>;
  on: (eventName: string, listener: (...args: any[]) => void) => () => void;
  emit: (eventName: string, ...args: any[]) => void;
  exec: (methodName: string, ...args: any[]) => void;
  expose: (methodMap: Record<string, (...args: any[]) => void>) => void;
  getComponent: (id: string) => IDatavComponent | undefined | null;
  getVariable: (
    id: string,
  ) =>
    | {
        value: any;
        set: (value: any) => void;
        onChange: (cb: (current: any, prev: any) => void) => IDisposer;
      }
    | undefined;
}

type IDisposer = () => void;
/**
 * Common methods for widget instances
 */
interface IDatavComponent {
  /** Renders the widget */
  render(data: any, options?: { [key: string]: any }): void;
  /** Updates configurations */
  updateOptions(options: { [key: string]: any }): void;
  /** Uninstalls the widget */
  destroy(): void;
  /** Resizes the width and height */
  resize?(w: number, h: number): void;
  /** Starts animations */
  startAnimates?(): void;
  /** Purges animations */
  clearAnimates?(): void;
}

interface IMoveConfig {
  attr: {
    x: number;
    y: number;
  };
  positionType: 'to' | 'by';
}

type ICompatibleComponent = IDatavComponent & {
  /* Widget instance */
  instance: any;
  /* The actual DOM rendered by the widget */
  container: HTMLDivElement;
  /* Listens for events emitted by the widget. For details about the input parameters of the callback function, see the widget's documentation. */
  on: (eventName: string, ...args: any[]) => void;
  /* Shows the widget */
  show(): void;
  /* Hides the widget */
  hide(): void;
  /* Updates the widget's style configuration */
  updateProps(props: any): void;
  /* Sets the widget data */
  setData(key: string): void;
  /* Initiates the widget's data retrieval process. You can specify a data name. */
  fetchData(key?: string): Promise<any>;
  /* Listens for changes in widget data */
  onDataChange: (key: string, cb: (current: any, prev: any) => void) => IDisposer;
} & {
  /* Widget ID */
  __id: string;
  /* Toggles the widget's visibility */
  toggleVisible(): void;
  /* Moves the widget */
  move(options: IMoveConfig): void;
}

Sample code

Getting components

To retrieve a widget, use the following code.

Important

To obtain the widget ID, select the widget in the canvas editor, right-click it, and select Copy ID.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

Toggle widget visibility

To toggle the visibility of a widget, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Hide the widget
lineChart.hide();
// Show the widget
lineChart.show();
// Toggle visibility
lineChart.toggleVisible();

Move a widget

To move a widget, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Move the widget 100 units to the right and 30 units down
lineChart.move({
  attr: {
    x: 100,
    y: 30,
  },
  positionType: 'by'
});

// Move the widget to the coordinate (0, 120). Note: The origin of the coordinate system is the upper-left corner of the canvas.
lineChart.move({
  attr: {
    x: 0,
    y: 120,
  },
  positionType: 'to'
});

Set widget data

To set widget data, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Clear the widget's data
lineChart.setData('source', []);

View widget data

To view widget data, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Current data of the widget
const data = lineChart.data;

Get the widget's DOM

To retrieve the widget's DOM, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Do not directly delete or modify the DOM. This may affect the runtime content.
const dom = lineChart.container;

Initiate a data source request for a widget

To initiate a data source request for a widget, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// Initiate requests for all data sources of the widget
lineChart.fetchData();
// Initiate a request for the 'source' data source of the widget
lineChart.fetchData('source')

Listen for widget data changes

To listen for widget data changes, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

lineChart.onDataChange('source', (currentData, previousData) => {
  // This callback function is executed when the result of the 'source' data source changes.
});

Listen for events emitted by a widget

To listen for events emitted by a widget, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');

// For specific event IDs and callback function input parameters, see the instructions in the Blueprint Editor or the widget documentation.
lineChart.on('click', () => {
  
});

Update widget style configurations

To update the style configuration of a widget, use the following code.

const lineChart = stage.get('@echarts_echarts-line-category_eqbr7');
lineChart.updateProps({
  // For specific configurable styles, see the widget documentation.
});

Get a global variable

To retrieve a global variable, use the following code.

Important

To obtain the global variable ID, right-click the global variable and copy the ID.

const varA = stage.getVariable('var_khje3');
// View the current value
const value = varA.value;
// Set the variable value
varA.set('newValue');
// Listen for variable changes
varA.onChange((currentValue, oldValue) => {

});

Listen for page events

To listen for page events, use the following code.

// For available events, see the dashboard interface node in the Blueprint Editor.
stage.on('data-update', () => {
  
});

Execute page methods

To execute page methods, use the following code.

// For specific methods, see the dashboard action interface node in the Blueprint Editor.
stage.exec('change-location', { value: 'Zhejiang Province' });

Manually emit page events

To manually emit page events, use the following code.

// Manually emit an event
stage.emit('custom-evt', []);

stage.on('custom-evt', (data) => {
  // data is an empty array
});