Embedded JS SDK API

src

Defines the source for an embedded page. Its type is EmbedSrcUnion. The following table describes its parameters.

Sample code

<EmbedComponent
      src={
        origin: 'xxx',  // The host for accessing Quick BI
        page: EmbedRouteKey.dashboardEdit,  // The EmbedRouteKey for the dashboard edit page
        // Query parameters for the Quick BI dashboard page
        search: {
          workspaceId: 'xxx',  // Workspace ID
          id: 'xxx',  // Works ID
        }
      }
    />

Feature

An embedded feature is a configuration that temporarily controls display properties, such as UI component visibility and display text. For example, you can hide a page header. This configuration is of type EmbedFeatureIntersect and has a three-level structure: routing > feature module > feature configuration item. The key at the routing level is EmbedRouteKey, which defines the feature's scope. The following code shows an example.

feature: {
  [routing key]: {
    [functional module]: {
      [feature configuration key]: value
    }
  }
}

Some features use a two-layer structure: routing > feature configuration item. This structure controls whether the module for the corresponding routing is displayed, as shown in the sample code below.

feature: {
  [routing key]: {
    [feature configuration key]: value
  }
}

You can configure features for multiple routes simultaneously. The table below lists the route parameters.

Sample code

<EmbedComponent 
  feature={{
    [EmbedRouteKey.homeRoot]: {
      // workbench...
    },
    [EmbedRouteKey.dashboardEdit]: {
      // dashboard edit page...
    },
    // ...
  }} 
/>

EmbedRouteKey.homeRoot

As the root page for Home, homeRoot's feature configurations apply to all its child pages. For example, hiding the header on the homeRoot page also hides it on all child pages, such as the workPlatform workbench, workspace workspace, templateRoot template marketplace, view My Dashboard, subscriptionManage subscription management, and monitorManage monitoring and alerts. The scope of this property is as follows.

• header: Settings for the home page header.

• header.show

  • type: boolean

  • default value: true

  • description: Shows or hides the header navigation on the home page.

EmbedRouteKey.workspace

The control scope for each attribute in the workspace feature configuration is as follows.

• header: Configures the workspace header.

• header.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the workspace header.

• goBack: Configures the 'Back to Workbench' feature.

• goBack.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the 'Back to Workbench' control.

• goBack.text

  • Type: string

  • Default: 'Back to Workbench'

  • Description: Specifies the text for the 'Back to Workbench' control.

• switchWorkspace: Configures the workspace switching feature.

• switchWorkspace.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the workspace switching control.

• breadcrumb: Configures the workspace breadcrumb.

• breadcrumb.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the breadcrumb.

• workspaceManageNavLabel: Configures the 'Space Management' navigation label.

• workspaceManageNavLabel.text

  • Type: string

  • Default: 'Space Management'

  • Description: Specifies the text for the 'Space Management' navigation label.

• sideNav: Configures the workspace side navigation.

• sideNav.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the side navigation.

EmbedRouteKey.workPlatform

The attributes in the workbench feature configuration control the following.

• userInfo: Configures the user information feature on the workbench page.

• userInfo.show

  • Type: boolean

  • Default: true

  • Description: Controls whether the user information is displayed.

• myWorkSpace: Configures the My Workspace feature on the workbench page.

• myWorkSpace.text

  • Type: string

  • Default: 'My Workspace'

  • Description: Specifies the text for the My Workspace section.

EmbedRouteKey.monitorManage

This section describes the feature configuration for the Monitoring and Alarm Management page and the scope of each attribute.

• gotoDashboard: Configures the "Go to dashboard" button on the monitoring and alerting management page.

• gotoDashboard.show

  • type: boolean

  • default value: true

  • description: Specifies whether to display the "Go to dashboard" button.

EmbedRouteKey.dashboardEdit

The following properties configure the features on the dashboard edit page.

• goBack: Configuration for the Go Back button.

• goBack.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the Go Back button.

• publish: Configuration for the Publish button.

• publish.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the Publish button.

• saveAs: Configuration for the Save As button.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default: 'menu'

  • Description: Controls the group for the Save As button. A value of 'menu' places it in the more menu, while 'state' places it in the save and publish status area.

• saveAs.order

  • Type: number

  • Default: -1

  • Description: Controls the order of the Save As button within its button group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default: 'default'

  • Description: Controls the style of the Save As button. This setting applies only when saveAs.group is set to 'state'.

• share: Configuration for the Share button.

• share.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the Share button.

