嵌入式分析 SDK - 问题

您可以通过不同的方式嵌入问题

• 静态问题。嵌入图表。点击图表没有任何反应。
• 交互式问题。点击图表会显示钻取菜单。
• 查询构建器。嵌入图形化查询构建器，不带预定义查询。

嵌入静态问题

您可以使用 StaticQuestion 组件嵌入静态问题。

该组件具有默认高度，可以使用 height 属性进行自定义。要从父容器继承高度，您可以将 100% 传递给 height 属性。

import React from "react";
import {MetabaseProvider, StaticQuestion} from "@metabase/embedding-sdk-react";

const authConfig = {...}

export default function App() {
    const questionId = 1; // This is the question ID you want to embed

    return (
        <MetabaseProvider authConfig={authConfig}>
            <StaticQuestion questionId={questionId} withChartTypeSelector={false}/>
        </MetabaseProvider>
    );
}

嵌入交互式问题

您可以使用 InteractiveQuestion 组件嵌入交互式问题。

import React from "react";
import {MetabaseProvider, InteractiveQuestion} from "@metabase/embedding-sdk-react";

const authConfig = {...}

export default function App() {
    const questionId = 1; // This is the question ID you want to embed

    return (
        <MetabaseProvider authConfig={authConfig}>
            <InteractiveQuestion questionId={questionId}/>
        </MetabaseProvider>
    );
}

问题属性

将 SQL 参数传递给问题

您可以通过 initialSqlParameters 属性以 {parameter_name: parameter_value} 的格式将参数值传递给使用 SQL 定义的问题。了解更多关于 SQL 参数的信息。

<StaticQuestion questionId={questionId} initialSqlParameters={{ product_id: 50 }} />

自定义交互式问题

默认情况下，嵌入式分析 SDK 为交互式问题提供默认布局，使您可以查看问题、应用筛选和聚合，以及访问查询构建器中的功能。

以下是使用带有默认布局的 InteractiveQuestion 组件的示例

<InteractiveQuestion questionId={95} />

要自定义布局，请在 InteractiveQuestion 组件中使用命名空间组件。例如

<InteractiveQuestion questionId={95}>
  <div
    style={{
      display: "flex",
      flexDirection: "column",
      alignItems: "center",
      justifyContent: "center",
    }}
  >
    <div style={{ display: "grid", placeItems: "center" }}>
      <InteractiveQuestion.Title />
      <InteractiveQuestion.ResetButton />
    </div>
    <div
      style={{
        display: "flex",
        alignItems: "center",
        justifyContent: "flex-start",
        overflow: "hidden",
      }}
    >
      <div style={{ width: "100%" }}>
        <InteractiveQuestion.QuestionVisualization />
      </div>
      <div style={{ display: "flex", flex: 1, overflow: "scroll" }}>
        <InteractiveQuestion.Summarize />
      </div>
    </div>
    <div style={{ display: "flex", flexDirection: "column" }}>
      <InteractiveQuestion.Filter />
    </div>
  </div>
</InteractiveQuestion>

交互式问题组件

这些组件通过 InteractiveQuestion 命名空间提供（例如，<InteractiveQuestion.Filter />）。

* 表示必需属性

InteractiveQuestion.BackButton

返回上一视图的导航按钮。仅当 InteractiveQuestion 提供 onNavigateBack 属性时才呈现。

在底层使用 Mantine ActionIcon 属性，以及：| 属性 | 类型 | 描述 | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.Filter

一组交互式筛选器徽章，允许添加、编辑和删除筛选器。将当前筛选器显示为徽章，并提供“添加另一个筛选器”选项。

InteractiveQuestion.FilterDropdown

Filter 组件的下拉按钮。

InteractiveQuestion.ResetButton

用于重置问题修改的按钮。仅当问题存在未保存的更改时才会显示。

在底层使用 Mantine Button 属性，以及：| 属性 | 类型 | 描述 | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.Title

根据问题的状态显示标题。显示：

• 如果问题已保存，则显示问题的显示名称
• 为即席问题（非原生查询）自动生成的描述
• 对于新问题/原生查询，显示“新问题”作为后备或默认标题

InteractiveQuestion.SaveButton

用于保存问题更改的按钮。仅当问题存在未保存的修改时才启用。

注意：目前，在自定义布局中，SaveButton 必须具有 onClick 处理程序，否则单击按钮将不会执行任何操作。

在底层使用 Mantine Button 属性，以及：| 属性 | 类型 | 描述 | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.Breakout

一组用于管理数据分组（细分）的徽章。

无属性。使用问题上下文进行细分功能。

InteractiveQuestion.BreakoutDropdown

Breakout 组件的下拉按钮。

在底层使用 Popover 属性，除了 onClose、children 和 opened 之外，以及：| 属性 | 类型 | 描述 | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.Summarize

用于添加和管理数据摘要（如计数、总和、平均值）的界面。显示为一组徽章。

无属性。使用问题上下文进行汇总功能。

InteractiveQuestion.SummarizeDropdown

Summarize 组件的下拉按钮。

在底层使用 Popover 属性，除了 onClose、children 和 opened 之外，以及：| 属性 | 类型 | 描述 | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.Editor

