此页面由 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 扩展服务可能需要设置自己的高度，而 tile 扩展服务则不需要。

功能块扩展程序其他 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} />
  }

Tile SDK 函数和属性

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

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

函数或属性	说明
`tileHostData`（媒体资源）	特定于 tile 扩展程序的宿主数据。如需了解详情，请参阅 Tile 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` 是在 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`	字段维度信息和表现得像维度的表计算的串联数组。

使用嵌入 SDK

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

扩展程序可能会最终呈现一个信息中心，而该扩展程序是信息中心中的一个图块。扩展程序框架无法检测到此情况，因此浏览器可能会崩溃。
无法正常呈现图块扩展程序内嵌的内容的 PDF。