使用開發人員工具建立自訂視覺效果Use developer tools to create custom visuals

自訂視覺效果可讓您滿足使用者的需求,並契合應用程式的設計。Custom visuals allow you to meet your users' needs and match your app's design. 您可以使用開發人員工具來建立 Power BI 的自訂視覺效果。Learn how to create a custom visual for Power BI using the developer tools.

注意

這份文件可讓您輕鬆上手。You can use this document to get up and running. 如需深入的詳細資訊,請參閱 Power BI 視覺效果 Git 存放庫中的參考資訊。For more in-depth information, see the reference information within the Power BI Visuals git repo.

需求Requirements

  • 需具備 NodeJS 4.0 以上的版本 (建議 5.0 或更新版本) 下載 NodeJSNodeJS 4.0+ Required (5.0 or later recommended) Download NodeJS

安裝 NodeJS 和 Power BI 工具Install NodeJS and the Power BI tools

若要建立自訂視覺效果,您必須安裝 NodeJS。In order to create a custom visual, you will need to install NodeJS. 若要執行命令列工具,需具備 NodeJS。NodeJS is required to run the command line tools.

  1. 下載並安裝 NodeJSDownload and install NodeJS. 需具備 4.0 或更新版本,但建議使用 5.0 或更新版本。Version 4.0 or later is required but it is recommended to have 5.0 or later.
  2. 安裝命令列工具。Install the command line tools. 在命令提示字元中,執行下列命令。Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. 您可以執行下列命令,不需任何參數,即可確認工具是否安裝。You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

    您應該會看到下列說明的輸出。You should see the help output.

    
          +syyso+/
     oms/+osyhdhyso/
     ym/       /+oshddhys+/
     ym/              /+oyhddhyo+/
     ym/                     /osyhdho
     ym/                           sm+
     ym/               yddy        om+
     ym/         shho /mmmm/       om+
      /    oys/ +mmmm /mmmm/       om+
     oso  ommmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    ymmmy smmmh +mmmm /mmmm/       om+
    +dmd+ smmmh +mmmm /mmmm/       om+
          /hmdo +mmmm /mmmm/ /so+//ym/
                /dmmh /mmmm/ /osyhhy/
                  //   dmmd
                        ++
    
        PowerBI Custom Visual Tool
    
     Usage: pbiviz [options] [command]
    
     Commands:
    
     new [name]        Create a new visual
     info              Display info about the current visual
     start             Start the current visual
     package           Package the current visual into a pbiviz file
     update [version]  Updates the api definitions and schemas in the current visual. Changes the version if specified
     help [cmd]        display help for [cmd]
    
     Options:
    
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate
     

<a name"ssl-setup">

伺服器憑證安裝Server Certificate setup

若要啟用視覺效果的即時預覽,需具備受信任的 HTTPS 伺服器。To enable a live preview of your visual, a trusted https server is needed. 在開始之前,您必須先安裝 SSL 憑證,才能將視覺效果資產載入網頁瀏覽器。Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

注意

這是用於開發人員工作站的一次性安裝。This is a one-time setup for your developer workstation.

若要新增憑證,請執行下列命令。To add a certificate, run the following command.

pbiviz --install-cert

Windows OSWindows OS

  1. 選取 [安裝憑證...]。Select Install Certificate....

  2. 依序選取 [目前使用者] 和 [下一步]。Select Current User and then select Next.

  3. 依序選取 [Place all certificate in the following store] (將所有憑證放在下列存放區) 和 [瀏覽]。Select Place all certificate in the following store and select Browse....
  4. 依序選取 [信任的根憑證授權] 和 [確定]。Select Trusted Root Certification Authorities and then select OK. 選取 [下一步] 。Select Next.

  5. 選取 [完成] 。Select Finish.

  6. 在安全性警告對話方塊中,選取 [是]。Select Yes on the security warning dialog.

  7. 關閉任何已開啟的瀏覽器。Close any browsers that you have open.

注意

如果系統無法辨識憑證,您可能需要重新啟動電腦。If the certificate is not recognized, you may need to restart your computer.

