使用开发人员工具创建自定义视觉对象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 和 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 证书,以允许在 Web 浏览器中加载视觉对象资产。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 操作系统Windows OS

  1. 选择“安装证书...”。Select Install Certificate....

  2. 选择“当前用户”,然后选择“下一步”。Select Current User and then select Next.

  3. 选择“将所有证书放在以下存储”,然后选择“浏览…”。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 startThis 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

可以将“我的视觉对象名称”替换为要对此视觉对象命名的名称。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 版本,请参阅 change log(更改日志)。For the current stable API version, see the change log. 有关预发行版本的详细信息,请参阅 roadmap(路线图)。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.json 的更多信息。Learn 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 编写视觉对象代码,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. 只要这两个文件在 tsconfig 中列出,此操作允许从其他文件引用导出的元素,而无需手动 require 它们。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.

了解更多有关 TypeScript 的详细信息。Learn more about TypeScript.

视觉对象样式 (Less)Visual style (Less)

视觉对象样式使用层叠样式表 (CSS) 进行处理。Visual styling is handled using cascading style sheets (CSS). 为方便起见,我们使用 Less 预编译器,该编译器支持某些高级功能,例如嵌套、变量、mixins、条件、循环等。如果不想使用其中任何一种功能,可以只在 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. 使用 @import 加载任何其他文件。Any additional files should be loaded using @import.

了解有关 Less 的更多信息。Learn 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