请注意，您正在查看 Looker 文档。如需查看 Looker Studio 文档，请访问 https://support.google.com/looker-studio。

此页面由 Cloud Translation API 翻译。

构建功能块扩展程序

从 Looker 24.0 开始，您可以开发可在信息中心的功能块中运行的扩展程序。支持以图块或可视化图表形式运行的扩展程序可以在信息中心处于修改模式时添加，也可以作为“探索”中的可视化图表保存到信息中心。您还可以在 LookML 信息中心中将扩展程序配置为功能块。

以下是可用作信息中心功能块的扩展程序示例：

图块可视化图表扩展程序显示了如何使用扩展程序框架构建自定义可视化图表。
功能块 SDK 扩展会显示特定于功能块扩展程序的可用 API 方法。

将 Looker Extension SDK 与功能块扩展程序搭配使用

功能块扩展程序需要在 LookML 项目清单文件中定义 mount_points 参数，才能将扩展程序作为图块加载到信息中心。与功能块扩展相关的 mount_points 有两种类型：

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

dashboard_vis - 启用后，该扩展程序将显示在“探索”的可视化选项中，您可以在其中选择该扩展程序作为可视化图表，并将其保存为信息中心功能块。运行信息中心时，信息中心会执行与功能块相关联的查询，并向扩展程序提供数据。这与自定义可视化图表的工作原理类似。自定义可视化图表与在已启用 dashboard_vis 的信息中心功能块中运行的扩展程序之间的主要区别在于，扩展程序可以调用 Looker API。
dashboard_tile - 启用后，附加信息将显示在用户修改信息中心时所显示的附加信息面板中，并且在点击添加按钮后选择附加信息选项。此类扩展程序负责检索自己的数据，而不是让功能块查询自动向扩展程序提供数据。

另一个装载点 standalone 会导致该扩展程序显示在 Looker 主菜单的应用部分下。一个扩展程序可以定义多个装载点。在运行时，系统会通知扩展程序其挂载方式，扩展程序可以据此调整其行为。例如，standalone 扩展程序可能需要设置自己的高度，而功能块扩展程序则不需要。

功能块扩展附加 API

在运行时，功能块扩展会提供额外的 API 和数据。这些信息是从扩展程序上下文获取的：

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

tileSDK - 提供特定于功能块的功能，以允许扩展程序与 Looker 信息中心主机互动。例如，允许扩展程序显示和清除错误消息。
tileHostData - 向扩展程序提供功能块数据。系统会根据与托管信息中心的互动自动更新数据。例如 isDashboardEditing 指示器。
visualizationSDK - 提供特定于可视化的功能，以允许扩展程序与 Looker 信息中心主机进行交互。updateRowLimit 函数就是一个示例。
visualizationData - 向扩展程序提供可视化数据。这些数据会根据您与托管信息中心的互动而自动更新。这些数据与向自定义可视化图表提供的数据类似。

构建响应式扩展程序

随着父级 Looker 主机窗口的大小调整，扩展程序运行的 iframe 也会自动调整大小。该操作会自动反映在 iframe 内容窗口中。iframe 组件没有任何内边距或外边距，因此应由扩展程序提供自己的内边距和外边距，使其看起来与 Looker 应用保持一致。对于独立的附加信息，由附加信息控制其高度。对于在信息中心功能块或“探索”可视化图表中运行的扩展程序，iframe 内容窗口将自动设置为 iframe 提供的高度。

渲染注意事项

请务必注意，以 PDF 或图片形式下载信息中心时，系统会呈现图块扩展。渲染程序希望功能块在渲染完成时通知它。如果不执行此操作，渲染程序将停止响应。以下示例展示了如何通知渲染程序功能块已渲染。

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

渲染时还应停用动画。在下面的示例中，渲染时关闭了动画配置：

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

功能块 SDK 函数和属性

功能块 SDK 提供了一些函数，可让功能块扩展程序与其托管信息中心进行交互。

可用函数和属性如下表所示：

函数或属性	说明
`tileHostData`（属性）	特定于功能块扩展程序的托管数据。如需了解详情，请参阅功能块 SDK 数据部分。
`addError`	被调用后，信息中心或“探索”会在可视化图表下方显示错误消息。
`clearError`	调用此方法后，信息中心或“探索”部分会隐藏显示在可视化图表下方的所有错误消息。
`openDrillMenu`	对于可视化扩展程序，此调用将打开深入分析菜单。如果扩展程序不是图块扩展程序可视化，系统会忽略此调用。
`runDashboard`	运行当前信息中心。在“探索”中运行的某个功能块可视化扩展程序会忽略此调用。
`stopDashboard`	停止正在运行的信息中心。在“探索”中运行的某个功能块可视化扩展程序会忽略此调用。
`updateFilters`	更新当前信息中心或“探索”中的过滤条件。
`openScheduleDialog`	打开时间安排对话框。在“探索”中运行时，系统会忽略此调用。
`toggleCrossFilter`	切换交叉过滤条件。在探索中运行时，系统会忽略此调用。

Tile SDK 数据

可用的功能块 SDK 数据属性显示在下表中：

