此页面由 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`	切换交叉过滤条件。在探索中运行时，系统会忽略此调用。

功能块 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。如果信息中心运行是通过信息中心的 Run 按钮或自动刷新触发的，或者是使用嵌入 SDK 触发的，则 ID 将未定义。如果功能块配置为“探索”，系统不会填充此属性。请注意，`lastRunSourceElementId` 可以与当前扩展程序实例的元素 ID 相同。例如，如果扩展程序触发信息中心运行，则在信息中心运行开始和结束时，扩展程序会收到通知。
`lastRunStartTime`	表示上次信息中心运行的开始时间。如果功能块配置为“探索”，系统不会填充此属性。请注意，不应使用报告的开始时间和结束时间来捕获性能指标。
`lastRunEndTime`	表示上次信息中心运行结束时间。如果功能块配置为“探索”，系统不会填充此属性。如果功能块正在运行，系统不会填充此属性。请注意，不应使用报告的开始时间和结束时间来捕获效果指标。
`lastRunSuccess`	指示上次运行信息中心是否成功。如果功能块配置为“探索”，系统不会填充此属性。如果功能块正在运行，系统不会填充此属性。

Visualization 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`	字段维度信息和表计算的串联数组，其行为类似于维度。

使用嵌入 SDK

不建议在功能块扩展程序中使用 Embed SDK，原因如下：

该扩展程序最终可能会呈现包含该扩展程序的功能块的信息中心。扩展程序框架无法检测到这种情况，因此浏览器可能会崩溃。
无法在功能块扩展程序中对嵌入内容进行 PDF 呈现。