OSXOSX

  1. 如果左上方的鎖為鎖定狀態,請選取該鎖以解除鎖定。If the lock in the upper left is locked, select it to unlock. 搜尋 localhost 並連按兩下憑證。Search for localhost and double click on the certificate.

  2. 選取 [永遠信任],然後關閉視窗。Select Always Trust and close the window.

  3. 輸入您的使用者名稱和密碼。Enter your username and password. 選取 [更新設定]。Select Update Settings.

  4. 關閉任何已開啟的瀏覽器。Close any browsers that you have open.

注意

如果系統無法辨識憑證,您可能需要重新啟動電腦。If the certificate is not recognized, you may need to restart your computer.

啟用開發人員視覺效果的即時預覽Enable live preview of developer visual

若要啟用自訂視覺效果的即時預覽,請遵循下列步驟。To enable a live preview of your custom visual, follow these steps. 這可讓您在編輯報表時,於 Power BI 服務中使用視覺效果。This allows the visual to be used within the Power BI service when editing reports.

  1. 瀏覽並登入 app.powerbi.comBrowse and sign into app.powerbi.com.
  2. 選取齒輪圖示,然後選取 [設定]。Select the gear icon and then select Settings.

  3. 依序選取 [開發人員] 和 [啟用開發人員視覺效果以供測試]。Select Developer and then select Enable developer visual for testing.

  4. 在 [視覺效果] 窗格中,選取 [開發人員視覺效果]。Select the Developer Visual in the Visualization pane.

    注意

    您必須已從開發電腦的視覺效果資料夾執行 pbiviz start,才能進行此動作。This requires that you have run pbiviz start from the visual folder on your development machine. 如需如何建立視覺效果的詳細資訊,請參閱本文的建立新的視覺效果For more information on creating your visual, see Create a new visual in this article.

  5. 在報表畫布中選取視覺效果。Select the visual in the report canvas. 您可以使用繫結其他視覺效果的相同方式來繫結資料。You can bind data in the same way you do other visuals.

現在,您可以著手開發自己的視覺效果。You can now begin developing your visual.

建立新的視覺效果Create a new visual

您可以執行下列命令來建立新的視覺效果專案。You can create a new visual project by running the following command.

pbiviz new My Visual name

您可以將 My Visual Name 取代為想要提供給視覺效果的名稱。You can replace My Visual Name with the name you want to give the visual. 之後,您也可以在產生的 pbiviz.json 檔案中,修改 namedisplayName 欄位以進行變更。This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

此命令會在命令執行所在目錄中建立新的資料夾,This command will create a new folder in the direct where the command was run. 並會產生視覺效果的基本入門範本。It will generate a basic starter template for your visual. 當命令完成時,您可以開啟該目錄,並使用喜好的編輯器以開始使用新的視覺效果。Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

在 Power BI 中測試視覺效果Testing your visual in Power BI

您可以在 Power BI 服務的報表和儀表板中測試視覺效果。You can test your visual within the Power BI service within reports and dashboards.

執行視覺效果Running your visual

您可以透過下列方式來執行視覺效果:You can run your visual by doing the following.

  1. 開啟提示。Open a prompt.
  2. 將目錄變更為您的視覺效果資料夾。Change your directory to be your visual folder. 這是包含 pbiviz.json 檔案的資料夾。This is the folder that contains the pbiviz.json file.
  3. 執行下列命令:Run the following command.

    pbiviz start
    

如果您的位置錯誤,則會看到類似如下的錯誤:If you are in the wrong location, you will see an error similar to the following.

    error  LOAD ERROR Error: pbiviz.json not found. You must be in the root of a visual project to run this command.
        at e (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:67:35)
        at Function.loadVisualPackage (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:62:16)
        at Object.<anonymous> (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\bin\pbiviz-start.js:43:15)
        at Module._compile (module.js:556:32)
        at Object.Module._extensions..js (module.js:565:10)
        at Module.load (module.js:473:32)
        at tryModuleLoad (module.js:432:12)
        at Function.Module._load (module.js:424:3)
        at Module.runMain (module.js:590:10)
        at run (bootstrap_node.js:394:7)