属性	说明
`isExploring`	如果为 true，表示功能块正在配置为“探索”中的可视化图表。
`dashboardId`	所呈现图块的信息中心 ID。如果图块被配置为“探索”，系统不会填充此属性。
`elementId`	要渲染的功能块的元素 ID。如果图块被配置为“探索”，系统不会填充此属性。
`queryId`	正在渲染的功能块的查询 ID（如果与可视化相关联）。如果功能块配置为“探索”，系统不会填充此属性。 `queryId` 是在 Looker 探索中内置可视化图表时创建的查询的 ID。不包含任何可应用于信息中心的过滤条件或交叉过滤。为了反映 `QueryResponse` 中显示的数据，您需要应用过滤条件和交叉过滤条件，并生成新的查询。因此，可能有比 `queryId` 更实用的属性。如需查看已应用过滤条件的查询对象，请参阅 `filteredQuery`。
`querySlug`	如果正在渲染的功能块与可视化图表相关联，则其查询 slug。如果图块被配置为“探索”，系统不会填充此属性。 `querySlug` 是查询的 Slug，而该查询在 Looker 探索中内置了可视化功能时创建。它不包含任何已应用于信息中心的过滤条件或交叉过滤。为了反映 `QueryResponse` 中显示的数据，您需要应用过滤条件和交叉过滤条件，并生成新的查询。因此，可能有比 `querySlug` 更实用的属性。如需查看已应用过滤条件的查询对象，请参阅 `filteredQuery`。
`dashboardFilters`	应用于信息中心的过滤条件。如果图块被配置为“探索”，系统不会填充此属性。
`dashboardRunState`	指示信息中心是否正在运行。如果功能块配置为“探索”，状态将为 `UNKNOWN`。出于信息中心性能方面的原因，运行状态可能永远不会显示为正在运行。如果没有与查询相关联的其他功能块（包括与扩展程序相关联的功能块），通常就会出现这种情况。如果扩展程序需要确切知道信息中心是否已运行，检测 `lastRunStartTime` 中的差异是一种可靠的方法。
`isDashboardEditing`	如果为 true，则表示信息中心正在修改中。如果图块被配置为“探索”，系统不会填充此属性。
`isDashboardCrossFilteringEnabled`	如果值为 true，则信息中心会启用交叉过滤。如果功能块配置为“探索”，系统不会填充此属性。
`filteredQuery`	一个查询对象，它与查询 ID 匹配，该查询 ID 与底层信息中心元素相关联，该元素应用了在信息中心级别进行的任何信息中心过滤条件和时区更改。
`lastRunSourceElementId`	触发上次运行信息中心的图块扩展元素的 ID。如果信息中心运行是由信息中心的运行按钮或autorefresh触发的，或者运行是使用嵌入 SDK 触发的，则该 ID 将未定义。如果功能块配置为“探索”，系统不会填充此属性。请注意，`lastRunSourceElementId` 可以与当前扩展程序实例的元素 ID 相同。例如，如果扩展程序触发信息中心运行，则在信息中心运行开始和结束时，扩展程序会收到通知。
`lastRunStartTime`	表示信息中心上次运行开始时间。如果图块被配置为“探索”，系统不会填充此属性。请注意，不应使用报告的开始时间和结束时间来捕获性能指标。
`lastRunEndTime`	表示上次信息中心运行结束时间。如果功能块配置为“探索”，系统不会填充此属性。如果功能块正在运行，系统不会填充此属性。请注意，报告的开始时间和结束时间不应用于捕获效果指标。
`lastRunSuccess`	指示上次运行信息中心是否成功。如果图块被配置为“探索”，系统不会填充此属性。如果图块正在运行，系统将不会填充此属性。

可视化 SDK 函数和属性

下表显示了可用的可视化 SDK 函数和属性：

函数或属性	说明
`visualizationData`（媒体资源）	可视化图表（`visConfig` 和 `queryResponse` 数据的组合）。
`visConfig`（媒体资源）	可视化图表配置数据：测量配置维度配置表计算数据透视配置可视化图表配置这些属性用于自定义“探索”中的可视化图表的外观和风格。
`queryResponse`（媒体资源）	查询的响应数据
`configureVisualization`	为扩展程序可视化设置默认配置。此配置将在“探索”可视化编辑器中呈现。此方法应仅调用一次。
`setVisConfig`	更新可视化图表配置。
`updateRowLimit`	更新查询行数限制。

可视化 SDK 数据

该可视化 SDK 包含以下内容：

可视化配置数据
查询响应数据

可视化图表配置数据

属性	说明
`queryFieldMeasures`	测量信息
`queryFieldDimensions`	维度信息
`queryFieldTableCalculations`	表计算信息
`queryFieldPivots`	数据透视信息
`visConfig`	可视化配置数据。此配置应与默认配置合并，并应用于扩展程序呈现的可视化图表。

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

查询响应数据

属性	说明
`data`	行数据的数组
`fieldMeasures`	现场测量信息。
`fieldDimensions`	字段维度信息。
`fieldTableCalculations`	字段表计算信息。
`fieldPivots`	字段透视信息。
`fieldMeasureLike`	字段测量信息和表计算的串联数组（行为类似于测量）。
`fieldDimensionLike`	字段维度信息和表计算的串联数组，其行为类似于维度。