ออบเจ็กต์และคุณสมบัติของวิชวล Power BI

ออบเจ็กต์อธิบายคุณสมบัติแบบปรับแต่งได้ที่เกี่ยวข้องกับวิชวล ออบเจ็กต์สามารถมีคุณสมบัติได้หลายรายการและแต่ละคุณสมบัติมีประเภทที่เกี่ยวข้องซึ่งอธิบายถึงคุณสมบัติที่จะเป็น บทความนี้ให้ข้อมูลเกี่ยวกับออบเจ็กต์และชนิดของคุณสมบัติ

myCustomObjectเป็นชื่อภายในที่ใช้เพื่ออ้างอิงวัตถุภายในdataView

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

ชื่อที่แสดงและคําอธิบาย

หมายเหตุ

ชื่อที่แสดงและคําอธิบายไม่ได้รับการสนับสนุนจาก API เวอร์ชัน 5.1+ ขณะนี้มีการเพิ่มชื่อที่แสดงและคําอธิบายในแบบจําลองการจัดรูปแบบแทนที่จะเป็นไฟล์ capabilities.json

displayName คือชื่อที่จะแสดงในบานหน้าต่างคุณสมบัติ description เป็นคําอธิบายของคุณสมบัติการจัดรูปแบบที่จะแสดงให้ผู้ใช้เห็นเป็นคําแนะนําเครื่องมือ

คุณสมบัติ

properties เป็นแผนที่ของคุณสมบัติที่กําหนดโดยผู้พัฒนา

"properties": {
    "myFirstProperty": {
        "type": ValueTypeDescriptor | StructuralTypeDescriptor
    }
}

หมายเหตุ

show เป็นคุณสมบัติพิเศษที่เปิดใช้งานสวิตช์เพื่อสลับวัตถุ

ตัวอย่าง:

"properties": {
    "show": {
        "type": {"bool": true}
    }
}

ชนิดของคุณสมบัติ

มีชนิดคุณสมบัติสองชนิด: ValueTypeDescriptor และStructuralTypeDescriptor

ตัวอธิบายชนิดค่า

ValueTypeDescriptor ส่วนใหญ่เป็นชนิดดั้งเดิมและโดยปกติแล้วจะเป็นวัตถุแบบสแตติก

ต่อไปนี้เป็นองค์ประกอบส่วนหนึ่งของแบบทั่วไป ValueTypeDescriptor :

export interface ValueTypeDescriptor {
    text?: boolean;
    numeric?: boolean;
    integer?: boolean;
    bool?: boolean;
}

ตัวอธิบายชนิดโครงสร้าง

StructuralTypeDescriptor ส่วนใหญ่จะใช้สําหรับวัตถุที่ผูกกับข้อมูล ชนิดที่พบบ่อยStructuralTypeDescriptorที่สุดคือการเติม

export interface StructuralTypeDescriptor {
    fill?: FillTypeDescriptor;
}

คุณสมบัติการไล่ระดับสี

คุณสมบัติการไล่ระดับสีเป็นคุณสมบัติที่ไม่สามารถตั้งค่าเป็นคุณสมบัติมาตรฐานได้ แต่คุณจําเป็นต้องตั้งค่ากฎสําหรับการแทนที่คุณสมบัติตัวเลือกสี (ชนิดการใส่สีเติม )

ตัวอย่างจะแสดงในโค้ดต่อไปนี้:

"properties": {
    "showAllDataPoints": {
        "type": {
            "bool": true
        }
    },
    "fill": {
        "type": {
            "fill": {
                "solid": {
                    "color": true
                }
            }
        }
    },
    "fillRule": {
        "type": {
            "fillRule": {}
        },
        "rule": {
            "inputRole": "Gradient",
            "output": {
                "property": "fill",
                    "selector": [
                        "Category"
                    ]
            }
        }
    }
}

กรุณาใส่ใจกับคุณสมบัติการใส่สีเติมและกฎการใส่สีพื้น อันแรกคือตัวเลือกสี และข้อที่สองคือกฎการแทนที่สําหรับการไล่ระดับสีที่จะแทนที่คุณสมบัติvisuallyการเติม เมื่อตรงตามเงื่อนไขของกฎ

คุณสามารถตั้งค่าการเชื่อมโยงระหว่างคุณสมบัติ การใส่สีพื้น และกฎ"rule""output">การแทนที่ได้ในส่วน ของคุณสมบัติ กฎการใส่สีเติม