在 Power BI 中檢視視覺效果Viewing your visual in Power BI

若要在報表中檢視視覺效果,請移至該報表,然後選取 [視覺效果] 窗格中的視覺效果。To view your visual in a report, go to that report and select the visual within the Visualizations pane.

注意

在進行此動作之前,您必須先執行 pbiviz start 命令 (如執行視覺效果一節所述)。You must run the pbiviz start command before doing this as discribed in the Running your visual section.

接著,即會顯示視覺效果的入門範本。You will then see the starter template for the visual.

工具列項目Toolbar item 描述Description
重新整理視覺效果Refresh visual 如果已停用自動重新載入,請手動重新整理視覺效果。Manually refresh the visual if auto reload is disabled.
切換自動重新載入Toggle auto reload 開啟時,系統即會在每次儲存視覺效果檔案時自動更新視覺效果。When turned on, the visual will automatically update every time you save your visual file.
顯示資料檢視Show dataview 顯示視覺效果的基礎資料檢視以進行偵錯Shows the visual's underlying data view for debugging
取得說明Get help GitHub 中的文件Documentation within GitHub
傳送意見反應Send feedback 如果您有可以改善體驗的建議,歡迎告訴我們!Let us know if there is anyway we can improve the experience! (需要 GitHub 帳戶)(Requires GitHub account)

封裝視覺效果以用於 Power BI Desktop 並進行發佈Package your visual for use in Power BI Desktop and distribution

若要將視覺效果載入 Power BI Desktop,或在 Power BI 視覺化組件庫中與社群分享,您必須先產生 pbiviz 檔案。Before you can load your visual into Power BI Desktop, or share it with the community in the Power BI Visual gallery, you'll need to generate a pbiviz file.

您可以透過下列方式來封裝視覺效果:You can package your visual by doing the following.

  1. 開啟提示。Open a prompt.
  2. 將目錄變更為您的視覺效果資料夾。Change your directory to be your visual folder. 這是包含 pbiviz.json 檔案的資料夾。This is the folder that contains the pbiviz.json file.
  3. 執行下列命令:Run the following command.

    pbiviz package
    

此命令會在視覺化專案的 dist/ 目錄中建立 pbivizThis command will create a pbiviz in the dist/ directory of your visual project. 它會覆寫已存在的 pbiviz 檔案 (若有的話)。If there is already a pbiviz file present, it will be overwritten.

更新視覺效果 API 版本Updating the visuals API version

當您使用 pbiviz new 建立視覺效果時,系統會將適當的 API 類型定義和 json 結構描述複本複製到您的視覺效果目錄。When you create a visual using pbiviz new, a copy of the appropriate API type definitions and json schemas are copied into your visual's directory. 您可以使用 pbiviz update 命令,視需要更新這些檔案。You can use the pbiviz update command to update these files if needed. 如果我們發行過去 API 版本的修正程式,或您想要更新至最新的 API 版本,此功能就非常實用。This can be useful if we release a fix for a past API version or if you want to update to the latest API version.

更新現有的 API 版本Updating your existing API version

如果我們發行現有 API 的更新,您可以透過下列方式取得最新版本。If we release an update to an existing API, you can get the latest version by doing the following.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update

這會從 npm 下載最新的工具,包括已更新的類型定義與結構描述。This will download the latest tools from npm which include the updated type definitions and schemas. 使用 pbiviz update 時,最新版本即會覆寫 pbiviz.json 檔案的 apiVersion 屬性。Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

升級至不同的 API 版本Upgrading to a different API version

您可以使用上述的相同步驟,更新至不同的 API 版本。You can update to a different API version by using the same steps as mentioned above. 您可以明確指定您想要使用的 API 版本。You can explicitly specify the API version you want to use.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update 1.2.0

這會將您的視覺效果更新至 API 1.2.0 版。This would update yoru visual to API version 1.2.0. 您可以將 1.2.0 取代為任何想要使用的版本。You can replace 1.2.0 with whatever version your wanting to use.

