本頁面由 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：啟用後，當使用者編輯資訊主頁，並在點選「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 提供的函式可讓資訊方塊擴充功能與其代管資訊主頁互動。

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

函式或屬性	說明
`tileHostData` (資源)	代管資訊，具體取決於資訊方塊擴充功能。詳情請參閱「Tile SDK 資料」一節。
`addError`	呼叫時，資訊主頁或「探索」會在視覺化呈現下方顯示錯誤訊息。
`clearError`	在呼叫時，資訊主頁或探索會隱藏顯示在圖表下方的任何錯誤訊息。
`openDrillMenu`	對於視覺化擴充功能，這個呼叫會開啟鑽研選單。如果擴充功能不是資訊方塊擴充功能視覺化，系統就會忽略此呼叫。
`runDashboard`	執行目前的資訊主頁。在 Explore 中執行的資訊方塊圖表擴充功能會忽略這項呼叫。
`stopDashboard`	停止執行中的資訊主頁。在 Explore 中執行的資訊方塊圖表擴充功能會忽略這項呼叫。
`updateFilters`	更新目前資訊主頁或「探索」中的篩選器。
`openScheduleDialog`	開啟時間表對話方塊。在探索中執行時，系統會忽略此呼叫。
`toggleCrossFilter`	切換交叉篩選器。在探索中執行時，系統會忽略此呼叫。

圖塊 SDK 資料

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

屬性	說明
`isExploring`	如果為 true，表示資訊方塊已設為「探索」中的視覺化呈現。
`dashboardId`	要轉譯的資訊方塊的資訊主頁 ID。如果資訊方塊已設為「探索」，就不會填入這項屬性。
`elementId`	要算繪的圖塊的元素 ID。如果資訊方塊已設為「探索」，就不會填入這項屬性。
`queryId`	正在算繪的圖塊 (如果與圖表相關) 的查詢 ID。如果資訊方塊已設為「探索」，就不會填入這項屬性。 `queryId` 是 Looker Explore 內建視覺化內容時建立的查詢 ID。不含任何篩選條件或交叉篩選條件，無法套用至資訊主頁。如要反映 `QueryResponse` 中顯示的資料，您必須套用篩選器和交叉篩選器，並產生新的查詢。因此，可能還有比 `queryId` 更實用的屬性。如要查看套用篩選器的查詢物件，請參閱 `filteredQuery`。
`querySlug`	如果圖塊與圖表相關，則該圖塊的查詢 slug。如果資訊方塊已設為「探索」，就不會填入這項屬性。 `querySlug` 是 Looker Explore 內建視覺化內容時建立的查詢 slug。不含任何套用至資訊主頁的篩選器或交叉篩選條件。如要反映 `QueryResponse` 中顯示的資料，您必須套用篩選器和交叉篩選器，並產生新的查詢。因此，可能還有比 `querySlug` 更實用的屬性。如要查看套用篩選器的查詢物件，請參閱 `filteredQuery`。
`dashboardFilters`	套用至資訊主頁的篩選器。如果資訊方塊已設為「探索」，就不會填入這項屬性。
`dashboardRunState`	指示資訊主頁是否正在執行。如果資訊方塊已設為「探索」，狀態就會是 `UNKNOWN`。基於資訊主頁效能考量，系統可能不會顯示為執行中。通常在沒有其他資訊方塊與查詢相關聯時，就會發生這種情況，包括擴充資料相關聯的資訊方塊。如果擴充功能需要確知資訊主頁是否已執行，檢測 `lastRunStartTime` 中的差異是可靠的方法。
`isDashboardEditing`	如果為 true，表示資訊主頁正在編輯中。如果資訊方塊已設為「探索」，就不會填入這項屬性。
`isDashboardCrossFilteringEnabled`	如果設為 true，系統會在資訊主頁上啟用交叉篩選功能。如果資訊方塊已設為「探索」，就不會填入這項屬性。
`filteredQuery`	與底層資訊主頁元素相關聯的查詢 ID 相符的查詢物件，該元素會套用資訊主頁層級的任何資訊主頁篩選器和時區變更。
`lastRunSourceElementId`	觸發上次資訊主頁執行作業的資訊方塊額外資訊元素 ID。如果資訊主頁執行作業是由資訊主頁「執行」按鈕或自動重新整理觸發，或是是由內嵌 SDK 觸發，則 ID 會未定義。如果資訊方塊已設為「探索」，就不會填入這項屬性。請注意，`lastRunSourceElementId` 可以與目前擴充功能例項的元素 ID 相同。舉例來說，如果外掛程式觸發資訊主頁執行作業，系統會在資訊主頁執行作業開始及結束時通知外掛程式。
`lastRunStartTime`	指出上次執行資訊主頁的開始時間。如果資訊方塊已設為「探索」，就不會填入這項屬性。請注意，請勿使用回報的開始和結束時間來擷取成效指標。
`lastRunEndTime`	表示上次執行資訊主頁的結束時間。如果資訊方塊已設為「探索」，就不會填入這項屬性。如果資訊方塊正在執行，則不會填入這個屬性。請注意，回報的開始和結束時間不應用於擷取成效指標。
`lastRunSuccess`	指出上次資訊主頁執行作業是否成功。如果資訊方塊已設為「探索」，就不會填入這項屬性。如果資訊方塊正在執行，則不會填入這個屬性。

Visualization SDK 函式和屬性

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

函式或屬性	說明
`visualizationData` (資源)	視覺化 (`visConfig` 和 `queryResponse` 資料的組合)。
`visConfig` (資源)	視覺化呈現設定資料：評估設定維度設定資料表計算資料透視設定視覺化呈現設定這些屬性可用於自訂 Explore 中視覺化內容的外觀和風格。
`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`	欄位維度資訊和資料表計算的串接陣列，其運作方式與維度相同。

使用 Embed SDK

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

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