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

构建功能块扩展

从 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 - 为扩展程序提供可视化数据。这些数据会根据用户与托管信息中心的互动而自动更新。这些数据类似于为自定义可视化图表提供的数据。

构建响应式扩展程序

运行扩展程序的 iframe 会在父级 Looker 主机窗口大小调整时自动调整大小。这会自动反映在 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} />
  }

Tile SDK 函数和属性

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

下表中列出了可用的函数和属性：

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

功能块 SDK 数据

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

属性	说明
`isExploring`	如果为 true，则表示将图块配置为探索内的可视化图表。
`dashboardId`	正在渲染的图块的信息中心 ID。如果将图块配置为“探索”，系统将不会填充此属性。
`elementId`	正在渲染的图块的元素 ID。如果将图块配置为“探索”，系统将不会填充此属性。
`queryId`	与可视化图表相关联的图块的查询 ID。如果将图块配置为“探索”，系统将不会填充此属性。 `queryId` 是 Looker 探索中内置可视化图表时创建的查询的 ID。不包含任何要应用于信息中心的过滤条件或交叉过滤。为了反映 `QueryResponse` 中显示的数据，需要应用过滤条件和交叉过滤条件，并生成新的查询。因此，可能会有比 `queryId` 更实用的属性。如需了解应用了过滤条件的查询对象，请参阅 `filteredQuery`。
`querySlug`	与可视化图表相关联的图块的查询 slug。如果将图块配置为“探索”，系统将不会填充此属性。 `querySlug` 是 Looker 探索中内置可视化图表时创建的查询的 slug。不包含任何应用于信息中心的过滤条件或交叉过滤。为了反映 `QueryResponse` 中显示的数据，需要应用过滤条件和交叉过滤条件，并生成新的查询。因此，可能会有比 `querySlug` 更实用的属性。如需了解应用了过滤条件的查询对象，请参阅 `filteredQuery`。
`dashboardFilters`	应用到信息中心的过滤条件。如果将图块配置为“探索”，系统将不会填充此属性。
`dashboardRunState`	指示信息中心是否正在运行。如果功能块被配置为“探索”，则状态将为 `UNKNOWN`。出于信息中心性能方面的原因，运行状态可能永远不会显示为正在运行。如果没有其他与查询相关联的图块（包括与扩展程序关联的图块），通常会出现这种情况。如果扩展程序需要确定信息中心是否已运行，则检测 `lastRunStartTime` 中的差异才是可靠的方法。
`isDashboardEditing`	如果为 true，则表示信息中心处于修改状态。如果将图块配置为“探索”，系统将不会填充此属性。
`isDashboardCrossFilteringEnabled`	如果为 true，则会在信息中心内启用交叉过滤。如果将图块配置为“探索”，系统将不会填充此属性。
`filteredQuery`	与与底层信息中心元素相关联的查询 ID 匹配的查询对象，该对象会应用任何在信息中心级别发生的信息中心过滤条件和时区更改。
`lastRunSourceElementId`	触发信息中心上次运行的功能块扩展程序元素的 ID。如果信息中心运行是由信息中心的运行按钮或自动刷新触发的，或者运行是使用嵌入 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`	一个由字段维度信息和表格计算构成的串联数组，其行为类似于维度。