事件
3月31日 下午11時 - 4月2日 下午11時
最終Microsoft Fabric、Power BI、SQL 和 AI 社群主導的活動。 2025 年 3 月 31 日至 4 月 2 日。
立即註冊注意
此功能從 API 版本 5.7.0 開始可用。
動態鑽研控制功能允許視覺效果使用 API 呼叫來動態啟用或停用鑽研功能。 啟用鑽研功能時,可使用所有向下切入功能和展開/折疊功能,包括 API 呼叫、快顯功能表命令、標頭鑽研按鈕,以及階層資料支援。 停用時,無法使用這些功能。
下列影像顯示已啟用和停用動態鑽研控制功能的視覺效果範例:
動態鑽研控制功能包含下列 API 元素:
DataRolesInfo
中的 isDrillDisabled
旗標:
export interface DataRolesInfo {
//…
isDrillDisabled?: boolean; // ----- NEW -----
}
IVisualHost
介面中的 setCanDrill
方法:
export interface IVisualHost extends extensibility.IVisualHost {
//…
setCanDrill: (drillAllowed: boolean) => void; // ----- NEW -----
}
若要識別鑽研是否已停用,請在 update 方法中使用 isDrillDisabled
屬性:
private update(options: VisualUpdateOptions) {
//…
const isDrillDisabled = options.dataViews[0].metadata.dataRoles.isDrillDisabled;
//…
}
然後使用 API 呼叫,視需要啟用或停用鑽研:
若要啟用:this.host.setCanDrill(true /* drillAllowed */);
若要停用:this.host.setCanDrill(false /* drillAllowed */);
鑽研預設為已啟用,但動態鑽研控制功能允許視覺效果使用 API 呼叫來啟用或停用鑽研。
具有動態鑽研控件功能的視覺效果,在 capabilities.json 檔案中具有下列程式碼:
依預設停用鑽研:
"drilldown": {
"roles": [
"Rows",
"Columns"
],
"canDisableDrill": {
"disabledByDefault": true
}
},
依預設啟用鑽研:
"drilldown": {
"roles": [
"Rows",
"Columns"
],
"canDisableDrill": {}
},
canDisableDrill
屬性表示視覺效果支援這項功能。 如果沒有這個屬性,就不會遵守 API 呼叫。
disabledByDefault
屬性指出是否依預設停用鑽研功能。
注意
當您執行下列其中一個動作時,disabledByDefault
屬性會生效:
例如,如果您將 sourceVisual 轉換成 targetVisual,則只有在sourceVisual 不支援此功能時,才會考慮 targetVisual 的 disabledByDefault
屬性。 如果 sourceVisual 支援此功能,targetVisual 會保留 sourceVisual 的狀態,而不是預設值。
使用向下切入功能代表重大變更。 因此,為了達到最順暢的轉換,建議您針對新版本使用新的視覺 GUID。
不過,如果您想要保留相同的 GUID,請記住下列幾點:
當您從不可鑽研的版本移轉至新的可鑽研版本時,dataView
中可能不會提供某些資料,因為階層式資料支援作為鑽研功能的一部分引進。 動態鑽研控制功能不提供此問題的自動支援,但可用來管理移轉程序。
針對視覺效果的自我移轉,視覺效果應該採取下列動作:
識別第一次載入新版本,而不是舊版,並套用 persistProperties
API。
使用 setCanDrill
API 停用鑽研以接收所有資料。
下列範例示範如何將較舊的視覺效果自我移轉至使用動態鑽研控制的視覺效果:
在 capabilities.json 檔案中新增下列物件:
"DrillMigration": {
"displayName": "Drill Migration",
"properties": {
"isMigrated": {
"displayName": "Is Drill Migrated",
"type": {
"bool": true
}
}
}
},
將下列內容新增至 visual.ts 檔案:
export class Visual implements IVisual {
//...
private isCalledToDisableDrillInMigrationScenario = false;
private drillMigration = { disabledByDefault: true };
constructor(options: VisualConstructorOptions) {
//...
this.host = options.host;
//...
}
private update(options: VisualUpdateOptions) {
this.handleSelfDrillMigration(options);
//...
}
private handleSelfDrillMigration(options: VisualUpdateOptions): void {
if (options && options.dataViews && options.dataViews[0] && options.dataViews[0].metadata) {
const metadata = options.dataViews[0].metadata;
if (metadata && metadata.dataRoles) {
const isDrillDisabled = metadata.dataRoles.isDrillDisabled;
if (isDrillDisabled === undefined) {
return;
}
// Continue in case the visual is already migrated
if (!metadata.objects?.DrillMigration?.isMigrated) {
// Persist the isMigrated property when the drill has the correct state
if (this.drillMigration.disabledByDefault === isDrillDisabled) {
this.persistMigrationProperty();
} else if (!this.isCalledToDisableDrillInMigrationScenario) {
// Use the API call only once
this.host.setCanDrill(!this.drillMigration.disabledByDefault);
this.isCalledToDisableDrillInMigrationScenario = true;
}
}
}
}
}
private persistMigrationProperty(): void {
let property = {
merge: [{
objectName: "DrillMigration",
properties: {
isMigrated: true
},
selector: null
}]
};
this.host.persistProperties(property);
}
}
新增此程式碼之後,第一次開啟視覺效果時,DrillMigration 變數會設定為 true,且視覺效果會以預設狀態開啟。
停用鑽研之後,不會儲存鑽研狀態。 如果您在停用鑽研之後予以重新啟用,則不論在停用前顯示的內容為何,都只會顯示第一個層級。
停用鑽研之後,不會儲存展開/摺疊狀態。 重新啟用鑽研後,會摺疊所有的資料列。
儀表板不支援 API 呼叫。
資料檢視對應條件:針對可鑽研角色的所有條件使用 "max": 1
,限制視覺效果在停用鑽研時只顯示一個欄位。 例如:
針對類別資料檢視:
"conditions": [
{ "category": { "min": 1 }, "measure": { "max": 1 }}
]
針對矩陣資料檢視:
"conditions": [
{ "Rows": { "max": 0 }, "Columns": { "max": 0 }, "Value": { "min": 1 } },
{ "Rows": { "min": 1 }, "Columns": { "min": 0 }, "Value": { "min": 0 } },
{ "Rows": { "min": 0 }, "Columns": { "min": 1 }, "Value": { "min": 0 } },
]
事件
3月31日 下午11時 - 4月2日 下午11時
最終Microsoft Fabric、Power BI、SQL 和 AI 社群主導的活動。 2025 年 3 月 31 日至 4 月 2 日。
立即註冊訓練
認證
Microsoft Certified: Power BI Data Analyst Associate - Certifications
示範符合使用 Microsoft Power BI 進行資料建模、視覺化和分析的業務和技術要求的方法和最佳做法。