• offline: Configuration for the Offline button.

• offline.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the Offline button.

• save: Configuration for the Save button.

• save.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the Save button.

• switchDataset: Configuration for the switch dataset feature.

• switchDataset.disabled

  • Type: boolean

  • Default: false

  • Description: Specifies whether to disable the switch dataset feature on the dashboard edit page.

EmbedRouteKey.workbookEdit

The following properties configure the features of the spreadsheet edit page.

• goBack: Configures the back button.

• goBack.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the back button.

• publish: Configures the publish button.

• publish.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the publish button.

• saveAs: Configures the save as button.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default value: 'menu'

  • Description: Specifies the location of the save as button. A value of 'menu' places the button in the more menu, and 'state' places it in the save and publish status area.

• saveAs.order

  • Type: number

  • Default value: -1

  • Description: Specifies the display order of the save as button within its group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default value: 'default'

  • Description: Specifies the style of the save as button. This property only applies if the group is 'state'.

• offline: Configures the unpublish button.

• offline.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the unpublish button.

• save: Configures the save button.

• save.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the save button.

• switchDataset: Configures the switch dataset button.

• switchDataset.disabled

  • Type: boolean

  • Default value: false

  • Description: Specifies whether to disable the switch dataset button on the spreadsheet edit page.

EmbedRouteKey.screenEdit

This topic describes the properties for feature configuration on the dashboard editing page.

• goBack: Configures the Back button properties.

• goBack.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the Back button.

• publish: Configures the Publish button properties.

• publish.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the Publish button.

• saveAs: Configures the Save As button properties.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default value: 'menu'

  • Description: Specifies the location of the Save As button. A value of 'menu' places the button in the More menu, while 'state' places it in the save/publish status area.

• saveAs.order

  • Type: number

  • Default value: -1

  • Description: Specifies the display order of the Save As button within its button group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default value: 'default'

  • Description: Specifies the style of the Save As button. This property applies only when the button belongs to the 'state' group.

• share: Configures the Share button properties.

• share.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the Share button.

• offline: Configures the Offline button properties.

• offline.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the Offline button.

• save: Configures the Save button properties.

• save.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the Save button.

• switchDataset: Configures the switch dataset feature.

• switchDataset.disabled

  • Type: boolean

  • Default value: false

  • Description: Specifies whether to disable the switch dataset feature on the dashboard editing page.

EmbedRouteKey.analysisEdit

The following properties configure features on the ad-hoc analysis edit page.

• goBack: Configures the back button.

• goBack.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the back button.

• publish: Configures the publish button.

• publish.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the publish button.

• saveAs: Configures the save as button.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default value: 'menu'

  • Description: Specifies the group for the save as button. A value of 'menu' places the button in the more menu, while 'state' places it in the save and publish status area.

• saveAs.order

  • Type: number

  • Default value: -1

  • Description: Controls the order of the save as button within the button group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default value: 'default'

  • Description: Controls the style of the save as button. This property applies only when the button is in the 'state' group.

• save: Configures the save button.

• save.show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the save button.

• switchDataset: Configures the switch dataset feature.

• switchDataset.disabled

  • Type: boolean

  • Default value: false

  • Description: Enables or disables the switch dataset feature on the ad hoc analysis edit page.

EmbedRouteKey.downloadEdit

This topic describes the feature configuration and the controls for attributes on the self-service data retrieval edit page.

• goBack: Configures the back button.

• goBack.show

  • Type: boolean

  • Default: true

  • Description: Specifies whether the back button is displayed.

• saveAs: Configures the save as button.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default: 'menu'

  • Description: Specifies the group that contains the save as button. A value of 'menu' places it in the more menu, and 'state' places it in the save and publish status area.

• saveAs.order

  • Type: number

  • Default: -1

  • Description: Sets the display order of the save as button within its button group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default: 'default'

  • Description: Sets the style of the save as button. This property only takes effect when saveAs.group is set to 'state'.

• save: Configures the save button.

• save.show

  • Type: boolean

  • Default: true

  • Description: Specifies whether the save button is displayed.

• switchDataset: Configures the switch dataset functionality.

• switchDataset.disabled

  • Type: boolean

  • Default: false

  • Description: Specifies whether the switch dataset functionality is disabled on the self-service data retrieval edit page.

EmbedRouteKey.formEdit

This section details the feature configuration for the data entry edit page and the scope of its attributes.

• goBack: Settings for the back button.

• goBack.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the back button.

• save: Settings for the save button.

