Skapa en dialogruta för ditt visuella Power BI-objekt
När du skapar ett visuellt objekt är det ibland användbart att visa ytterligare information för kunden i ett separat fönster. Du kanske till exempel vill:
- Visa ytterligare information – till exempel en textanteckning eller en video
- Visa en dialogruta för indata – till exempel en datumdialogruta
För dessa ändamål kan du skapa ett popup-fönster för visuella dialogrutor som kallas för en dialogruta i den här artikeln.
Dialogruteöverväganden
Tänk på följande när du skapar en dialogruta för ditt visuella objekt:
- Under utvecklingen kan du ange dialogrutans storlek och position.
- När dialogrutan utlöses är rapportbakgrunden nedtonad.
- Dialogrubriken innehåller det visuella objektets ikon och dess visningsnamn som en rubrik.
- Dialogrutan kan ha upp till tre åtgärdsknappar. Du kan välja vilka knappar som ska visas från en viss markering.
- I dialogrutan används en omfattande HTML-kod
iframe. - Dialogrutan visas, men ingen åtgärd kan utföras i rapporten förrän den har stängts.
- Dialogkoden kan använda externa npm-bibliotek, precis som det visuella objektet.
Viktigt!
Dialogrutan ska inte utlösas spontant. Det bör vara det omedelbara resultatet av en användaråtgärd.
Utforma en dialogruta för ditt visuella objekt
Om du vill konfigurera en dialogruta måste du lägga till två komponenter i koden:
- En implementeringsfil – Det är bästa praxis att skapa en implementeringsfil för varje dialogruta.
- Kod för att anropa dialogrutan – Om du vill anropa dialogrutan lägger du till kod i
visual.tsfilen.
Skapa dialogrutans implementeringsfil
Vi rekommenderar att du skapar en implementeringsfil för varje dialogruta som du skapar. Placera dina dialogrutefiler i src mappen:
Varje dialogruteimplementeringsfil bör innehålla följande komponenter:
Skapa en dialogruteklass
Skapa en dialogruteklass för dialogrutan. Parametern initialState i openModalDialog skickas till dialogleverantören när den skapas. Använd objektet initialState för att skicka parametrar till dialogrutan för att påverka dess beteende eller utseende.
Dialogkoden kan använda följande IDialogHost metoder:
IDialogHost.setResult(result:object)– Dialogkoden returnerar ett resultatobjekt som skickas tillbaka till det anropande visuella objektet.IDialogHost.close(actionId: DialogAction, result?:object)– Dialogkoden kan programmässigt stänga dialogrutan och ange ett resultatobjekt tillbaka till det visuella objektet som anropar.
Importerar ovanpå filen:
import powerbi from "powerbi-visuals-api";
import DialogConstructorOptions = powerbi.extensibility.visual.DialogConstructorOptions;
import DialogAction = powerbi.DialogAction;
// React imports as an example
import * as ReactDOM from 'react-dom';
import * as React from 'react';
import reactDatepicker from 'react-datepicker';
import 'react-datepicker/dist/react-datepicker.css';
Det här exemplet kräver att du installerar följande paket:
npm i react-dom react react-datepicker
Klassrealisering:
export class DatePickerDialog {
static id = "DatePickerDialog";
constructor(options: DialogConstructorOptions, initialState: object) {
const host = options.host;
let pickedDate: Date;
const startDate = new Date(initialState['startDate']);
// Dialog rendering implementation
ReactDOM.render(
React.createElement(
reactDatepicker,
{
inline: true,
openToDate: startDate,
onChange: (date: Date) => {
pickedDate = date
host.setResult({ date: pickedDate })
}
},
null),
options.element
);
document.addEventListener('keydown', e => {
if (e.code == 'Enter' && pickedDate) {
host.close(DialogAction.Close, {date: pickedDate});
}
});
}
}
Skapa en resultatklass
Skapa en klass som returnerar dialogruteresultatet och lägg sedan till den i dialogrutans implementeringsfil.
I exemplet nedan DatePickerDialogResult returnerar klassen en datumsträng.
export class DatePickerDialogResult {
date: string;
}
Lägg till dialogrutan i registerlistan
Varje dialogimplementeringsfil måste innehålla en registerreferens. Lägg till de två raderna i exemplet nedan i slutet av dialogrutans implementeringsfil. Den första raden ska vara identisk i varje dialogruteimplementeringsfil. Den andra raden visar din dialogruta. ändra den enligt namnet på din dialogruteklass.
globalThis.dialogRegistry = globalThis.dialogRegistry || {};
globalThis.dialogRegistry[DatePickerDialog.id] = DatePickerDialog;
Anropa dialogrutan
Innan du skapar en dialogruta måste du bestämma vilka knappar den ska innehålla. Visuella Power BI-objekt stöder följande sex dialogruteknappar:
export enum DialogAction {
Close = 0,
OK = 1,
Cancel = 2,
Continue = 3,
No = 4,
Yes = 5
}
Varje dialogruta som du skapar måste anropas i visual.ts filen. I det här exemplet definieras dialogrutan med två åtgärdsknappar.
import powerbi from "powerbi-visuals-api";
import DialogAction = powerbi.DialogAction;
const dialogActionsButtons = [DialogAction.OK, DialogAction.Cancel];
I det här exemplet anropas dialogrutan genom att klicka på en visuell knapp. Den visuella knappen definieras som en del av den visuella konstruktorn i visual.ts filen.
Definiera dialogrutans storlek och position
Från API-version 4.0 eller senare kan du definiera dialogrutans storlek och position med parametern DialogOpenOptions openModalDialog. Om du vill ta reda på vilken version du använder kontrollerar apiVersion du i filen pbiviz.json .
export interface RectSize {
width: number;
height: number;
}
export interface DialogOpenOptions {
title: string;
size?: RectSize;
position?: VisualDialogPosition;
actionButtons: DialogAction[];
}
Med positionsparametern kan du bestämma var dialogrutan ska öppnas på skärmen. Du kan välja att öppna dialogrutan i mitten av skärmen, eller så kan du definiera en annan position i förhållande till det visuella objektet.
const enum VisualDialogPositionType {
Center = 0,
RelativeToVisual = 1
}
export interface VisualDialogPosition {
type: VisualDialogPositionType;
left?: number;
top?: number;
}
- Om ingen typ anges är standardbeteendet att öppna dialogrutan i mitten.
- Positionen anges i bildpunkter i förhållande till det övre vänstra hörnet i det visuella objektet.
I det här exemplet visas en dialogruta med datummarkeringen 250 x 300 bildpunkter 100 bildpunkter till vänster och 30 bildpunkter under det visuella objektets överkant:
export class Visual implements IVisual {
private target: HTMLElement;
private host: IVisualHost;
constructor(options: VisualConstructorOptions) {
this.host = options.host;
this.target = options.element;
const dialogActionsButtons = [DialogAction.OK, DialogAction.Cancel];
const sectionDiv = document.createElement("div");
const span = document.createElement("span");
span.id = "datePicker";
let button = document.createElement("button");
button.id = "DateButton";
button.innerText = "Date";
button.onclick = (event) => {
const initialDialogState = { startDate: new Date() };
const position = {
type: VisualDialogPositionType.RelativeToVisual,
left: 100,
top: 30
};
const size = {width: 250, height: 300};
const dialogOptions = {
actionButtons: dialogActionsButtons,
size: size,
position: position,
title: "Select a date"
};
this.host.openModalDialog(DatePickerDialog.id, dialogOptions, initialDialogState).
then(ret => this.handleDialogResult(ret, span)).
catch(error => this.handleDialogError(error, span));
}
sectionDiv.appendChild(button);
sectionDiv.appendChild(span);
this.target.appendChild(sectionDiv)
}
// Custom logic to handle dialog results
private handleDialogResult( result: ModalDialogResult, targetElement: HTMLElement){
if ( result.actionId === DialogAction.OK || result.actionId === DialogAction.Close) {
const resultState = <DatePickerDialogResult> result.resultState;
const selectedDate = new Date(resultState.date);
targetElement.textContent = selectedDate.toDateString();
}
}
// Custom logic to handle errors in dialog
private handleDialogError( error: any, targetElement: HTMLElement ) {
targetElement.textContent = "Error: " + JSON.stringify(error);
}
}
Definiera hur du stänger dialogrutan
Den bästa metoden för att stänga dialogrutan är att slutanvändaren klickar på [x]-knappen, en av åtgärdsknapparna eller rapportens bakgrund.
Du kan också programmera dialogrutan så att den stängs automatiskt genom att anropa IDialogHost stängningsmetoden. Den här metoden blockeras i fem sekunder efter att dialogrutan har öppnats, så att det tidigaste du kan stänga dialogrutan automatiskt är fem sekunder efter att den initierades.
Visa inte dialogrutan
Dialogrutan visas med en kryssruta som ger användaren möjlighet att blockera dialogrutor.
Den här kryssrutan är en säkerhetsfunktion som förhindrar att det visuella objektet skapar modala dialogrutor (antingen avsiktligt eller inte) utan användarens medgivande.
Den här blockeringen gäller endast för den aktuella sessionen. Så om en användare blockerar cv-modaldialogrutorna men senare ändrar sig kan de återaktivera dialogrutorna. För att göra det måste de starta en ny session (uppdatera rapportsidan i Power BI-tjänst eller starta om Power BI Desktop).
Beaktanden och begränsningar
Från och med powerbi-visuals-API 3.8 bestäms dialogikonen och rubriken av det visuella objektets ikon och visningsnamn och kan inte ändras.
Dialogrutans storleksbegränsningar beskrivs i tabellen nedan.
Max/min Bredd Höjd Högsta 90 % av webbläsarens bredd 90 % av webbläsarens höjd Minimal 240 px 210 px När du definierar positionen för dialogrutan kan den vågräta positionen vara ett positivt eller negativt heltal, beroende på vilken sida av det visuella objektet du vill att rutan ska vara. Den lodräta positionen kan inte vara negativ eftersom den placeras ovanför det visuella objektet.
Följande funktioner stöder inte dialogrutan visuella Power BI-objekt:
- Inbäddad analys
- Publicera på webben
- Instrumentpaneler
Du kan programmera ditt visuella objekt för att identifiera om den aktuella miljön tillåter att du öppnar en dialogruta genom att kontrollera det booleska this.host.hostCapabilities.allowModalDialog.