แชร์ผ่าน

กําหนดบานหน้าต่างการจัดรูปแบบในวิชวลแบบกําหนดเองของ Power BI

  • บทความ

เริ่มต้นจาก API เวอร์ชัน 5.1 นักพัฒนาสามารถสร้างวิชวลที่ใช้ บานหน้าต่างรูปแบบ Power ใหม่ได้ นักพัฒนาสามารถกําหนดการ์ดและหมวดหมู่ของการ์ดสําหรับคุณสมบัติใด ๆ ในวิชวลแบบกําหนดเอง ทําให้ผู้สร้างรายงานสามารถใช้วิชวลเหล่านี้ได้ง่ายขึ้น

API ใหม่ใช้ เมธอด FormattingModel เพื่อกําหนดส่วนของบานหน้าต่างรูปแบบและการวิเคราะห์

เคล็ดลับ

เม getFormattingModel ธอด จะ enumerateObjectInstances แทนที่วิธีการ ใน API เวอร์ชันก่อนหน้า

ส่งกลับ getFormattingModel ที่กําหนด FormattingModel ลักษณะที่ปรากฏของการจัดรูปแบบและบานหน้าต่างการวิเคราะห์ของวิชวล

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

Screenshot of the new formatting pane.

หากต้องการอัปเกรดเป็น API เวอร์ชัน 5.1 + ให้ตั้งค่า apiVersion ในไฟล์ pbiviz.json ของคุณเป็น5.1หรือใหม่กว่า และเลือกทําอย่างใดอย่างหนึ่งต่อไปนี้:

  • ใช้ ยูทิลิตี้การจัดรูปแบบ model (แนะนํา)
  • หากไม่มี util นี้ ให้ใช้ API ตามวิธีการต่อไปนี้เท่านั้น

สร้างวิชวลที่สนับสนุนบานหน้าต่างรูปแบบใหม่

เมื่อต้องสร้างวิชวลแบบกําหนดเองที่ใช้บานหน้าต่างรูปแบบใหม่:

  1. กําหนดทั้งหมดที่สามารถกําหนดเองได้ในobjectsไฟล์ capabilities.json ของคุณ
    จําเป็นต้องมีคุณสมบัติต่อไปนี้สําหรับแต่ละวัตถุ:

    • ชื่อวัตถุ
    • ชื่อคุณสมบัติ
    • ชนิดของคุณสมบัติ

    คุณสมบัติอื่น ๆ ทั้งหมด รวมถึง DisplayName และ descriptionเป็นทางเลือกในขณะนี้

  2. สร้างการจัดรูปแบบวิ ชวลแบบกําหนดเองแบบจําลอง กําหนดคุณสมบัติของรูปแบบการจัดรูปแบบวิชวลแบบกําหนดเองของคุณและสร้างโดยใช้รหัส (ไม่ใช่ JSON)

  3. getFormattingModelใช้ API ในคลาสวิชวลแบบกําหนดเองที่ส่งกลับแบบจําลองการจัดรูปแบบวิชวลแบบกําหนดเอง (API นี้จะแทนที่ enumerateObjectInstances ถูกใช้ในเวอร์ชันก่อนหน้า)

คุณสมบัติการจัดรูปแบบแผนที่

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

  1. apiVersionตั้งค่า ในไฟล์ pbiviz.json ของคุณเป็น 5.1 หรือใหม่กว่า

  2. สําหรับแต่ละชื่อวัตถุและชื่อคุณสมบัติใน capabilities.json ให้สร้างคุณสมบัติการจัดรูปแบบที่ตรงกัน คุณสมบัติการจัดรูปแบบควรมีตัวอธิบายที่มี objectName และ propertyName ที่ตรงกับชื่อวัตถุและชื่อคุณสมบัติใน capabilities.json

คุณสมบัติ objects ในไฟล์ความสามารถยังคงมีรูปแบบเดียวกันและไม่จําเป็นต้องเปลี่ยนแปลง

ตัวอย่างเช่น ถ้าวัตถุในcircleไฟล์ capabilities.json ของคุณถูกกําหนดดังนี้:

"objects": {
    "circle": {
        "properties": {
            "circleColor": {
                "type": {
                    "fill": {
                        "solid": {
                            "color": true
                        }
                    }
                  }
          },
        }
      }
    }

คุณสมบัติการจัดรูปแบบในแบบจําลองของคุณควรเป็นชนิด ColorPicker และมีลักษณะดังนี้:

control: {
    type: "ColorPicker",
    properties: {
        descriptor: {
            objectName: "circle",
            propertyName: "circleColor"
        },
        value: {
            value: this.visualSettings.circle.circleColor
        }
    }
}