• save.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the save button.

EmbedRouteKey.etlEdit

The feature configuration on the data preparation edit page controls the scope of each property as follows.

• goBack: Settings for the back button.

• goBack.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the back button.

• publish: Settings for the publish button.

• publish.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the publish button.

• offline: Settings for the unpublish button.

• offline.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the unpublish button.

• save: Settings for the save button.

• save.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the save button.

EmbedRouteKey.datasetEdit

On the dataset edit page, the feature configuration properties are as follows.

• goBack: Back button settings.

• goBack.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the back button.

• saveAs: Save as button settings.

• saveAs.group

  • Type: 'state' | 'menu'

  • Default value: 'menu'

  • Description: Specifies the location of the save as button. A value of 'menu' places the button in the more menu, while 'state' places it in the save and publish status area.

• saveAs.order

  • Type: number

  • Default value: -1

  • Description: Specifies the display order of the save as button within its button group.

• saveAs.type

  • Type: 'default' | 'primary'

  • Default value: 'default'

  • Description: Specifies the style of the save as button. This property applies only when the button is in the 'state' group.

• save: Save button settings.

• save.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the save button.

EmbedRouteKey.workbookFormTask

The following attributes configure the features on the spreadsheet approval page.

• header: Settings for the header on the spreadsheet approval page.

• header.show

  • type: boolean

  • default value: true

  • description: Shows or hides the page header navigation.

• goBack: Settings for the back button.

• goBack.show

  • type: boolean

  • default value: true

  • description: Shows or hides the back button.

EmbedRouteKey.dashboardView/EmbedRouteKey.dashboardPublicView

The feature configurations and property settings for the dashboard preview page (dashboardView) and the dashboard public page (dashboardPublicView) are as follows.

• title: Configures the dashboard title.

• title.show

  • type: boolean

  • default value: false

  • description: Shows or hides the dashboard title. By default, the title is hidden when the dashboard is embedded.

• miniMenu: Configures the dashboard's mini menu.

• miniMenu.show

  • type: boolean

  • default value: true

  • description: Shows or hides the dashboard's mini menu.

• cardMenu: Configures the chart card menu.

• cardMenu.show

  • type: boolean

  • default value: true

  • description: Shows or hides the chart card menu.

• highlight: Configures the card highlight feature.

• highlight.componentIds

  • type: string[]

  • description: The IDs of the cards to highlight.

    Note

    You can get componentIds from the Query the data lineage of a data product open API or the page's /api/v2/dashboard endpoint.

EmbedRouteKey.subscriptionManage

The feature configuration on the subscription management page controls the following attributes.

• header: Configures the header of the subscription management page.

• header.show

  • type: boolean

  • default value: true

  • description: Specifies whether to display the header of the subscription management page. This property takes precedence over EmbedRouteKey.homeRoot.show.

EmbedRouteKey.subscriptionTask

The feature configuration on the subscription task page includes the following properties.

• show

  • type: boolean

  • Default value: true

  • description: This second-level property controls whether the subscription task page is displayed.

EmbedRouteKey.sendRecord

The configuration of the send log page feature has the following properties.

• show

  • type: boolean

  • default value: true

  • description: Controls the visibility of the send log page.

EmbedRouteKey.orgAdmin

This topic describes the features of the organization management page and the scope of each attribute.

• header: Configures the header of the organization management page.

• header.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the header of the organization management page. This property has a higher priority than EmbedRouteKey.homeRoot.show.

• sideNav: Configures the side navigation of the organization management page.

• sideNav.show

  • Type: boolean

  • Default value: true

  • Description: Specifies whether to display the side navigation of the organization management page.

EmbedRouteKey.userMemberManage

The member management page has the following features.

• show

  • type: boolean

  • default value: true

  • description: This two-tier feature shows or hides the member management page.

EmbedRouteKey.userGroupManage

The user group management page has the following features.

• show

  • Type: boolean

  • Default value: true

  • Description: Shows or hides the user group management page.

EmbedRouteKey.userTagManage

The User Tag Management page has the following features.

• show

  • Type: boolean

  • Default value: true

  • Description: This two-tier property shows or hides the user tag management page.

EmbedRouteKey.userTagDetailManage

The user tag page includes the following properties.

• show

  • Type: boolean

  • Default: true

  • Description: Controls whether the user tag page is displayed. This is a second-level feature.

EmbedRouteKey.tagManage

The tag management page offers the following features.