"Rule">"InputRole" คุณสมบัติ กําหนดบทบาทข้อมูลที่ทริกเกอร์กฎ (เงื่อนไข) ในตัวอย่างนี้ ถ้าบทบาท "Gradient" ข้อมูลประกอบด้วยข้อมูล กฏจะถูกนําไปใช้กับ "fill" คุณสมบัติ

ตัวอย่างของบทบาทข้อมูลที่ทริกเกอร์กฎการเติม (the last item) จะแสดงในโค้ดต่อไปนี้:

{
    "dataRoles": [
            {
                "name": "Category",
                "kind": "Grouping",
                "displayName": "Details",
                "displayNameKey": "Role_DisplayName_Details"
            },
            {
                "name": "Series",
                "kind": "Grouping",
                "displayName": "Legend",
                "displayNameKey": "Role_DisplayName_Legend"
            },
            {
                "name": "Gradient",
                "kind": "Measure",
                "displayName": "Color saturation",
                "displayNameKey": "Role_DisplayName_Gradient"
            }
    ]
}

พื้นที่การจัดรูปแบบ

หากต้องการกําหนดคุณสมบัติในบานหน้าต่างการจัดรูปแบบ ให้ใช้หนึ่งในวิธีต่อไปนี้ โดยขึ้นอยู่กับเวอร์ชัน API ที่คุณกําลังใช้

getFormattingModel API

หมายเหตุ

วิธีการ getFormattingModel API ได้รับการสนับสนุนจาก API เวอร์ชัน 5.1+ เมื่อต้องการตรวจสอบเวอร์ชันที่คุณกําลังใช้ ให้ตรวจสอบ apiVersion ในไฟล์ pbiviz.json

หากต้องการใช้ออบเจ็กต์อย่างมีประสิทธิภาพใน API เวอร์ชัน 5.1 + คุณจําเป็นต้องใช้ getFormattingModel เมธอด
วิธีนี้สร้างและส่งกลับรูปแบบการจัดรูปแบบที่มีลําดับชั้นบานหน้าต่างคุณสมบัติทั้งหมดของการ์ดการจัดรูปแบบกลุ่มการจัดรูปแบบนอกจากนี้ยังมีคุณสมบัติการจัดรูปแบบและค่า

วัตถุความสามารถสะท้อนให้เห็นในการจัดรูปแบบแบบจําลอง

คุณสมบัติการจัดรูปแบบแต่ละอย่างในแบบจําลองการจัดรูปแบบจําเป็นต้องมีวัตถุที่สอดคล้องกันในไฟล์ capabilities.json คุณสมบัติการจัดรูปแบบควรประกอบด้วยตัวอธิบายที่มีชื่อวัตถุและชื่อคุณสมบัติที่ตรงกับวัตถุความสามารถที่สอดคล้องกัน (วัตถุและชื่อคุณสมบัติจะต้องตรงตามตัวพิมพ์ใหญ่-เล็ก)
ตัวอย่างเช่น:

สําหรับคุณสมบัติการจัดรูปแบบต่อไปนี้ในรูปแบบการจัดรูปแบบ (ดูเนื้อหาของวัตถุตัวอธิบาย):

 const myCustomCard: powerbi.visuals.FormattingCard = {
            displayName: "My Custom Object Card",
            uid: "myCustomObjectCard_uid",
            groups: [{
                displayName: undefined,
                uid: "myCustomObjectGroup_uid",
                slices: [
                    {
                        uid: "myCustomProperty_uid",
                        displayName: "My Custom Property",
                        control: {
                            type: powerbi.visuals.FormattingComponent.ColorPicker,
                            properties: {
                                descriptor: {
                                    objectName: "myCustomObject",
                                    propertyName: "myCustomProperty",
                                    selector: null // selector is optional
                                },
                                value: { value: "#000000" }
                            }
                        }
                    }
                ],
            }],
        };