คุณจะได้รับข้อผิดพลาดถ้าหนึ่งในเงื่อนไขต่อไปนี้เป็นจริง:

  • ชื่อวัตถุหรือคุณสมบัติในไฟล์ความสามารถไม่ตรงกับชื่อในแบบจําลองการจัดรูปแบบ
  • ชนิดคุณสมบัติในไฟล์ความสามารถไม่ตรงกับชนิดในแบบจําลองการจัดรูปแบบ

การจัดรูปแบบแบบจําลอง

แบบจําลองการจัดรูปแบบคือที่ที่คุณอธิบายและกําหนดคุณสมบัติทั้งหมดของบานหน้าต่างการจัดรูปแบบของคุณ

การจัดรูปแบบคอมโพเนนต์แบบจําลอง

ในแบบจําลองการจัดรูปแบบใหม่ คอมโพเนนต์คุณสมบัติจะถูกจัดกลุ่มเข้าด้วยกันในประเภทเชิงตรรกะและประเภทย่อย กลุ่มเหล่านี้ทําให้ง่ายต่อการสแกนแบบจําลอง มีส่วนประกอบพื้นฐานห้าส่วน ตั้งแต่มากที่สุดถึงน้อยที่สุด:

  • การจัดรูปแบบแบบจําลอง
    คอนเทนเนอร์บานหน้าต่างที่ใหญ่ที่สุดซึ่งใช้สําหรับการจัดรูปแบบอินเทอร์เฟซด้านหน้าของบานหน้าต่าง ซึ่งประกอบด้วยรายการของการ์ดการจัดรูปแบบ

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

    Screenshot of formatting model with individual formatting cards.

  • กลุ่มการจัดรูปแบบ
    คอนเทนเนอร์การจัดกลุ่มคุณสมบัติระดับรอง กลุ่มการจัดรูปแบบจะแสดงเป็นคอนเทนเนอร์การจัดกลุ่มสําหรับส่วนการจัดรูปแบบ

    Screenshot of formatting cards divided into formatting groups.

  • การจัดรูปแบบส่วนข้อมูล
    คอนเทนเนอร์คุณสมบัติ มีสองชนิดของส่วนข้อมูล:

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

    รูปภาพต่อไปนี้แสดงประเภทต่าง ๆ ของส่วนข้อมูล "Font" คือชิ้นแบบรวมที่ประกอบด้วยตระกูลแบบอักษร ขนาด และตัวหนา ตัวเอียง และสวิตช์ขีดเส้นใต้ "สี" "หน่วยแสดงผล" และส่วนอื่น ๆ เป็นส่วนง่าย ๆ ที่มีองค์ประกอบเดียว

    Screenshot of format pane composite and simple slices.

คุณสมบัติการจัดรูปแบบบานหน้าต่างการแสดงภาพ

คุณสมบัติทั้งหมดในแบบจําลองการจัดรูปแบบควรตรงกับและชนิดของวัตถุในไฟล์ capabilities.json

ตารางต่อไปนี้แสดงชนิดคุณสมบัติการจัดรูปแบบใน ไฟล์ capabilities.json และคลาสชนิดที่ตรงกันในคุณสมบัติแบบจําลองการจัดรูปแบบที่ทันสมัย:

