Power BI görseliniz için iletişim kutusu oluşturma

Bir görsel oluşturduğunuzda, bazen müşteriye ayrı bir pencerede ek bilgiler görüntülemek yararlı olabilir. Örneğin, şunları yapmak isteyebilirsiniz:

• Ek bilgileri gösterme - Metin notu veya video gibi
• Giriş verileri iletişim kutusunu görüntüleme - Tarih iletişim kutusu gibi

Bu amaçlarla, bu makalede iletişim kutusu olarak adlandırılan bir iletişim kutusu görseli açılır penceresi oluşturabilirsiniz.

İletişim kutusuyla ilgili dikkat edilmesi gerekenler

Görseliniz için bir iletişim kutusu oluştururken şunları aklınızda bulundurun:

• Geliştirme sırasında iletişim kutusunun boyutunu ve konumunu belirtebilirsiniz.
• İletişim kutusu tetiklendiğinde rapor arka planı gri görünür.
• İletişim kutusu üst bilgisi görselin simgesini ve görünen adını başlık olarak içerir.
• İletişim kutusunda en fazla üç eylem düğmesi olabilir. Belirli bir seçimden hangi düğmelerin görüntüleneceğini seçebilirsiniz.
• İletişim kutusunda zengin bir HTML iframekullanılır.
• İletişim kutusu görüntülenirken, rapor kapatılana kadar raporda hiçbir eylem gerçekleştirilemez.
• İletişim kutusu kodu, görselde olduğu gibi dış npm kitaplıklarını kullanabilir.

Önemli

İletişim kutusu kendiliğinden tetiklenmemelidir. Bu, bir kullanıcı eyleminin hemen sonucu olmalıdır.

Görseliniz için iletişim kutusu tasarlama

İletişim kutusunu yapılandırmak için kodunuza iki bileşen eklemeniz gerekir:

• Uygulama dosyası - Her iletişim kutusu için bir uygulama dosyası oluşturmak en iyi yöntemdir.
• İletişim kutunuzu çağırmak için kod - İletişim kutunuzu çağırmak için dosyaya visual.ts kod ekleyin.

İletişim kutusu uygulama dosyası oluşturma

Oluşturduğunuz her iletişim kutusu için bir uygulama dosyası oluşturmanızı öneririz. İletişim kutusu dosyalarınızı klasöre src yerleştirin:

Her iletişim kutusu uygulama dosyası aşağıdaki bileşenleri içermelidir:

• İletişim kutusu sınıfı
• Sonuç sınıfı
• İletişim kutusu sınıfının kaydı

İletişim kutusu sınıfı oluşturma

İletişim kutunuz için bir iletişim kutusu sınıfı oluşturun. initialState parametresiopenModalDialog, oluşturuldukten sonra iletişim kutusu yüklenicisine geçirilir. initialState Davranışını veya görünümünü etkilemek için iletişim kutusuna parametre geçirmek için nesnesini kullanın.

İletişim kutusu kodu şu IDialogHost yöntemleri kullanabilir:

• IDialogHost.setResult(result:object) - İletişim kutusu kodu, çağıran görseline geri geçirilen bir sonuç nesnesi döndürür.
• IDialogHost.close(actionId: DialogAction, result?:object) - İletişim kutusu kodu, iletişim kutusunu program aracılığıyla kapatabilir ve çağıran görseline bir sonuç nesnesi sağlayabilir.

Dosyanın en üstünde içeri aktarır:

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';

Bu örnekte şu paketlerin yüklenmesi gerekir:

    npm i react-dom react react-datepicker

Sınıf gerçekleştirme:

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});
            }
        });
    }
}

Sonuç sınıfı oluşturma

İletişim kutusu sonucunu döndüren bir sınıf oluşturun ve bunu iletişim kutusu uygulama dosyasına ekleyin.

Aşağıdaki örnekte, DatePickerDialogResult sınıfı bir tarih dizesi döndürür.

export class DatePickerDialogResult {
    date: string;
}

İletişim kutunuzu kayıt defteri listesine ekleme

Her iletişim kutusu uygulama dosyasının bir kayıt defteri başvurusu içermesi gerekir. Aşağıdaki örnekteki iki satırı iletişim kutusu uygulama dosyanızın sonuna ekleyin. her iletişim kutusu uygulama dosyasında ilk satır aynı olmalıdır. İkinci satırda iletişim kutunuz listelenir; iletişim kutusu sınıfınızın adına göre değiştirin.

globalThis.dialogRegistry = globalThis.dialogRegistry || {};
globalThis.dialogRegistry[DatePickerDialog.id] = DatePickerDialog;

İletişim kutusunu çağırma

bir iletişim kutusu oluşturmadan önce, hangi düğmeleri içereceğine karar vermeniz gerekir. Power BI görselleri aşağıdaki altı iletişim kutusu düğmesini destekler:

