Создание пользовательского визуального элемента с помощью средств разработчика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. Дополнительные справочные сведения см. в репозитории Git визуальных элементов Power BI.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 BIInstall 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. Скачайте и установите NodeJS.Download 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

ОС WindowsWindows 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. Выберите пункт Always Trust (Всегда доверять) и закройте окно.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.com.Browse 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. Позже его можно изменить, изменив поля name и displayName в созданном файле pbiviz.json.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 BITesting 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 BIViewing 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
    

Эта команда создаст файл pbiviz в каталоге dist/ проекта визуального элемента.This 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.

Обновление имеющейся версии APIUpdating 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 свойство apiVersion перезапишется с помощью последней версии в файле pbiviz.json.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 по умолчанию, используемая средствами — это постоянно стабильная версия.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/, а также их необходимо добавить к массиву files в файле tsconfig.json.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.

Дополнительные сведения см. на странице TypeScript.Learn more about TypeScript.

Стиль визуального элемента (Less)Visual style (Less)

Стиль визуального элемента обрабатывается с помощью каскадных таблиц стилей (CSS).Visual styling is handled using cascading style sheets (CSS). Для удобства предварительный компилятор Less используется для поддержки некоторых дополнительных функций, таких как вложения, переменные, примеси, условия, циклы и т. д. Если в использовании любой из этих функций нет необходимости, можно просто записать обычные CSS в файле Less.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. Файл, указанный в поле style файла pbiviz.json, будет загружен.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. Дополнительные сведения см. в статье Публикация пользовательских визуализаций в Магазине Office.For 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 BIVisualizations in Power BI
Пользовательские визуализации в Power BICustom Visualizations in Power BI
Публикация пользовательских визуализаций в Магазине OfficePublish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

Появились дополнительные вопросы?More questions? Попробуйте задать вопрос в сообществе Power BI.Try asking the Power BI Community