• show

  • type: boolean

  • default value: true

  • description: A two-level property that toggles the visibility of the tag management page.

EmbedRouteKey.userRoleManage

The Role Management page has the following properties.

• show

  • type: boolean

  • default value: true

  • description: Specifies whether to display the role management page.

EmbedRouteKey.copilotPage

The Intelligent Advisor page has the following properties.

• header: Configures the page header.

• header.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the page header. This property has a higher priority than EmbedRouteKey.homeRoot.header.show.

• sideNav: Configures the side navigation.

• sideNav.show

  • Type: boolean

  • Default: true

  • Description: Shows or hides the side navigation.

• theme: Configures the page theme.

• theme.primaryColor

  • Type: string

  • Default: #2F66FF

  • Description: Sets the page's primary color.

• theme.chartColorSeries

  • Type: string[]

  • Default: [

    '#4080FF',

    '#3DC8DC',

    '#A191F2',

    '#FFB77A',

    '#7C7CA6',

    '#33CC99',

    '#217CCC',

    '#FF80AA',

    '#008770',

    '#D1876F',

    '#4798B3',

    '#C896FA']

  • Description: Sets the color series for charts.

EmbedRouteKey.copilotPageQChat

The Ask Q page inherits all features from EmbedRouteKey.copilotPage with higher precedence and includes additional properties.

• dataInterpretation: Settings for the data interpretation feature in Intelligent Query.

• dataInterpretation.show

  • type: boolean

  • default value: true

  • description: Shows or hides the data interpretation feature on the Intelligent Query page.

EmbedRouteKey.copilotPageQReport

The Copilot report page includes all the features of EmbedRouteKey.copilotPage and has a higher priority.

EmbedRouteKey.wordAgentEdit

The Q Report edit page has the following properties.

• goBack: Settings for the back button on the Q Report.

• goBack.show

  • type: boolean

  • default value: true

  • description: Shows or hides the back button on the Q Report edit page.

Events

An object for configuring listeners for events on the embedded page. The host system can bind to these events to capture user actions and respond accordingly.

The following events are currently available:

type EmbedEventBeforePageChange = {
  type: EmbedEventType['before-page-change-event'],
  payload: {
    src: EmbedSrcUnion,
    target: '_blank' | '_self'
  }
}

embedClient.on(EmbedEventType['before-page-change-event'], async (event: EmbedEventBeforePageChange) => {
  // Block navigation to a new page
  if (event.payload.target === '_blank') {
    return false;
  }
})

type EmbedEventAfterComponentRendered = {
  type: EmbedEventType['after-component-rendered-event'],
  payload: ComponentProps
}

export interface ComponentProps {
  status?: 'success' | 'error';
  error?:
    | ComponentError
    | ComponentConfigError
    | ComponentNoPermissionError
    | ComponentDataMaskError
    | ComponentNoDataError
    | ComponentRenderError;
  pageConfig?: ComponentPageConfig;
  id: string;
  data: DataCell[][];
  dataConfig: AreaModel[];
  viewConfig: ComponentPropsViewConfig;
  advancedConfig: object;
  globalConfig: ComponentPropsGlobalConfig;
  cubeConfig?: ComponentPropsCubeConfig[];
  sql?: string[];
}

Action

An action is a configuration object that allows the host system to programmatically trigger behaviors on the embedded page, such as page navigation or feature updates.

The following actions are available: embedNavigate, setEmbedFeature, and scrollToComponentById.

enum EmbedActionType {
  /** Navigates to a route. */
  embedNavigate = 'embedNavigate',
  /** Updates an embedded feature. */
  setEmbedFeature = 'setEmbedFeature',
}

/** An action to programmatically trigger a route navigation. */
type EmbedActionNavigate = {
  type: EmbedActionType.embedNavigate;
  payload: {
    src: EmbedSrcUnion;
  }
}

/** An action to programmatically update features. */
type EmbedActionSetFeature = {
  type: EmbedActionType.setEmbedFeature;
  payload: EmbedFeatureIntersect;
}
  

embedNavigate

• Navigates the embedded page to a specified route.

• payload.src: The source information of the target route. For details, see src.

  type EmbedActionNavigate = {
    type: EmbedActionType.embedNavigate;
    payload: {
      src: EmbedSrcUnion;
    }
  }

• Example

  // Navigates to the dashboard edit page.
  embedClient.dispatch({
    type: EmbedActionType.embedNavigate,
    payload: {
      src: {
        origin: 'https://bi.aliyun.com',
        page: EmbedRouteKey.dashboardEdit,
        search: {
          workspaceId: 'xx',
          id: 'xx'
        },
      },
    },
  });