警告

工具所使用的預設 API 版本一律為 API 的穩定版本。The default API version used by the tools will always be the stable version of the API. 比預設 API 版本更晚的任何版本皆為不穩定版本而且可能隨時變更。Any versions later than the default API version are unstable and subject to change. 不穩定版本可能會發生非預期的行為,並在 Power BI 服務與 Power BI Desktop 之間出現不一致的行為。They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. 如需目前的穩定 API 版本,請參閱變更記錄檔For the current stable API version, see the change log. 如需發行前版本的詳細資訊,請參閱藍圖For more information about pre-release versions, see the roadmap.

在視覺效果專案內Inside the visual project

您的視覺效果專案是在執行 pbiviz new 命令時建立的資料夾。Your visual project is the folder that gets created when you run the pbiviz new command.

檔案結構File structure

項目Item 描述Description
assets/assets/ 用來儲存視覺效果資產 (圖示、螢幕擷取畫面等)。Used to store visual assets (icon, screenshots, etc).
dist/dist/ 當您執行 pbiviz package 時,會於此處產生 pbiviz 檔案。When you run pbiviz package, the pbiviz file will be generated here.
src/src/ 您的視覺效果的 TypeScript 程式碼。Typescript code for your visual.
style/style/ 視覺效果的 Less 樣式。Less styles for your visual.
.gitignore.gitignore 告知 git 忽略在存放庫中不應追蹤的檔案。Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json 用來定義視覺效果的功能Used to define the capabilities of your visual.
package.jsonpackage.json npm 會使用此項目來管理模組。Used by npm to manage modules.
pbiviz.jsonpbiviz.json 主要設定檔。Main configuration file.
tsconfig.jsontsconfig.json Typescript 編譯器設定。Typescript compiler settings. 深入了解 tsconfig.jsonLearn more about tsconfig.json.

pbiviz.jsonpbiviz.json

這個檔案是視覺效果的主要設定檔,This file is the main configuration file for your visual. 其中包含您建置視覺效果所需的中繼資料以及檔案相關資訊。It contains metadata, as well as information about your files, needed to build your visual.

{
    "visual": {
        "name": "myVisual", // internal visual name (should not contain spaces)
        "displayName": "My Visual!", // visual name displayed to user (used in gallery)
        "guid": "PBI_CV_xxxxxxx", // a unique id for this visual MUST BE UNIQUE
        "visualClassName": "Visual" // the entry class for your visual
        "version": "1.0.0", // visual version. Should be semantic version (increment if you update the visual)
        "description": "", // description used in gallery
        "supportUrl": "", // url to where users can get support for this visual
        "gitHubUrl": "" // url to the source in github (if applicable)
    },
    "apiVersion": "1.0.0", //API version this visual was created with
    "author": {
        "name": "", // your name
        "email": "" // your e-mail
    },
    "assets": {
        "icon": "assets/icon.png" // relative path to your icon file (20x20 png)
    },
    "style": "style/visual.less", // relative path to your less file
    "capabilities": "capabilities.json" // relative path to your capabilities definition 
}

視覺效果來源 (TypeScript)Visual source (TypeScript)

視覺效果程式碼應該以 TypeScript 來撰寫,其為 JavaScript 的超集合並支援更進階的功能且可優先存取 ES6/ES7 功能。Visual code should be written in TypeScript, which is a superset of JavaScript that support more advanced features and early access to ES6/ES7 functionality.

所有 TypeScript 檔案應儲存在 src/ 目錄,並新增至 tsconfig.json 中的 files 陣列。All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. 這可讓 TypeScript 編譯器將其載入,並決定載入順序。This allows the TypeScript compiler to load them and in what order.

視覺效果建置好之後,就會將所有 TypeScript 編譯成單一的 JavaScript 檔案。When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. 這可讓您從其他檔案參考匯出的項目,而不需手動針對檔案使用 require (只要 tsconfig 中列出這兩個檔案即可)。This allows you to reference exported elements from other files without needing to manually require them as long as both files are listed in the tsconfig.