高级查询编辑器，提供对问题配置的完全访问权限。包括筛选、聚合、自定义表达式和连接。

替换已弃用的 InteractiveQuestion.Notebook

InteractiveQuestion.EditorButton

用于显示/隐藏 Editor 界面的切换按钮。

替换已弃用的 InteractiveQuestion.NotebookButton

注意：目前，在自定义布局中，EditorButton 必须具有 onClick 处理程序，否则单击按钮将不会执行任何操作。

在底层使用 Mantine ActionIcon 属性，以及：| 属性 | 类型 | 描述 | |——|——|————-| | isOpen | boolean | 编辑器当前是否打开 | | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.QuestionVisualization

主可视化组件，用于将问题结果呈现为图表、表格或其他可视化类型。

InteractiveQuestion.QuestionSettings

用于配置可视化选项（如坐标轴、颜色和格式）的设置面板。

无属性 (props)。使用问题上下文进行设置。

InteractiveQuestion.QuestionSettingsDropdown

包含 QuestionSettings 组件的下拉按钮。

使用 Popover props，但底层除外 onClose 和 opened，以及： | Prop | Type | Description | |——|——|————-| | height | React.CSSProperties[“height”] | 下拉菜单的高度 | | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.ChartTypeSelector

详细的图表类型选择界面，包含推荐的可视化选项。

底层使用 Mantine Stack props，以及： | Prop | Type | Description | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.ChartTypeDropdown

用于选择可视化类型的下拉菜单（条形图、折线图、表格等）。自动更新以显示当前数据的推荐可视化类型。

底层使用 Mantine Menu props，以及： | Prop | Type | Description | |——|——|————-| | className | string | 用于设置组件样式的自定义 CSS 类名 | | style | React.CSSProperties | 应用于组件的内联样式 |

InteractiveQuestion.SaveQuestionForm

用于保存问题的表单，包括标题和描述。保存时

• 对于新问题：调用来自 InteractiveQuestion 的 onCreate 属性 (prop)
• 对于现有问题：调用来自 InteractiveQuestion 的 onSave 属性 (prop)
• 两个回调都接收更新后的问题对象
• 可以通过 onCancel 属性 (prop) 取消表单

交互式问题插件

您可以使用插件为问题添加自定义功能。

mapQuestionClickActions

此插件允许您向交互式问题的点击菜单添加自定义操作。您可以添加和自定义自定义操作的外观和行为。

// You can provide a custom action with your own `onClick` logic.
const createCustomAction = clicked => ({
  buttonType: "horizontal",
  name: "client-custom-action",
  section: "custom",
  type: "custom",
  icon: "chevronright",
  title: "Hello from the click app!!!",
  onClick: ({ closePopover }) => {
    alert(`Clicked ${clicked.column?.name}: ${clicked.value}`);
    closePopover();
  },
});

// Or customize the appearance of the custom action to suit your need.
const createCustomActionWithView = clicked => ({
  name: "client-custom-action-2",
  section: "custom",
  type: "custom",
  view: ({ closePopover }) => (
    <button
      className="tw-text-base tw-text-yellow-900 tw-bg-slate-400 tw-rounded-lg"
      onClick={() => {
        alert(`Clicked ${clicked.column?.name}: ${clicked.value}`);
        closePopover();
      }}
    >
      Custom element
    </button>
  ),
});

const plugins = {
  /**
   * You will have access to default `clickActions` that Metabase renders by default.
   * So you could decide if you want to add custom actions, remove certain actions, etc.
   */
  mapQuestionClickActions: (clickActions, clicked) => {
    return [
      ...clickActions,
      createCustomAction(clicked),
      createCustomActionWithView(clicked),
    ];
  },
};

const questionId = 1; // This is the question ID you want to embed

return (
  <MetabaseProvider authConfig={authConfig} pluginsConfig={plugins}>
    <InteractiveQuestion questionId={questionId} />
  </MetabaseProvider>
);

嵌入可编辑的交互式问题

您可以通过在 InteractiveQuestion 组件上传递 isSaveEnabled 属性 (prop)，使用查询构建器编辑现有问题。

import React from "react";
import {MetabaseProvider, InteractiveQuestion} from "@metabase/embedding-sdk-react";

const authConfig = {...}

export default function App() {
    return (
        <MetabaseProvider authConfig={authConfig}>
            <InteractiveQuestion questionId={1} isSaveEnabled />
        </MetabaseProvider>
    );
}

嵌入查询构建器

使用 CreateQuestion 组件，您可以嵌入查询构建器，而无需预定义问题。

此组件构建于具有命名空间组件的 InteractiveQuestion 组件之上。它与 InteractiveQuestion 共享相同的属性 (props)，但缺少 questionId 属性 (prop) 和传递自定义子组件的能力。

要自定义问题编辑器的布局，请直接使用带有自定义 children 属性 (prop)的 InteractiveQuestion 组件。

import React from "react";
import {MetabaseProvider, CreateQuestion} from "@metabase/embedding-sdk-react";

const authConfig = {...}

export default function App() {
    return (
        <MetabaseProvider authConfig={authConfig}>
            <CreateQuestion />
        </MetabaseProvider>
    );
}