ขนิด ชนิดค่าความสามารถ คุณสมบัติการจัดรูปแบบ
บูลีน Bool สลับสลับ
ตัวเลข
  • ตัวเลข
  • จํานวนเต็ม
  • NumUpDown
  • แถบเลื่อน
    		•
    รายการการแจงนับ การแจงนับ:[]
  • ItemDropdown
  • ItemFlagsSelection
  • ดรอปดาวน์อัตโนมัติ
  • AutoFlagsSelection
    • * ดูหมายเหตุด้านล่าง
    สี สีพื้น ColorPicker
    ไล่ ระดับ สี กฎการเติม GradientBar: ค่าคุณสมบัติควรเป็นสตริงที่ประกอบด้วย: minValue[,midValue],maxValue
    ข้อความ ข้อความ
  • TextInput
  • TextArea
    		•

    ความสามารถในการจัดรูปแบบวัตถุ

    ขนิด ชนิดค่าความสามารถ คุณสมบัติการจัดรูปแบบ
    ขนาดแบบอักษร FontSize NumUpDown
    ตระกูลแบบอักษร FontFamily FontPicker
    การจัดแนวเส้น การจัดแนว AlignmentGroup
    หน่วยแสดงผลป้ายชื่อ LabelDisplayUnits AutoDropDown

    * คุณสมบัติการจัดรูปแบบรายการการแจงนับจะแตกต่างกันในแบบจําลองการจัดรูปแบบและในไฟล์ความสามารถ

    • ประกาศคุณสมบัติต่อไปนี้ในคลาสการตั้งค่าการจัดรูปแบบ รวมถึงรายการของรายการการแจงนับ:

      • ItemDropdown
      • ItemFlagsSelection

    • ประกาศคุณสมบัติต่อไปนี้ในคลาสการตั้งค่าการจัดรูปแบบ โดยไม่มีรายการการแจงนับ ประกาศรายการข้อมูลการแจงนับของพวกเขาใน capabilities.json ภายใต้วัตถุที่เหมาะสม (ชนิดเหล่านี้เหมือนกับใน API เวอร์ชันก่อนหน้า):

      • ดรอปดาวน์อัตโนมัติ
      • AutoFlagSelection

    คุณสมบัติชิ้นแบบรวม

    ชิ้นการจัดรูปแบบแบบรวมคือชิ้นการจัดรูปแบบที่ประกอบด้วยคุณสมบัติที่เกี่ยวข้องหลายรายการเข้าด้วยกัน

    ในตอนนี้เรามีชิ้นแบบรวมสองชนิด:

    • FontControl
      ซึ่งจะทําให้คุณสมบัติที่เกี่ยวข้องกับแบบอักษรทั้งหมดอยู่ด้วยกัน ประกอบด้วยคุณสมบัติต่อไปนี้:

      • ตระกูลแบบอักษร
      • ขนาดแบบอักษร
      • ตัวหนา [ตัวเลือก]
      • ตัวเอียง [ไม่บังคับ]
      • ขีดเส้นใต้ [ไม่บังคับ]

      Screenshot of font composite slice with font family, font size, bold, italic, and underline options.

      แต่ละคุณสมบัติเหล่านี้ควรมีวัตถุที่สอดคล้องกันในไฟล์ความสามารถ:

      คุณสมบัติ ชนิดความสามารถ ชนิดของการจัดรูปแบบ
      ตระกูลแบบอักษร การจัดรูปแบบ: { fontFamily} FontPicker
      ขนาดแบบอักษร การจัดรูปแบบ: {fontSize} NumUpDown
      Bold Bool สลับสลับ
      Italic Bool สลับสลับ
      ขีดเส้นใต้ Bool สลับสลับ

    • ช่องว่างภายในระยะขอบ จะกําหนดการจัดแนวของข้อความในวิชวล ประกอบด้วยคุณสมบัติต่อไปนี้:

      • ซ้าย
      • Right
      • ด้านบน
      • ล่าง

      แต่ละคุณสมบัติเหล่านี้ควรมีวัตถุที่สอดคล้องกันในไฟล์ความสามารถ:

      คุณสมบัติ ชนิดความสามารถ ชนิดของการจัดรูปแบบ
      ซ้าย ตัวเลข NumUpDown
      Right ตัวเลข NumUpDown
      ด้านบน ตัวเลข NumUpDown
      ล่าง ตัวเลข NumUpDown

    ตัวอย่าง: การจัดรูปแบบการ์ดข้อมูล

    ในตัวอย่างนี้ เราจะแสดงวิธีการสร้างรูปแบบการจัดรูปแบบวิชวลแบบกําหนดเองด้วยการ์ดเดียว
    การ์ดมีสองกลุ่ม:

    • กลุ่ม ควบคุมฟอนต์ที่มีคุณสมบัติแบบรวมหนึ่งคุณสมบัติ
      • ตัวควบคุมฟอนต์
    • กลุ่ม การออกแบบข้อมูลที่มีสองคุณสมบัติแบบง่าย
      • สีแบบอักษร
      • การจัดแนวเส้น

    ก่อนอื่น ให้เพิ่มวัตถุไปยังไฟล์ความสามารถ:

    "objects": {
        "dataCard": {
            "properties": {
                "displayUnitsProperty": {
                    "type":
                    {
                        "formatting": {
                            "labelDisplayUnits": true
                        }
                    }
                },
                "fontSize": { 
                    "type": {
                        "formatting": {
                            "fontSize": true
                        }
                    }
                },
                "fontFamily": {
                    "type": {
                        "formatting": {
                            "fontFamily": true
                        }
                    }
                },
                "fontBold": {
                    "type": {
                        "bool": true
                    }
                },
                "fontUnderline": {
                    "type": {
                        "bool": true
                    }
                },
                "fontItalic": {
                    "type": {
                        "bool": true
                    }
                },
                "fontColor": {
                    "type": {
                        "fill": {
                            "solid": {
                                "color": true
                            }
                        }
                    }
                },
                "lineAlignment": {
                    "type": {
                        "formatting": {
                            "alignment": true
                        }
                    }
                }
            }
        }
    }

    จากนั้น ให้สร้าง getFormattingModel

        public getFormattingModel(): powerbi.visuals.FormattingModel {
        // Building data card, We are going to add two formatting groups "Font Control Group" and "Data Design Group"
        let dataCard: powerbi.visuals.FormattingCard = {
            description: "Data Card Description",
            displayName: "Data Card",
            uid: "dataCard_uid",
            groups: []
        }

        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group1_dataFont: powerbi.visuals.FormattingGroup = {
            displayName: "Font Control Group",
            uid: "dataCard_fontControl_group_uid",
            slices: [
                {
                    uid: "dataCard_fontControl_displayUnits_uid",
                    displayName:"display units",
                    control: {
                        type: powerbi.visuals.FormattingComponent.Dropdown,
                        properties: {
                            descriptor: {
                                objectName: "dataCard",
                                propertyName:"displayUnitsProperty"
                            },
                            value: 0
                        }
                    }
                },
                // FontControl slice is composite slice, It means it contain multiple properties inside it
                {
                    uid: "data_font_control_slice_uid",
                    displayName: "Font",
                    control: {
                        type: powerbi.visuals.FormattingComponent.FontControl,
                        properties: {
                            fontFamily: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontFamily"
                                },
                                value: "wf_standard-font, helvetica, arial, sans-serif"
                            },
                            fontSize: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontSize"
                                },
                                value: 16
                            },
                            bold: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontBold"
                                },
                                value: false
                            },
                            italic: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontItalic"
                                },
                                value: false
                            },
                            underline: {
                                descriptor: {
                                    objectName: "dataCard",
                                    propertyName: "fontUnderline"
                                },
                                value: false
                            }
                        }
                    }
                }
            ],
        };
        // Building formatting group "Font Control Group"
        // Notice that "descriptor" objectName and propertyName should match capabilities object and property names
        let group2_dataDesign: powerbi.visuals.FormattingGroup = {
            displayName: "Data Design Group",
            uid: "dataCard_dataDesign_group_uid",
            slices: [
                // Adding ColorPicker simple slice for font color
                {
                    displayName: "Font Color",
                    uid: "dataCard_dataDesign_fontColor_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.ColorPicker,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "fontColor"
                            },
                            value: { value: "#01B8AA" }
                        }
                    }
                },
                // Adding AlignmentGroup simple slice for line alignment
                {
                    displayName: "Line Alignment",
                    uid: "dataCard_dataDesign_lineAlignment_slice",
                    control: {
                        type: powerbi.visuals.FormattingComponent.AlignmentGroup,
                        properties: {
                            descriptor:
                            {
                                objectName: "dataCard",
                                propertyName: "lineAlignment"
                            },
                            mode: powerbi.visuals.AlignmentGroupMode.Horizonal,
                            value: "right"
                        }
                    }
                },
            ]
        };

        // Add formatting groups to data card
        dataCard.groups.push(group1_dataFont);
        dataCard.groups.push(group2_dataDesign);

        // Build and return formatting model with data card
        const formattingModel: powerbi.visuals.FormattingModel = { cards: [dataCard] };
        return formattingModel;
    }

    นี่คือบานหน้าต่างผลลัพธ์:

    Screenshot of format pane that results from the data card example.

    รีเซ็ตการตั้งค่าเป็นค่าเริ่มต้น

    บานหน้าต่างรูปแบบใหม่มีตัวเลือกในการตั้งค่าคุณสมบัติของการ์ดการจัดรูปแบบทั้งหมดเป็นค่าเริ่มต้นโดยการคลิกที่ปุ่ม รีเซ็ตเป็นค่าเริ่มต้น ที่ปรากฏในการ์ดเปิด

    Screenshot of format card reset to default button.

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

    let dataCard: powerbi.visuals.FormattingCard = {
    displayName: "Data Card",
    // ... card parameters and groups list

    revertToDefaultDescriptors: [
        {
            objectName: "dataCard",
            propertyName:"displayUnitsProperty"
        },
        {
            objectName: "dataCard",
            propertyName: "fontFamily"
        },

        // ... the rest of properties descriptors 
    ]
};

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

    Screenshot of format pane reset all settings to default button.

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

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

    การแปลเป็นภาษาท้องถิ่น

    สําหรับข้อมูลเพิ่มเติมเกี่ยวกับคุณลักษณะการแปลเป็นภาษาท้องถิ่น และการตั้งค่าสภาพแวดล้อมการแปลเป็นภาษาท้องถิ่น ดู เพิ่มภาษาท้องถิ่นไปยังวิ ชวล Power BI ของคุณ ใช้ตัวจัดการการแปลเป็นภาษาท้องถิ่นเพื่อจัดรูปแบบคอมโพเนนต์ที่คุณต้องการแปล:

    displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

    หากต้องการแปลยูทิลิตี้ การจัดรูปแบบยูทิลิตี้การจัดรูปแบบให้เป็นภาษาท้องถิ่น

    ทรัพยากร GitHub

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

    มีคำถามเพิ่มเติมหรือไม่? ถามชุมชน Power BI