setEmbedFeature

• Updates the embedded feature configuration on the embedded page.

• payload: The embedded feature configuration for various pages. For details, see feature.

  type EmbedActionSetFeature = {
    type: EmbedActionType.setEmbedFeature;
    payload: EmbedFeatureIntersect;
  }

• Example

  embedClient.dispatch({
    type: EmbedActionType.setEmbedFeature,
    payload: {
      // Hides the Back button on the dashboard edit page.
      [EmbedRouteKey.dashboardEdit]: {
        goBack: {
          show: goBack,
        },
      },
    },
  });

scrollToComponentById

• Scrolls the embedded page to a specified chart component on a dashboard preview or public page.

• payload

  • payload.id: The ID of the card to scroll to.

  • payload.position: The position of the card after scrolling.

type EmbedActionScrollToComponentById = {
  type: EmbedActionType.scrollToComponentById,
  payload: {
    id: string;
    position: 'start' | 'center' | 'end' | 'nearest'
  }
}

Example

embedClient.dispatch({
  type: EmbedActionType.scrollToComponentById,
  payload: {
    // Scrolls the dashboard preview page to the component with this ID.
    id: 'scroll to this component id',
    // The card will be centered on the screen after scrolling.
    position: 'center',
  },
});

EmbedClient

You can use the following methods of the EmbedClient class to customize your embedded page.

constructor

Creates a new client instance.

• Type: (src: EmbedSrcUnion, option?: Partial<PostMessengerParam>) => void

• Parameters

  • src: The embed source, which specifies the page to embed. For more information, see src.

  • option: Client configuration options.

    • option.connectTimeout: The client connection timeout in milliseconds.

    • option.messageTimeout: The message timeout in milliseconds.

• Sample code

  const embedClient = new EmbedClient({
    src: {
      origin: 'https://bi.aliyun.com',
      page: EmbedRouterKey.dashboardView,
    },
    option: { connectTimeout: 5000 }
  });

render

Renders the client instance to a specified DOM container.

• Type: (container: HTMLIframeElement) => HTMLIFrameElement

• Parameter

  • container: The DOM element in which to render the embedded page.

• Sample code

  embedClient.render(document.getElementById('embed-container'));

destroy

Destroys the client instance and removes the embedded page.

• Type: () => void

• Sample code

  embedClient.destroy();

dispatch

Dispatches an action to the embedded page.

• Type: (action: EmbedAction) => Promise<T>

• Parameter

  • action: The embed action to dispatch. For more information, see action.

• Sample code

  // Hide the Back button on the dashboard edit page
  embedClient.dispatch({
    type: EmbedActionType.setEmbedFeature,
    payload: {
      [EmbedRouteKey.dashboardEdit]: {
        goBack: {
          show: goBack,
        },
      },
    },
  });

on

Registers an event listener for a specific embed event.

• Type: on(eventType: EmbedEventType, listener: (event: T) => Promise<T>)

• Parameters

  • eventType: The event type, EmbedEventType.

  • listener: The callback function for the event. This function can be asynchronous. Its parameters and return values depend on the event type. For more information, see events.

• Sample code

  // Before-page-change event handler
  async handler(event: EmbedEventBeforePageChange) => {
    return false;
  }
  
  // Register the event listener
  embedClient.on(EmbedEventType['before-page-change-event'], handler); 

off

Unregisters an event listener for a specific embed event.

• Type: off(eventType: EmbedEventType, listener).

• Parameters

  • eventType: The event type, EmbedEventType.

  • listener: The callback function to unregister. This must be the same function reference that was passed to on.

• Sample code

  async function handler(payload) {}
  
  // Unregister the event listener
  embedClient.off(EmbedEventType['before-page-change-event'], handler);

EmbedComponent

In React or Vue frameworks, you can embed a page by rendering the EmbedComponent component. The properties (props) of this component are of the types shown below. Updating these properties automatically triggers the component to update and render the latest page.

interface EmbedComponentCommonProps {
  /** The class name for the container. */
  className?: string;
  /** The styles for the container. */
  style?: CSSProperties;
  /** The embed source information. */
  src: EmbedSrcUnion;
  /** The initial embedded feature configuration. */
  feature?: EmbedFeatureIntersect;
  /** The initial embedded event listeners. */
  events?: EmbedEventListenerUnion;
}

The following table describes these properties.