建構資訊方塊擴充功能

自 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：啟用後，當使用者編輯資訊主頁，並在點選「Add」按鈕後選取「Extensions」選項時，擴充功能就會顯示在「Extensions」面板中。這類擴充功能負責擷取自己的資料，而非由資訊方塊查詢自動為擴充功能提供資料。

額外的掛載點 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} />
  }

Tile SDK 函式和屬性

資訊方塊 SDK 提供的函式可讓資訊方塊擴充功能與其代管資訊主頁互動。

下表列出可用的函式和屬性：

圖塊 SDK 資料

下表列出可用的資訊方塊 SDK 資料屬性：

Visualization SDK 函式和屬性

下表列出可用的視覺化 SDK 函式和屬性：

視覺化 SDK 資料

可視化 SDK 包含下列項目：

• 視覺化呈現設定資料
• 查詢回應資料

視覺化呈現設定資料

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

查詢回應資料

使用 Embed SDK

我們不建議在資訊方塊擴充功能中使用 Embed SDK，原因如下：

• 擴充功能可能會顯示內含擴充功能的資訊主頁資訊方塊。擴充功能架構無法偵測這項情況，因此瀏覽器可能會當機。
• 無法在圖塊擴充功能中對嵌入內容進行 PDF 算繪。