共用方式為

Power BI 視覺效果系統整合

  • 發行項

本文說明 Visual API，以及 Power BI 如何處理您、視覺效果和主機之間的互動。

Power BI 中的動作和後續更新可以手動或自動起始。 更新類型：

下圖顯示了 Power BI 中常見的基於視覺效果的動作 (例如選取書籤) 的處理方式。

Power BI 視覺效果處理流程的圖表。

透過 Power BI 與視覺效果互動

您可以使用 Power BI 更新視覺效果，如下所示：

  • 開啟視覺效果的屬性面板。

    當您開啟視覺效果的屬性面板時，Power BI 會從視覺效果的 capabilities.json 檔案提取支援的物件和屬性。 為了接收屬性的實際值，Power BI 會呼叫視覺效果的 getFormattingModel 方法 (早於 5.0 版的 API 會改為呼叫 enumerateObjectInstances)。 API 會傳回新式格式窗格模型元件、屬性及其實際值。

    如需詳細資訊，請參閱 Power BI 視覺效果的功能和屬性。

  • 自訂視覺效果標題、背景、標籤與圖例。

    當您在 [格式] 面板中變更屬性的值時，Power BI 會呼叫 update 方法。 Power BI 會將新的 options 物件傳遞給 update 方法，而且物件包含新的值。

    如需詳細資訊，請參閱 Power BI 視覺效果的物件和屬性。

  • 調整視覺效果的大小。

    當您變更視覺效果的大小時，Power BI 會呼叫 update 方法並傳入新的 options 物件。 options 物件具有巢狀 viewport 物件，其中包含視覺效果的新寬度和高度。

  • 在報表、頁面或視覺效果層級上套用篩選。

    Power BI 會根據篩選準則來篩選資料。 Power BI 會呼叫視覺效果的 update 方法，以新的資料更新視覺效果。

    當其中一個巢狀物件中有新資料時，視覺效果會取得 options 物件的新更新。 更新發生的方式取決於視覺效果的資料檢視對應設定。

    如需詳細資訊，請參閱了解 Power BI 視覺效果中的資料檢視對應。

  • 選取報表中另一個視覺效果中的資料點。

    當您在報表的另一個視覺效果中選取資料點時，Power BI 會篩選或醒目提示選取的資料點，並呼叫視覺效果的 update 方法。 視覺效果會取得新的篩選資料，或取得具有醒目提示陣列的相同資料。

    如需詳細資訊，請參閱在 Power BI 視覺效果中醒目提示資料點。

  • 在報表的 [書籤] 面板中選取書籤。

    當您在 [書籤] 面板中選取書籤時，會出現下列任一種情況：

    • Power BI 會呼叫由 registerOnSelectionCallback 方法傳遞和註冊的函式。 回呼函式會取得對應書籤的選取陣列。

    • Power BI 會使用 options 物件內的對應 filter 物件來呼叫 update 方法。

      在這兩種情況下，視覺效果都會根據收到的選取項目或 filter 物件來變更其狀態。

      如需有關書籤和篩選器的詳細資訊，請參閱 Power BI 視覺效果中的視覺篩選 API。

直接與視覺效果互動

您也可以直接與視覺效果互動以更新它：

  • 將滑鼠的游標停留在資料元素上。

    視覺效果可以透過 Power BI 工具提示 API 顯示資料點的詳細資訊。 當您將滑鼠的游標停留在視覺效果元素上時，該視覺效果可以處理事件，並顯示相關聯的工具提示元素資料。 視覺效果可以顯示標準工具提示或報表頁面工具提示。

    如需詳細資訊，請參閱將工具提示新增至您的 Power BI 視覺效果。

  • 變更視覺效果屬性 (例如，透過展開樹狀結構)，視覺效果會將新狀態儲存在視覺效果屬性中。

    視覺效果可以透過 Power BI API 儲存屬性值。 例如，當您與視覺效果互動，而視覺效果需要儲存或更新屬性值時，視覺效果就可以呼叫 persistProperties 方法。

  • 選取 URL。

    根據預設，視覺效果無法直接開啟 URL。 若要在新的索引標籤中開啟 URL，視覺效果可以呼叫 launchUrl 方法，並將 URL 傳遞為參數。

    如需詳細資訊，請參閱建立啟動 URL。

  • 透過視覺效果套用篩選。

    視覺效果可以呼叫 applyJsonFilter 方法並傳遞條件，以篩選其他視覺效果中的資料。 有數種篩選類型可供使用，包括基本、進階和 Tuple 篩選。

    如需詳細資訊，請參閱 Power BI 視覺效果中的視覺效果篩選 API。

  • 選取視覺效果中的元素。

    如需有關 Power BI 視覺效果中選取項目的詳細資訊，請參閱透過 Power BI 視覺選取項目將互動性新增到視覺效果中。

視覺效果與 Power BI 互動

有時候視覺效果會在沒有您任何輸入的情況下啟動與 Power BI 主機的通訊：

  • 視覺效果向 Power BI 要求更多資料。

    視覺效果逐項處理資料。 fetchMoreData API 方法會要求語意模型中的下一個資料片段。

    如需詳細資訊，請參閱從 Power BI 擷取更多資料。

  • 事件服務觸發程序。

    Power BI 可以將報表匯出為 PDF，或透過電子郵件傳送報表 (僅適用於經認證的視覺效果)。 若要通知 Power BI 轉譯已完成，而且視覺效果已準備好擷取為 PDF 或電子郵件，則視覺效果應呼叫轉譯事件 API。

    如需詳細資訊，請參閱報表從 Power BI 匯出至 PDF。

    若要了解事件服務，請參閱在 Power BI 視覺效果中「轉譯」事件。

相關內容

您想建立視覺效果並將其新增到 Microsoft AppSource 嗎？ 請參閱以下文章：