ออบเจ็กต์ที่สอดคล้องกันจากส่วนความสามารถ objects ควรเป็น:

    "objects": {
        "myCustomObject": {
            "properties": {
                "myCustomProperty": {
                    "type": {
                         "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                }
            }
        }
    }           

ตัวเลือกคุณสมบัติการจัดรูปแบบ

ตัวเลือกที่เลือกได้ในตัวอธิบายคุณสมบัติการจัดรูปแบบจะกําหนดตําแหน่งที่แต่ละคุณสมบัติถูกผูกไว้ใน dataView มีตัวเลือกที่แตกต่างกันสี่ตัวเลือก

ตัวอย่าง

ตัวอย่างข้างต้น myCustomCard แสดงให้เห็นว่าคุณสมบัติการจัดรูปแบบในแบบจําลองการจัดรูปแบบจะมีลักษณะเหมือนสําหรับวัตถุที่มีคุณสมบัติ myCustomPropertyหนึ่งรายการ วัตถุคุณสมบัตินี้ผูกไว้ กับdataViews[index].metadata.objectsแบบสแตติก สามารถเปลี่ยนแปลงตัวเลือกในตัวอธิบายตาม ชนิด ตัวเลือกที่คุณเลือกได้

เมธอด enumerateObjectInstances API - ไม่สนับสนุน

หมายเหตุ

วิธีการ enumerateObjectInstances ถูกเลิกใช้จาก API เวอร์ชัน 5.1 ซึ่งถูกแทนที่ด้วย getFormattingModel ใน API ใหม่

ในการใช้วัตถุอย่างมีประสิทธิภาพ คุณจําเป็นต้องมีฟังก์ชันในวิชวลแบบกําหนดเองของคุณที่เรียกว่าenumerateObjectInstances ฟังก์ชันนี้จะเติมข้อมูลในบานหน้าต่างคุณสมบัติที่มีวัตถุ และยังกําหนดตําแหน่งที่วัตถุของคุณควรถูกผูกไว้ภายใน dataView

นี่คือลักษณะการตั้งค่าทั่วไป:

public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
    let objectName: string = options.objectName;
    let objectEnumeration: VisualObjectInstance[] = [];

    switch( objectName ) {
        case 'myCustomObject':
            objectEnumeration.push({
                objectName: objectName,
                properties: { ... },
                selector: { ... }
            });
            break;
    };

    return objectEnumeration;
}

คุณสมบัติ enumerateObjectInstances

คุณสมบัติใน enumerateObjectInstances จะสะท้อนคุณสมบัติที่คุณกําหนดไว้ในความสามารถของคุณ ตัวอย่างเช่น ไปที่ส่วนท้ายของบทความนี้

ตัวอย่าง enumerateObjectInstances

ตัวอย่างต่อไปนี้แสดงให้เห็นว่า objectEnumeration หนึ่งออบเจ็กต์จะมองหาออบเจ็กต์ customColor ที่มีหนึ่งคุณสมบัติ การ ใส่สีเติม หนึ่งค่า เราต้องการให้วัตถุนี้ผูกไว้ dataViews[index].metadata.objectsกับ แบบสแตติก ตามที่แสดง:

objectEnumeration.push({
    objectName: "customColor",
    displayName: "Custom Color",
    properties: {
        fill: {
            solid: {
                color: dataPoint.color
            }
        }
    },
    selector: null
});

ชนิดตัวเลือกวัตถุ

ตัวเลือกใน enumerateObjectInstances กําหนดตําแหน่งที่แต่ละวัตถุถูกผูกไว้ใน dataView มีตัวเลือกที่แตกต่างกันสี่ตัวเลือก:

• คง
• คอลัมน์
• เลือก
• ข้อมูลประจําตัวของขอบเขต

คง

ออบเจ็กต์นี้จะผูกกับเมตาดาต้า dataviews[index].metadata.objectsดังที่แสดงไว้ที่นี่

selector: null

คอลัมน์

ออบเจ็กต์นี้จะผูกกับคอลัมน์ที่มีการจับคู่QueryName

selector: {
    metadata: 'QueryName'
}

เลือก

ออบเจ็กต์นี้จะผูกกับองค์ประกอบที่คุณสร้าง selectionID ขึ้น ในตัวอย่างนี้ สมมติว่าเราสร้าง selectionIDขึ้นสําหรับบางจุดข้อมูล และเรากําลังวนรอบผ่านจุดข้อมูลเหล่านั้น

for (let dataPoint in dataPoints) {
    ...
    selector: dataPoint.selectionID.getSelector()
}

ข้อมูลประจําตัวของขอบเขต

ออบเจ็กต์นี้จะผูกกับค่าเฉพาะที่จุดตัดของกลุ่ม ตัวอย่างเช่น ถ้าคุณมีข้อมูลจัดกลุ่ม["Jan", "Feb", "March", ...]และชุดข้อมูล ["Small", "Medium", "Large"]คุณอาจต้องการให้มีวัตถุที่จุดตัดของค่าที่ตรงกับ Feb และLarge เมื่อต้องการทําเช่นนี้ คุณจะได้รับ DataViewScopeIdentity ทั้งสองคอลัมน์ ให้ส่งไปยังตัวแปร identitiesและใช้ไวยากรณ์นี้กับตัวเลือก

selector: {
    data: <DataViewScopeIdentity[]>identities
}

เนื้อหาที่เกี่ยวข้อง

เคล็ดลับประสิทธิภาพการทํางาน