本頁面由 Cloud Translation API 翻譯而成。

建構資訊方塊擴充功能

自 Looker 24.0 起，開發人員可以開發擴充功能，在資訊主頁的圖塊中執行。如果擴充功能支援以圖塊或視覺化形式執行，您可以在資訊主頁處於編輯模式時新增擴充功能，也可以從探索中將擴充功能儲存至資訊主頁，做為視覺化項目。您也可以在 LookML 資訊主頁中，將擴充功能設定為圖塊。

我們提供可做為資訊主頁動態磚的擴充功能範例：

圖塊視覺化擴充功能：說明如何使用擴充功能架構建構自訂視覺化效果。
圖塊 SDK 擴充功能會顯示圖塊擴充功能專用的可用 API 方法。

搭配圖塊擴充功能使用 Looker 擴充功能 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` (房源)	圖塊擴充功能的專屬主機資料。詳情請參閱「圖塊 SDK 資料」一節。
`addError`	呼叫時，資訊主頁或「探索」會在視覺化圖表下方顯示錯誤訊息。
`clearError`	呼叫時，資訊主頁或「探索」會隱藏顯示在視覺化圖表下方的任何錯誤訊息。
`openDrillMenu`	如果是視覺化擴充功能，這項呼叫會開啟下鑽選單。如果擴充功能不是資訊方塊擴充功能視覺化效果，系統就會忽略此呼叫。
`runDashboard`	執行目前的資訊主頁。在「探索」中執行的圖塊視覺化擴充功能會忽略這項呼叫。
`stopDashboard`	停止執行中的資訊主頁。在「探索」中執行的圖塊視覺化擴充功能會忽略這項呼叫。
`updateFilters`	更新目前資訊主頁或「探索」中的篩選器。
`openScheduleDialog`	開啟排程對話方塊。在「探索」中執行時，系統會忽略此呼叫。
`toggleCrossFilter`	切換交叉篩選器。在「探索」中執行時，系統會忽略此呼叫。

Tile SDK 資料

下表列出可用的 Tile SDK 資料屬性：

屬性	說明
`isExploring`	如果為 true，表示正在將動態磚設定為「探索」中的視覺化內容。
`dashboardId`	要顯示的圖塊的資訊主頁 ID。如果將動態磚設定為「探索」，系統就不會填入這項屬性。
`elementId`	要算繪的圖塊元素 ID。如果將動態磚設定為「探索」，系統就不會填入這項屬性。
`queryId`	如果與視覺化效果相關聯，則為要算繪的圖塊查詢 ID。如果將動態磚設定為「探索」，系統就不會填入這項屬性。 `queryId` 是在 Looker 探索中建立視覺化內容時建立的查詢 ID。其中不含任何要套用至資訊主頁的篩選器或交叉篩選器。如要反映「`QueryResponse`」中顯示的資料，請套用篩選器和交叉篩選器，並產生新的查詢。因此，可能會有比 `queryId` 更有用的屬性。如要查看已套用篩選條件的查詢物件，請參閱 `filteredQuery`。
`querySlug`	如果與視覺化效果相關聯，則為要算繪的圖塊查詢 slug。如果將動態磚設定為「探索」，系統就不會填入這項屬性。 `querySlug` 是在 Looker 探索中建立視覺化內容時，所建立查詢的代碼。不包含套用至資訊主頁的任何篩選器或交叉篩選器。如要反映「`QueryResponse`」中顯示的資料，請套用篩選器和交叉篩選器，並產生新的查詢。因此，可能會有比 `querySlug` 更有用的屬性。如要查看已套用篩選條件的查詢物件，請參閱 `filteredQuery`。
`dashboardFilters`	套用至資訊主頁的篩選器。如果將動態磚設定為「探索」，系統就不會填入這項屬性。
`dashboardRunState`	指出資訊主頁是否正在執行。如果圖塊設定為探索，狀態會是 `UNKNOWN`。基於資訊主頁效能考量，系統可能不會顯示執行中的執行狀態。如果查詢沒有其他相關聯的動態磚 (包括擴充功能相關聯的動態磚)，通常就會發生這種情況。如果擴充功能需要確定資訊主頁是否已執行，偵測 `lastRunStartTime` 的差異是可靠的方法。
`isDashboardEditing`	如果為 true，表示正在編輯資訊主頁。如果將動態磚設定為「探索」，系統就不會填入這項屬性。
`isDashboardCrossFilteringEnabled`	設為 true 時，系統會在資訊主頁上啟用交叉篩選功能。如果將動態磚設定為「探索」，系統就不會填入這項屬性。
`filteredQuery`	查詢物件，與套用任何資訊主頁篩選器和時區變更的基礎資訊主頁元素相關聯。
`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`	欄位維度資訊和資料表計算的串連陣列，行為類似維度。

使用 Embed SDK

基於下列原因，不建議在動態磚擴充功能中使用 Embed SDK：

擴充功能可能會在擴充功能是其中一個圖塊的資訊主頁中，最終算繪資訊主頁。擴充功能架構無法偵測到這點，因此瀏覽器可能會當機。
無法在圖塊擴充功能中，將內嵌內容轉譯為 PDF。