v0.55

嵌入式分析 SDK - 常见问题

嵌入式分析 SDK 仅适用于 Pro 版和 Enterprise 版计划（包括自托管版和 Metabase 云版）。不过，您可以通过使用 API 密钥验证您的嵌入来在本地机器上无许可证地试用 SDK。

有几种不同的方式可以嵌入问题

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

嵌入问题

您可以使用以下问题组件之一嵌入问题

`StaticQuestion`

一个轻量级的问题组件。当您只想显示结果而不允许人们与数据交互时，请使用此组件。

Static question

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

API 参考

示例

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

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
});

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>
  );
}

属性

属性	类型	描述
`className?`	`字符串`	要添加到根元素的自定义类名。
`height?`	`Height`<`string` \| `number`>	指定组件高度的 CSS 尺寸值的数字或字符串
`initialSqlParameters?`	`SqlParameterValues`	SQL 参数的初始值。
`questionId`	`null` \| `SdkQuestionId`	问题的 ID。这可以是 - 访问问题链接时的数字 ID，例如 `http://localhost:3000/question/1-my-question`，其中 ID 为 `1` - 问题对象的 `entity_id` 键。您可以在查看问题时在信息面板中找到问题的实体 ID - `new` 用于显示笔记本编辑器以创建新问题。`isSaveEnabled` 必须为 `true` 才能允许保存问题
`style?`	`CSSProperties`	要添加到根元素的自定义样式对象。
`width?`	`Width`<`string` \| `number`>	指定组件宽度的 CSS 尺寸值的数字或字符串
`withChartTypeSelector?`	`布尔值`	-

`InteractiveQuestion`

当您希望允许人们探索其数据并自定义问题布局时，请使用此组件。

Interactive question

API 参考

示例

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

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
});

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

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

属性

属性	类型	描述
`children?`	`ReactNode`	MetabaseProvider 组件的子元素。
`className?`	`字符串`	要添加到根元素的自定义类名。
`entityTypes?`	`EmbeddingEntityType`[]	一个数组，指定数据选择器中可用的实体类型
`height?`	`Height`<`string` \| `number`>	指定组件高度的 CSS 尺寸值的数字或字符串
`initialSqlParameters?`	`SqlParameterValues`	SQL 参数的初始值。
`isSaveEnabled?`	`布尔值`	是否显示保存按钮。
`onBeforeSave?`	(`question`: `undefined` \| `MetabaseQuestion`, `context`: { `isNewQuestion`: `boolean`; }) => `Promise`<`void`>	在保存之前触发的回调函数。仅当 `isSaveEnabled = true` 时相关
`onRun?`	(`question`: `undefined` \| `MetabaseQuestion`) => `void`	当问题更新时（包括用户在问题编辑器中点击 `Visualize` 按钮时）触发的回调函数
`onSave?`	(`question`: `undefined` \| `MetabaseQuestion`, `context`: { `isNewQuestion`: `boolean`; }) => `void`	当用户保存问题时触发的回调函数。仅当 `isSaveEnabled = true` 时相关
`plugins?`	`MetabasePluginsConfig`	-
`questionId`	`null` \| `SdkQuestionId`	问题的 ID。这可以是 - 访问问题链接时的数字 ID，例如 `http://localhost:3000/question/1-my-question`，其中 ID 为 `1` - 问题对象的 `entity_id` 键。您可以在查看问题时在信息面板中找到问题的实体 ID - `new` 用于显示笔记本编辑器以创建新问题。`isSaveEnabled` 必须为 `true` 才能允许保存问题
`style?`	`CSSProperties`	要添加到根元素的自定义样式对象。
`targetCollection?`	`SdkCollectionId`	保存问题的集合。这将从保存模式中隐藏集合选择器。仅适用于交互式问题。
`title?`	`SdkQuestionTitleProps`	确定是否显示问题标题，并允许显示自定义标题而非默认问题标题。默认显示。仅在使用默认布局时适用于交互式问题。
`width?`	`Width`<`string` \| `number`>	指定组件宽度的 CSS 尺寸值的数字或字符串
`withChartTypeSelector?`	`布尔值`	确定是否显示图表类型选择器和相应的设置按钮。仅在使用默认布局时相关。
`withDownloads?`	`布尔值`	启用在交互式问题中下载结果的功能。
`withResetButton?`	`布尔值`	确定是否显示重置按钮。仅在使用默认布局时相关。

使用 `initialSqlParameters` 将 SQL 参数传递给 SQL 问题

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

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

initialSqlParameters 不能与使用查询构建器构建的问题一起使用。

自定义交互式问题

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

以下是使用 InteractiveQuestion 组件及其默认布局的示例

<InteractiveQuestion questionId={95} />

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

<div
  className="App"
  style={{
    width: "100%",
    maxWidth: "1600px",
    height: "800px",
    margin: "0 auto",
  }}
>
  <MetabaseProvider authConfig={authConfig} theme={theme}>
    <InteractiveQuestion questionId={95}>
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          justifyContent: "center",
          width: "100%",
        }}
      >
        <div style={{ display: "grid", placeItems: "center", width: "100%" }}>
          <InteractiveQuestion.Title />
          <InteractiveQuestion.ResetButton />
        </div>
        <div
          style={{
            display: "flex",
            alignItems: "center",
            justifyContent: "flex-start",
            overflow: "hidden",
            width: "100%",
          }}
        >
          <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", width: "100%" }}
        >
          <InteractiveQuestion.Filter />
        </div>
      </div>
    </InteractiveQuestion>
  </MetabaseProvider>
</div>

交互式问题组件

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

API 参考

交互式问题插件

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

`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={false}

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

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
});

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

嵌入查询构建器以创建新问题

Query builder

您可以通过将 questionId="new" 属性传递给 InteractiveQuestion 组件来嵌入查询构建器以创建新问题。您可以使用 children 属性来自定义创建新问题的布局。

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

const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://your-metabase.example.com",
});

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

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

阅读其他 Metabase 版本的文档。

商业智能

嵌入式分析

文档

学习

分析

嵌入

管理

其他资源

嵌入式分析 SDK - 常见问题

嵌入问题

`StaticQuestion`

API 参考

示例

属性

`InteractiveQuestion`

API 参考

示例

属性

使用 `initialSqlParameters` 将 SQL 参数传递给 SQL 问题

自定义交互式问题

交互式问题组件

API 参考

交互式问题插件

`mapQuestionClickActions`

阻止用户保存对 `InteractiveQuestion` 的更改

嵌入查询构建器以创建新问题

这有帮助吗？

感谢您的反馈！

商业智能

嵌入式分析

文档

学习

分析

嵌入

管理

其他资源

嵌入式分析 SDK - 常见问题

嵌入问题

StaticQuestion

API 参考

示例

属性

InteractiveQuestion

API 参考

示例

属性

使用 initialSqlParameters 将 SQL 参数传递给 SQL 问题

自定义交互式问题

交互式问题组件

API 参考

交互式问题插件

mapQuestionClickActions

阻止用户保存对 InteractiveQuestion 的更改

嵌入查询构建器以创建新问题

这有帮助吗？

感谢您的反馈！

`StaticQuestion`

`InteractiveQuestion`

使用 `initialSqlParameters` 将 SQL 参数传递给 SQL 问题

`mapQuestionClickActions`

阻止用户保存对 `InteractiveQuestion` 的更改