依據視覺效果的建立需求,您可以建立任意數量的檔案與類別。You can create as many files and classes as you need to create your visual.

深入了解 TypeScriptLearn more about TypeScript.

視覺效果樣式 (Less)Visual style (Less)

系統會使用階層式樣式表 (CSS) 來處理視覺效果樣式。Visual styling is handled using cascading style sheets (CSS). 為了便於使用,我們會使用可支援部分進階功能 (例如巢狀結構、變數、mixin、條件、迴圈等等) 的 Less 預先編譯器。如果您不想使用上述任何功能,只需在 Less 檔案中撰寫一般 CSS 即可。For your convience, we use the Less pre-compiler which supports some advanced features such as nesting, variables, mixins, conditions, loops, etc. If you don't want to use any of these features, you can just write plain CSS in the Less file.

您應將所有 Less 檔案儲存在 style/ 目錄中。All Less files should be stored in the style/ directory. 系統會載入 pbiviz.json 檔案內之 style 欄位下方所指定的檔案。The file specified under the style field within your pbiviz.json file will be loaded. 若要載入任何其他檔案,則應該使用 @importAny additional files should be loaded using @import.

深入了解 LessLearn more about Less.

偵錯Debugging

如需偵錯自訂視覺效果的祕訣,請參閱偵錯指南For tips about debugging your custom visual, see the debugging guide.

將視覺效果提交至 AppSourceSubmit your visual to AppSource

您可以列出視覺效果供其他人使用,但要將它提交至 AppSource。You can list your visual for others to use but submitting it to AppSource. 如需此程序的詳細資訊,請參閱將自訂視覺效果發佈至 AppSourceFor more information on this process, see publish custom visuals to AppSource.

疑難排解Troubleshooting

找不到 pbiviz 命令 (或類似的錯誤)Pbiviz command not found (or similar errors)

如果您在終端機/命令列中執行 pbiviz,您應該會看到說明畫面。If you run pbiviz in your terminal / command line, you should see the help screen. 如果未顯示,則表示安裝有誤。If not, it is not installed correctly. 請確定您至少已安裝 NodeJS 4.0 版。Make sure you have at least the 4.0 version of NodeJS installed.

如需詳細資訊,請參閱安裝 NodeJS 和 Power BI 工具...For more information, see Install NodeJS and the Power BI tools...

在 [視覺效果] 索引標籤中找不到偵錯視覺效果的功能Cannot find the debug visual in the Visualizations tab

[視覺效果] 索引標籤中的偵錯視覺效果功能,看起來像個提示圖示。The debug visual looks like a prompt icon within the Visualizations tab.

如果未顯示,請確定您已在 Power BI 設定中加以啟用。If you don't see it, make sure you have enabled it within the Power BI settings.

注意

偵錯視覺效果功能目前僅可在 Power BI 服務中使用;Power BI Desktop 或行動裝置應用程式皆尚未提供。The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. 封裝的視覺效果仍可在每個地方運作。The packaged visual will still work everywhere.

如需詳細資訊,請參閱啟用開發人員視覺效果的即時預覽...For more information, see Enable live preview of developer visual...

聯繫不到視覺效果伺服器Can't contact visual server

從視覺效果專案的根目錄中,透過終端機/命令列的 pbiviz start 命令,來執行視覺效果伺服器。Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. 如果伺服器正在執行,原因很可能是因為您未正確安裝 SSL 憑證。If the server is running, it is likely that your SSL vertificates weren't installed correctly.

如需詳細資訊,請參閱執行視覺效果伺服器憑證安裝For more information, see Running your visual or Server certificate setup.

後續步驟Next steps

Power BI 中的視覺效果Visualizations in Power BI
Power BI 中的自訂視覺效果Custom Visualizations in Power BI
將自訂視覺效果發佈至 Office 市集Publish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

有其他問題嗎?More questions? 嘗試在 Power BI 社群提問Try asking the Power BI Community