export enum DialogAction {
        Close = 0,
        OK = 1,
        Cancel = 2,
        Continue = 3,
        No = 4,
        Yes = 5
    }

Oluşturduğunuz her iletişim kutusunun dosyada visual.ts çağrılması gerekir. Bu örnekte, iletişim kutusu iki eylem düğmesiyle tanımlanır.

import powerbi from "powerbi-visuals-api";
import DialogAction = powerbi.DialogAction;
const dialogActionsButtons = [DialogAction.OK, DialogAction.Cancel];

Bu örnekte, bir görsel düğmesine tıklanarak iletişim kutusu çağrılır. Görsel düğmesi, dosyadaki visual.ts görsel oluşturucunun bir parçası olarak tanımlanır.

İletişim kutusunun boyutunu ve konumunu tanımlama

API 4.0 veya sonraki bir sürümden, parametresini openModalDialogkullanarak DialogOpenOptions iletişim kutusunun boyutunu ve konumunu tanımlayabilirsiniz. Hangi sürümü kullandığınızı öğrenmek için pbiviz.json dosyasını denetleyin apiVersion.

    export interface RectSize {
        width: number;
        height: number;
    }

    export interface DialogOpenOptions {
        title: string;
        size?: RectSize;
        position?: VisualDialogPosition;
        actionButtons: DialogAction[];
    }

position parametresi, iletişim kutusunun ekranda nerede açileceğine karar vermenizi sağlar. Ekranın ortasındaki iletişim kutusunu açmayı seçebilir veya görsele göre farklı bir konum tanımlayabilirsiniz.

    const enum VisualDialogPositionType {
        Center = 0,
        RelativeToVisual = 1
    }

    export interface VisualDialogPosition {
        type: VisualDialogPositionType;
        left?: number;
        top?: number;
    }

• Hiçbir tür belirtilmezse, varsayılan davranış iletişim kutusunu ortada açmaktır.
• Konum, görselin sol üst köşesine göre piksel cinsinden verilir.

Bu örnekte, 250 x 300 piksel tarih seçimi iletişim kutusu 100 piksel sola ve 30 piksel görselin üst kısmında gösterilir:

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);
    }
}

İletişim kutusunun nasıl kapatılacağını tanımlama

İletişim kutusunu kapatmak için tercih edilen yöntem, son kullanıcının [x] düğmesine, eylem düğmelerinden birine veya rapor arka planına tıklamasıdır.

Ayrıca close yöntemini çağırarak IDialogHost iletişim kutusunu otomatik olarak kapatacak şekilde programlayabilirsiniz. Bu yöntem, iletişim kutusu açıldıktan sonra beş saniye boyunca engellenir, böylece iletişim kutusunu otomatik olarak kapatabileceğiniz en erken yöntem başlatıldıktan beş saniye sonra olur.

İletişim kutusunu gösterme

İletişim kutusu, kullanıcıya iletişim kutularını engelleme seçeneği sunan bir onay kutusuyla birlikte görüntülenir.

Bu onay kutusu, görselin kullanıcının onayı olmadan kalıcı iletişim kutuları (kasıtlı olarak veya değil) oluşturmasını engelleyen bir güvenlik özelliğidir.

Bu engelleme yalnızca geçerli oturum için geçerlidir. Bu nedenle, bir kullanıcı CV kalıcı iletişim kutularını engeller ancak daha sonra fikrini değiştirirse, iletişim kutularını yeniden etkinleştirebilir. Bunu yapmak için yeni bir oturum başlatmaları gerekir (Power BI hizmeti raporlar sayfasını yenileyin veya Power BI Desktop'ı yeniden başlatın).

Dikkat edilecekler ve sınırlamalar

• Powerbi-visuals-API 3.8 itibarıyla iletişim kutusu simgesi ve başlığı görselin simgesi ve görünen adı tarafından belirlenir ve değiştirilemez.

• İletişim kutusunun boyut sınırlamaları aşağıdaki tabloda açıklanmıştır.

  Maks./dk	Genişlik	Yükseklik
  En Büyük	Tarayıcı genişliğinin %90'ını	Tarayıcı yüksekliğinin %90'ını
  Minimum	240 piksel	210 piksel

• İletişim kutusunun konumunu tanımlarken, kutunun hangi tarafında olmasını istediğinize bağlı olarak yatay konum pozitif veya negatif bir tamsayı olabilir. Dikey konum, görselin üzerine yerleştirileceğinden negatif olamaz.

• Aşağıdaki özellikler Power BI görselleri iletişim kutusunu desteklemez:

  • Eklenmiş analiz
  • Web'de yayımlama
  • Panolar

Görselinizi, geçerli ortamın boole this.host.hostCapabilities.allowModalDialogdeğerini işaretleyerek bir iletişim kutusu açmaya izin vermediğini algılamak için programlayabilirsiniz.

İlgili içerik

Power BI özel görseli yayımlama

Power BI çubuk grafik görseli oluşturma