--- title: "Пользовательские виджеты" slug: "custom-widgets-2" updated: 2026-10-22T14:26:11Z published: 2026-10-22T14:26:11Z canonical: "support.tulip.co/custom-widgets-2" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.tulip.co/llms.txt > Use this file to discover all available pages before exploring further. # Пользовательские виджеты *Создавайте собственные виджеты в Tulip с помощью HTML, CSS и JavaScript* Who can use this feature Users on Professional plans and above. Requirement to use Custom Widget Please allow Outgoing access to Custom Widgets. See [Networking requirements for a Tulip Cloud Deployment](https://support.tulip.co/docs/networking-requirements-for-a-tulip-cloud-deployment) to learn more.* *.tulip-custom-widgets.com Элементы, которые вы перетаскиваете в своё приложение, называются виджетами. Это могут быть кнопки, изображения, поля ввода и всё остальное, доступное на панели инструментов. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459748507.png) Пользовательские виджеты позволяют вам писать собственный код и создавать собственные виджеты, которые затем можно перетаскивать в приложение и взаимодействовать с ними. Эта возможность позволяет пользователям Tulip расширять границы возможностей Tulip. Посмотрите следующее видео, чтобы ознакомиться с этой функцией: [Embedded content](https://www.youtube.com/embed/0T0NbPdR7PM) **Ознакомьтесь с доступными [пользовательскими виджетами в библиотеке Tulip](https://tulip.co/library/?query=Widgets).** ## Основы работы с пользовательскими виджетами Экран управления пользовательскими виджетами находится на странице настроек вашей учетной записи. Здесь вы можете создавать и удалять виджеты. Редактор пользовательских виджетов позволяет писать код виджета, создавать пропсы и события, а также просматривать виджет в режиме предварительного просмотра. Ниже приведена схема, описывающая, что такое пропсы и события: ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459772614.png) **Props:** Props — это данные, которые совместно используются пользовательскими виджетами и приложениями Tulip. Props будут отображаться в редакторе приложений и позволят разработчикам приложений выбирать, какие переменные, записи таблиц или другую информацию связывать с данным prop. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459780280.png) **События:** события — это сигналы, которые ваш виджет может отправлять в приложение. События позволяют приложению реагировать с помощью триггера и могут передавать информацию вместе с собой. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459790204.png) Доступ к пользовательским виджетам осуществляется через раскрывающийся список «Пользовательские» в редакторе приложений. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459791297.png) ## Создание виджета Permission Required Only users with access to account settings (i.e. Account Owners) or [users with specific permission](/r230/docs/customize-user-roles) to access the custom widget page can use the custom widget editor. Экран редактора виджетов разделен на четыре раздела. Код, который вы вводите в левом нижнем разделе, появится в разделе предварительного просмотра, как только вы щелкните в этом разделе. Значения свойств можно изменять непосредственно в разделе предварительного просмотра для тестирования. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_459796104.png) Существуют специальные функции для работы с пропсами и событиями. ### Получение значения пропса Warning It is not guaranteed that the prop being used by a widget will load before that widget loads, so all props associated with Table record fields, Aggregations, or any other dynamic value should include logic to support cases where they are null at the point the widget is loaded. See [this](/r230/docs/custom-widgets-overview#do-something-when-a-prop-changes) section for details on triggering logic when a prop changes. `//Получение значения проп getValue('My Prop');``//Сохранение проп в переменной let myVariable = getValue('My Prop');` ### Выполнить действие при изменении значения пропса `//Выполнить действие при каждом изменении значения пропса getValue('My Prop', (internalVariable) => { doSomething(internalVariable);});` ### Установка значения пропса ``` //Установить значение текстового проп на 'hello!' setValue('My Text Prop', 'hello!'); //Установить значение элемента в объекте setValue('My Object Prop', { 'Key inside object': 'new value' });``` ### Вызов события ```**Запуск события** fireEvent('event', *payload*); //Срабатывание события без данных fireEvent('My Event'); //Срабатывание события с данными fireEvent('My Event', myVariable);``` На следующей схеме показан поток информации через пользовательский виджет в приложении. Данные входной переменной сохраняются в свойстве. Изменение значения сигнализирует о событии, при котором триггер сохраняет данные в выходную переменную. ![Custom Widget App Setup Diagram](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widget%20App%20Setup%20Diagram.jpg){height="" width=""} ## Демонстрация сборки виджета ![Video](https://www.youtube.com/embed/H08-W2M2Ypo?rel=0){height="576" width="1024"} ## Импорт/экспорт приложений См. раздел [«Импорт и экспорт»](/r230/docs/import-export), чтобы узнать больше об этой функции. ### Экспорт 1. В обзоре пользовательских виджетов выберите **меню с тремя точками** рядом с виджетом, который хотите экспортировать. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477703991.png){height="" width=""} 1. Выберите **«Экспорт**». ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704053.png){height="" width="800"} ### Импорт 1. На экране обзора пользовательских виджетов выберите **меню с тремя точками** вверху. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704175.png){height="" width="800"} 1. Выберите **«Импорт**». ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477704228.png){height="" width="350"} 1. Найдите файл пользовательского виджета в формате .json. ## Включение внешних библиотек Внешние библиотеки расширяют возможности пользовательских виджетов. Внешние библиотеки берут на себя ручную работу по написанию HTML непосредственно в JavaScript. Внешние библиотеки необходимо включить для каждого виджета, в котором вы хотите их использовать. 1. Находясь в своем виджете, нажмите на **меню с тремя точками** в правом верхнем углу страницы. ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477684182.png){height="" width=""} 1. Выберите **«Включить внешнюю библиотеку**». ![](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20Widgets%20Overview_477684247.png){height="" width="250"} 1. Выберите **расширение**, которое хотите включить. ![Screenshot 2025-02-06 at 9.13.14 AM](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-02-06%20at%209.13.14%20AM.png){height="" width=""} Ниже приводится краткое описание функций каждого расширения: * **jQuery** — позволяет более удобно выбирать HTML-элементы и манипулировать ими. * **D3 —** «золотой стандарт» визуализации данных; требует серьезных усилий для освоения, но обеспечивает огромную гибкость. * **Google Visualization —** отличный инструмент для визуализации данных, как следует из названия. * **Lodash —** предоставляет множество инструментов, упрощающих работу с типами данных JavaScript. * **ChartJS —** пожалуй, самая простая библиотека для построения графиков с огромным количеством онлайн-ресурсов. * **Moment —** предоставляет множество инструментов для работы с датами и временем. ## Версия среды выполнения Способ загрузки пользовательских виджетов в новой среде выполнения был обновлен (см. [«Улучшения пользовательских виджетов»](/r230/docs/custom-widget-improvements)). Это изменение влияет на то, когда вы можете надежно получить доступ к свойствам вашего виджета, например к тем, которые извлекаются с помощью `getValue()`. Чтобы узнать, какую версию среды выполнения использует ваш виджет: * На странице **списка пользовательских виджетов** или в редакторе: если рядом с названием виджета есть значок **«Legacy»**, значит, виджет использует старую среду выполнения. Если значка нет, виджет использует новую среду выполнения. * На боковой панели с информацией о пользовательском виджете смотрите раздел **«Среда выполнения** ». * В **настройках разрешений** пользовательского виджета, если переключатель **«Среда выполнения пользовательского виджета»** включен, значит виджет использует новую среду выполнения. :::(Info) (NOTE) By default, newly created Custom Widgets use the old runtime. ::: Чтобы переключить версию среды выполнения для пользовательского виджета, воспользуйтесь переключателем **«Среда выполнения пользовательского виджета»** в **настройках разрешений**.![Custom widget runtime toggle](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Custom%20widget%20runtime%20toggle.png){height="" width=""} ## Примеры Ниже приведены несколько пользовательских виджетов из [библиотеки Tulip](https://tulip.co/library/), которые иллюстрируют описанные выше возможности: ### Простой виджет таймера [Простой виджет таймера](https://library.tulip.co/apps/simple-timer-widget) Удобный в использовании виджет таймера для отслеживания прошедшего времени во время выполнения рабочих процессов приложения. Операторы могут запускать, останавливать и сбрасывать таймер непосредственно из интерфейса приложения, что делает его полезным для хронометража задач или процессов. ![Screenshot 2025-07-02 at 15.33.20.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.33.20.png){height="" width=""} ### Виджет «Радиальный индикатор» [Виджет радиального индикатора](https://library.tulip.co/apps/radial-gauge-widget) Этот виджет визуально отображает числовые значения с помощью настраиваемого радиального индикатора. Он идеально подходит для отображения таких показателей, как скорость работы оборудования, температура или ход выполнения задачи, в быстром и понятном формате. ![Screenshot 2025-07-02 at 15.34.22.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.34.22.png){height="" width=""} ### Виджет «Временная шкала» [Виджет «Временная шкала»](https://library.tulip.co/apps/timeline-widget) Отображает события или этапы на горизонтальной временной шкале, помогая пользователям с первого взгляда визуализировать этапы процесса, выполненные задачи или данные, связанные со временем. ![Screenshot 2025-07-02 at 15.34.59.png](https://cdn.document360.io/7c6ff534-cad3-4fc8-9583-912c4016362f/Images/Documentation/Screenshot%202025-07-02%20at%2015.34.59.png){height="" width=""} ## Рекомендации ### 1. Предотвращайте непреднамеренные побочные эффекты от кода виджета, выполняемого при загрузке Tulip запускает фактический код вашего виджета при каждом его рендеринге — не только в Player, но и в редакторе пользовательских виджетов, редакторе приложений и в режиме предварительного просмотра станции. Это позволяет получить точный предварительный просмотр вашего виджета в режиме реального времени. Любой код, вызывающий побочные эффекты (например, вызовы API, запись в таблицы, уведомления) на верхнем уровне вашего скрипта, выполняется каждый раз при рендеринге виджета, в том числе при каждом повторном открытии виджета в редакторе или перезагрузке предварительного просмотра. Связывайте все, что имеет реальные последствия, с явным триггером (например, нажатие кнопки, вызов `` `fireEvent` `` в ответ на действие пользователя или изменение свойства), а не запускайте это автоматически при загрузке. ```// ПРАВИЛЬНО: срабатывает только тогда, когда приложение явно запрашивает это getValue('TriggerIncrement', (shouldIncrement) => { if (shouldIncrement) { fetch("https://api.example.com/increment-counter", { method: "POST" }); }}); // НЕПРАВИЛЬНО: срабатывает при каждой загрузке виджета, в том числе в редакторе и при предварительном просмотреfetch("https://api.example.com/increment-counter", { method: "POST" });```Если виджету необходимо автоматически загружать данные, используйте конечную точку, доступную только для чтения, или идемпотентную конечную точку, чтобы повторные загрузки не вызывали нежелательных последствий. ### 2. Проводите итеративное тестирование без вызова реальных побочных эффектов При разработке виджета, который вызывает производственный API с реальными побочными эффектами, указывайте на тестовую или промежуточную конечную точку до завершения итераций, а затем переключайтесь на производственную конечную точку перед публикацией. Это предотвращает дублирование записей, уведомлений или других побочных эффектов, связанных с редактированием и предварительным просмотром вашего виджета. Для действий, которые должны выполняться в производственной среде даже после публикации, встройте подтверждение в собственный интерфейс виджета, а не полагайтесь на время загрузки. Требуя видимого действия (например, нажатия кнопки), пользователь, просматривающий виджет, получает контроль над тем, когда произойдет эффект. ```// Требуется явное нажатие перед запуском реального действия,// независимо от того, сколько раз сам виджет был отображенdocument.getElementById('submitBtn')?.addEventListener('click', () => { fetch("https://api.example.com/submit-order", { method: "POST" });}); ``` ### 3. Управление пропсами — проверка значения пропса Убедитесь, что ваш пользовательский виджет надёжно обрабатывает данные. Пропсы — это способ передачи информации в ваш виджет, но их значения могут изменяться или изначально быть неопределёнными. Несмотря на то, что пропсы имеют заданный тип, изначально они могут быть неопределёнными, что может привести к ошибкам в коде вашего пользовательского виджета. **Соблюдение надёжного шаблона предотвращает ошибки и делает ваш виджет более отказоустойчивым.** В приведенном ниже примере в качестве второго параметра функции `getValue` используется функция обратного вызова. Эта функция обратного вызова будет запускаться каждый раз, когда пользовательский виджет получает обновленное значение проп. Поскольку начальное значение проп может быть неопределенным, а позже может быть получено обновлённое значение, необходимо обеспечить применение конфигурации сразу после получения обновлённого значения. Использование getValue без функции обратного вызова возвращает значение проп на данный момент выполнения кода. `getValue('config', function(config) { if (config) { applyConfiguration(config); }});` Следующий пример не рекомендуется, поскольку начальное значение проп может быть undefined:`const config = getValue('config');applyConfiguration(config);` ### 4. Обработка событий — проверка данных Данные события имеют тип. Хотя вызов события с неверным типом данных не приведёт к сбою или остановке выполнения кода вашего пользовательского виджета, **рекомендуется использовать собственные проверки, чтобы гарантировать, что данные, отправляемые в fireEvent, прошли валидацию и имеют правильный тип**. Такой подход предотвращает непредвиденное поведение и делает ваш код более предсказуемым. `if (data != null && typeof data === 'string') { fireEvent(eventName, data);} else { // При необходимости обработайте случай с недопустимыми данными.}` ### 5. Используйте функцию обратного вызова для асинхронного доступа к проп При вызове `setValue()` обновление проп происходит **асинхронно**. Это означает, что оно не происходит мгновенно, поскольку ваш пользовательский виджет взаимодействует с основным приложением из iframe. Запрос `setValue()` отправляется, но ваш код продолжает выполняться, не дожидаясь, пока изменение вступит в силу. Если вы попытаетесь сразу же после этого использовать `getValue()`, скорее всего, получите старое значение. **Чтобы получить самые актуальные данные, всегда используйте `getValue()` с функцией обратного вызова.** Функция обратного вызова выполняется только после успешного обновления проп, что гарантирует работу с самой свежей информацией. Следующий пример демонстрирует эту рекомендуемую практику:```// ПРАВИЛЬНО: Асинхронный доступ к значению свойства const newConfig = { setting: 'value' }; setValue('config', newConfig); // Функция обратного вызова запустится после завершения обновления проп.getValue('config', function(updatedConfig) { console.log('Проп обновлен. Новая конфигурация:', updatedConfig); // Выполните какие-либо действия с гарантированно новым значением applyConfiguration(updatedConfig);});``` Следующий пример показывает, чего следует избегать:```// НЕПРАВИЛЬНО: Это может работать не так, как ожидаетсяconst newConfig = { setting: 'value' };setValue('config', newConfig); // Скорее всего, в консоль будет выведено старое значение, а не новое.const currentConfig = getValue('config'); ``` ### 6. Используйте поддерживаемые заголовки при вызовах API При выполнении внешних вызовов API из пользовательских виджетов будьте осторожны с HTTP-заголовками, чтобы избежать проблем с CORS (Cross-Origin Resource Sharing). Пользовательские виджеты работают в среде iframe с определёнными ограничениями безопасности. **Используйте только те заголовки, которые явно поддерживаются.** Установка неподдерживаемых заголовков, таких как Content-Type или других пользовательских заголовков, может вызвать ошибки CORS и помешать работе ваших вызовов API. Следующий пример иллюстрирует эту рекомендуемую практику`:// ПРАВИЛЬНО: Простой вызов API без пользовательских заголовковfetch("https://akhatri.bulb.cloud/api/v3/w/1/tables", { headers: { Authorization: "<API key>", },}) .then((response) => response.json()) .then((data) => console.log(data)) .catch((error) => console.error("Ошибка:", error));` Следующий пример показывает, чего следует избегать`:// НЕПРАВИЛЬНО: Установка заголовка Content-Type приведёт к проблемам с CORSfetch("https://api.example.com/data", { headers: { Authorization: "<API key>", "Content-Type": "application/json", // Это приведёт к ошибкам CORS },})` Troubleshoot CORS error If you encounter CORS errors, first remove any custom headers you've set (especially Content-Type) and test with minimal headers. The iframe security model restricts which headers can be set from custom widgets. ### 7. Инициализируйте виджеты в зависимости от вашей среды выполнения Дополнительную информацию см. в разделе [«Версия среды выполнения](/r230/docs/custom-widgets#runtime-version) ». #### Новая среда выполнения В новой среде выполнения атрибут `src` возвращает пустой HTML-файл-оболочку. После загрузки этот файл-оболочка отправляет сообщение родительскому приложению. Родительское приложение отправляет код пользовательского виджета, служебные функции (такие как `getValue()`) и начальные значения свойств для вставки в iframe. Из-за этого события `DOMContentLoaded` и `window.onload` срабатывают при загрузке пустой оболочки, до того как код вашего виджета будет вставлен. Любой обработчик, привязанный к этим событиям, регистрируется слишком поздно: событие уже сработало, поэтому обратный вызов никогда не выполняется. Код внутри этих обработчиков пропускается без уведомления, как показано в примере ниже: `document.addEventListener('DOMContentLoaded', function() { // Срабатывает при загрузке SHELL, до вставки пользовательского кода // Пользовательский код ещё даже не вставлен! const myProp = getValue('myProp'); // ОШИБКА: getValue не определено});` **В custom widgets не нужно использовать `DOMContentLoaded` или `window.onload`**. Tulip загружает ресурсы в следующем порядке: сторонние библиотеки, пользовательский HTML, а затем JavaScript. К моменту выполнения вашего JavaScript DOM уже доступен. Вы можете обращаться к элементам DOM напрямую, не дожидаясь события загрузки, как показано в примере ниже: `// Можно вызывать напрямую — к моменту выполнения этого кода DOM уже загружен.const btn = document.getElementById('my-btn');` #### Старая среда выполнения В старой среде выполнения атрибут `srcDoc` вставляет код пользовательского виджета в iframe вместе с служебными функциями, такими как `getValue()`, и начальными значениями свойств. Поскольку код виджета с самого начала является частью документа, `getValue()` и ваши свойства доступны сразу же после загрузки содержимого iframe.В результате события `DOMContentLoaded` и `window.onload` работают в старой среде выполнения так, как и ожидается, что показано в следующем примере: `document.addEventListener('DOMContentLoaded', function() { // Срабатывает, когда HTML-код пользователя готов // Свойства уже доступны const myProp = getValue('myProp'); // Работает сразу});` {{snippet.Нашли ли вы то, что искали?}}