Что такое api key в figma
figma.parameters
These are methods and properties available on the figma.parameters global object. See Accepting Parameters as Input for more details.
The input event is fired on every key press as the user is entering parameters for a plugin in quick actions. The expectation is that plugin will respond to these events by calling one of the APIs result object.
on(type: «input», callback: (event: ParameterInputEvent) => void): void
Register a handler for user input events in the quick action UI.
once(type: «input», callback: (event: ParameterInputEvent) => void): void
off(type: «input», callback: (event: ParameterInputEvent) => void): void
The result object passed to the ‘input’ event handler contains API for controlling the UI that the user sees while entering parameter values. Most importantly it is able to provide the list of autocomplete suggestions that the user can choose from as they type.
But the result object also enables showing error messages and loading states.
setSuggestions(suggestions: Array ): void
Sets the list of autocomplete suggestions to be displayed in the quick action UI.
If you only want to provide a string suggestion, and don’t need metadata or icons, you can use an array of simple string values. For example
However the API also allows providing more information with each suggestion:
The name property contains the text to display to the user in the autocomplete suggestions. This property is required.
The data property allows associating hidden metadata with a given autocomplete suggestion. This data is passed back to the plugin as the parameter’s value if the user chooses this option. If no data property is provided, it defaults to the value of the name property. I.e. the value of the parameter will be the string that was displayed to the user.
setError(message: string): void
Displays an error message to the user instead of a list of autocomplete suggestions. When this function is called, the user is prevented from moving on to the next parameter without first changing the input for the current parameter.
This is useful to signal to the user that they have entered an invalid value and provide them instruction for how to correct the input.
You can also use this as a way to validate pre-conditions, like current selection, or some state of the current document. To do this, in the ‘input’ event handler for the first parameter key, check the that all pre-conditions are fulfilled and call setError with an appropriate error message if they are not, unconditionally of what the current query value is.
This function is not available on parameters with allowFreeform set. The purpose of allowFreeform is to allow users to enter arbitrary values and so Figma doesn’t guarantee that the plugin gets an opportunity to handle an input event and call setError before the user moves on to the next parameter.
For a full example of what this can look like, see the Resizer sample plugin
setLoadingMessage(message: string): void
You can call setLoadingMessage multiple times in order to provide an updated message.
ParameterValues is the type used to pass values for parameters into plugins. It’s a mapping from parameter keys, which come from the manifest, to the value that the user typed or chose in the autocomplete suggestions. Depending on how your plugin specified the suggestion when calling setSuggestions the value will resolve to:
Как мы создавали свой плагин для Figma
Рассказывает Андрей, JS Developer в Noveo
Наша команда дизайнеров и PM в своей работе часто сталкивается с теми или иными рутинными задачами. Представьте себе, что заказчик дал нам задачу на разработку дизайна мобильного приложения. Бизнес-аналитики расписали требования и функциональность.
Далее в дело вступают дизайнеры, которые постепенно отрисовывают экраны и согласовывают их с конечным заказчиком. В итоге набралось более 250 экранов с различными состояниями. Вот здесь скрывается очень сложная задача. Возникает вопрос: каким же образом нам вести учет статусов по каждому экрану (TODO, В работе, Готов к ревью, Принят и т.д.)? Особенно остро этот вопрос встает, если дизайн-проект достаточно большой, а обсуждение ведется в ежедневном режиме.
До того, как мы нашли решение этой проблемы, дизайнер вел специальную таблицу Google Sheet, куда переносил все экраны из Figma со ссылками на экран, текущим статусом и историей. У этого подхода были вагон и маленькая тележка недостатков:
Никто не любит монотонные действия, особенно когда результат от проделанной работы устаревает уже на следующий день. Вот и наши PM и дизайнеры хотели бы что-то более удобное, простое и, желательно, автоматизированное.
Пример того, как выглядит типичный файл FIGMA для мобильного приложения. Конкретно тут более 400 экранов
Часть 1. Разбираемся с текущим процессом
В процессе общения с ребятами со стороны дизайна и PM мы выяснили, что в Figma нет нативной возможности назначить статус на какой-то экран. Странно, что разработчики до сих пор не прикрутили такую фичу, но оставим это на их совести.
Пользователи Figma все же нашли несколько интересных решений проблемы. Самое популярное — добавлять вокруг экрана рамку (обводку) того или иного цвета, который говорит о статусе экрана.
Примеры статусов для экранов на одном из проектов
Это достаточно интересное решение, в котором есть ряд подводных камней:
Флоу по добавлению обводки
Стоить отметить, что существуют готовые плагины для Figma, которые немного упрощают эту процедуру, но они нам не подходили из-за невозможности их дальнейшей интеграции с Google API.
После общения с инициативной группой конечные требования к разрабатываемому решению стали следующими:
Часть 2. Figma API
Первое, за что хочется одновременно и поблагодарить разработчиков и ненавидеть их, — API Figma. С одной стороны, оно очень удобное, детально описанное, логичное. За все время его изучения мы ни разу не наступили ни на какие грабли.
Весь проект Figma представлен в виде одного огромного JSON с кучей полей, описывающих те или иные свойства экрана (обводки, названия экранов, дочерние элементы и так далее).
С другой стороны, очень жаль, что это обычный REST, а не GraphQL. Этот недостаток проявился фактически сразу, как только мы попытались запросить JSON-представление нашего текущего проекта. Для этого надо было отправить запрос на https://www.figma.com/file/:key/, где key — уникальный ID документа, который вы хотите запросить.
Напомню, проект состоял из 400+ скринов. Общий вес JSON составил 14.5 Mb. Да, GraphQL не помешал бы…
Немного разобравшись с документацией, мы нашли необходимые url-адреса, позволяющие получить JSON-скелет нужного нам проекта. Ресерч был приостановлен, и мы перешли к разработке MVP.
Часть 3. Figma API → Google Sheet
Более-менее разобравшись с тем, как вытянуть информацию из Figma по интересующему нас проекту, мы перешли к созданию скрипта для Google-таблицы.
Ранее эта таблица создавалась и актуализировалась в ручном режиме, что нас напрягало.
Первой целью стало автоматическое создание таблички для уже существующего проекта.
Внутри всех офисных сервисов Google (Doc, Sheet, Slides) есть свой встроенный JS-движок, позволяющий расширить функциональность этих сервисов. Язык разработки ребятами назван Google AppScript. По сути это надмножество JavaScript с несколькими дополнительными надстройками. К языку прилагается очень обширная и постоянно обновляемая документация. Примерно 50% переведено на русский.
Во время изучения документации мы поняли,что нам очень повезло. Google как раз обновил свой движок до ES6, что позволило писать более простой и лаконичный код с применением многих более удобных конструкций и синтаксического сахара.
Интерфейс IDE, встроенной в Гугл-сервисы
Логика разрабатываемого скрипта была очень простой:
Для того, чтобы показать скрипту, из какого Figma-проекта нужно тянуть данные, мы создали вкладку Settings.
Настройки для скрипта синхронизации Figma → Google Sheet
После того, как настройки внесены, можно вызвать меню и начать создание или апдейт таблицы.
Пример выгрузки из Figma
Пример выгрузки из Figma
Предлагаю немного разобраться с тем, как мы решили расширить функциональность Гугл-таблицы.
Сперва нужно рассказать, что и как устроено в самой таблице. Каждая вкладка — это отдельная страница в Figma с дизайнами экранов. Мы решили разделять страницы по размерам экрана (мобилка, десктоп, планшет).
В колонке Screen каждая строка — это имеющийся на текущей странице Figma экран. Он сделан в виде ссылки для быстрого перехода к нему в Figma. Каждый экран имеет дату последнего обновления, свой статус и дополнительную информацию (new frame — если этот экран добавился с момента прошлой синхронизации или Empty Status — если он не получил никакого статуса).
Самое удобное, что эта таблица генерируется в полностью автоматическом режиме, что стало экономить кучу времени проектному менеджеру. Ранее данные в таблицу заносились вручную.
К этой таблице теперь можно применять различные фильтры, чтобы получить быстрый срез по тому, какие экраны обновились, какие были приняты заказчиком, а какие требуют внимания и корректировок.
С нашей точки зрения получился очень функциональный инструмент, но у нас остался еще один участок «ручного труда».
Часть 4. Плагин для Figma
Мы сумели наладить синхронизацию между проектом в Figma и Гугл-таблицей, в которой автоматически проставлялись обновленные статусы. Однако осталась еще одна важная задача. PM все еще руками выставлял обводку и цвет для каждого экрана в Figma. Этот процесс и трудоемкий, и является источником ошибок, а значит, должен быть упрощен/автоматизирован. Мы решили обратить внимание на функциональность плагинов для Figma.
Разработчики Figma позволяют интегрировать свои мини-приложения для расширения функциональности. Приложение получает доступ к JSON-представлению проекта и позволяет манипулировать им при помощи любезно предоставленного командой Figma API.
В процессе изучения документации стало понятно, что для разработки плагинов нужно владеть базовыми знаниями React + TypeScript. Такие навыки имелись, и было принято решение создать свой плагин.
Функциональность была заложена достаточно простая: дать возможность пользователю плагина выделить группу экранов и простым способом назначить им статус.
Мы приняли решение «захардкодить» типы наших статусов и соответствующие им цвета в наш плагин, т.к. не планировали его opensource-ить. В конечном итоге за пару вечеров удалось разработать очень простое расширение.
В первом выпадающем списке можно выбрать статус текущего экрана.
Во втором выпадающем списке можно выбрать ширину обводки. Более широкая нужна для того, чтобы видеть статус экрана при беглом осмотре всего проекта (когда в рабочей области Figma видно 10-20 миниатюр экранов).
Такое минималистичное приложение позволило существенно сократить трудоемкость создания обводок для каждого экрана и сократить количество ошибок.
Итоги
В ходе реализации проекта удалось познакомиться с возможностями, которые Figma и Google-сервисы предоставляют разработчикам. Благодаря этим сервисам мы минимизировали трудозатраты PM и дизайнеров на рутину и, надеюсь, сделали их немного счастливее 🙂
Эти расширения уже используются на ряде проектов и получают позитивный фидбек со стороны пользователей. Ну и баг-репорты, разумеется ;).
Как мы используем Figma API для доставки дизайна в Production
Я продуктовый дизайнер в Яндекс.Картах и хочу рассказать, как мы связали макеты в Figma с разработкой и кодом. Сейчас изменения графики, стилей текста и цветов автоматически прорастают в код мобильных приложений. Но сначала расскажу почему мы выбрали для этого Figma.
Почему Фигма?
Раньше у нас была цепочка из нескольких инструментов и довольно непростой процесс. Мы использовали Sketch — для макетов, Zeplin — для передачи макетов разработке и PaintCode — для передачи графических ресурсов в разных форматах (xml, objective-c/swift). Сами макеты и ресурсы хранились в облаке (Яндекс.Диске), вся команда имела к ним прямой доступ.
Мы давно смотрели в сторону альтернатив и в начале мая решили изменить свой стек в сторону фигмы. В отличии от скетча, фигма позволяет более гибко работать с библиотекой компонентов, улучшает взаимодействие в команде, решает проблемы хранения и передачи макетов разработке, так как хранит всё в облаке. Переход в фигму в нашем случае исключал из цепочки Zeplin и Диск, а это уже минус два инструмента.
У нас, как у и всех, была дизайн-библиотека в скетче, которая хранила все наши переиспользуемые ресурсы. Для старта работы нам сначала нужно было переформатировать нашу дизайн-библиотеку с учетом возможностей API фигмы.
Библиотека компонентов
Мы пересмотрели всю структуру библиотеки, думая сразу над тем, как будем отдавать ресурсы разработке. Получилось разделить все на три файла:
Интеграция библиотеки в код
Мы хотели получить систему, при которой все ресурсы забираются автоматически через API фигмы. То есть, если мы захотим изменить какой-либо цвет в интерфейсе, стиль текста или иконку, это можно будет сделать только в фигме и не использовать другие инструменты (PaintCode, ручной экспорт ресурсов).
Находясь в постоянном контакте с разработкой, мы согласовывали внутри каждый момент, чтобы всем было удобно. В итоге выработали схему отдельных страниц для иконок, цветов, стилей текста и компонентов, удобную для автоматического экспорта через API. Это дало жесткую связку дизайн-библиотеки и кодовой базы. Сейчас наша команда разработки запускает скрипт и получает все обновления напрямую за пару секунд.
Но, конечно, не обошлось без трудностей. Как вы знаете, разные платформы используют разные ресурсы: Android — drawable xml, iOS — pdf/png, Web — svg. Фигма не поддерживает экспорт в drawable xml, поэтому ребятам из андроида приходится на своей стороне дополнительно делать из svg xml. Помимо этого, у Карт есть ночная и дневная тема, а значит, и у ресурсов должны быть две версии. Мы делаем дневную и ночную версии для сложной графики, которая состоит из нескольких цветов. Если же иконка одноцветная, то она красится маской на стороне разработки, а в файле Dev Core она черная.
В итоге был автоматизирован очень кропотливый процесс, но это накладывает ряд ограничений — приходится придерживаться четких правил по неймингу. Мы используем только lowercase названия с нижним подчеркиванием. Например, для иконок формат правильного имени получился такой: [name]_[state]_[size]_[day/night].
С большим количеством ресурсов легко ошибиться, нам нужна была дополнительная проверка на стороне фигмы, чтобы процесс парсинга был всегда беспроблемным. К счастью, не так давно фигма начала поддерживать плагины, и, чтобы проверять валидность библиотеки на стороне дизайнеров, я написал свое расширение.
Плагин для проверки библиотеки
Написать плагин оказалось совсем несложно, у фигмы отличная документация, писать нужно на JS. Сразу скажу, что делать с файлом фигмы через код можно все что угодно, посмотрите на кучу плагинов, доступных прямо сейчас. Еще удобно, что любой код легко проверить в консоли.
Наш плагин для Figma умеет следующее:
Если вам интересно, то код моего плагина найти можно здесь.
Компоненты
Помимо прочего, в Dev Core мы храним компоненты дизайн-системы и их описание. Сейчас это кнопки, списки, лоадеры, шапки, различные попапы и тд. Все эти компоненты привязаны к нашим дизайн-библиотекам.
Это нужно для того, чтобы у дизайна и разработки были единые компоненты и единый свод правил. Еще наша команда разработки собрала приложение для просмотра всех ресурсов и компонентов на мобильном устройстве. Все что забирается из фигмы собрано там и это легко посмотреть в одном месте.
Figmа позволяет нам работать в тесном контакте с разработкой и делать продукт быстрее и лучше. Как итог мы смогли автоматизировать очень рутинную часть своей работы и существенно упростить процесс. В наших планах интегрировать фигму еще и в процесс создания карт.
Introduction
Welcome to the Plugin API!
Plugins are programs or applications created by the community that extend the functionality of Figma and FigJam. Plugins run in Figma or FigJam files and perform one or more user actions. They allow users to customize their experience or create more efficient workflows.
Like Figma and FigJam, plugins are powered by web technologies. You’ll need an understanding of these technologies to develop plugins. You’ll write plugins in JavaScript and build any UI using HTML. Explore required knowledge →
Plugins interact with the Figma application via a dedicated Plugin API. They can also leverage external Web APIs. You can build plugins that run immediately, or build plugins that require user’s to input information via a user interface (UI). Explore how plugins are run →
The API reference and this accompanying documentation has the information you need to build plugins for Figma and FigJam. To ask questions, give feedback, or connect with other plugin developers: Join the Figma Plugins Slack →
Our setup guide takes you through the process of setting up your environment and running a sample plugin. Get started with the plugin API →
The Plugin API supports both read and write functions, allowing developers to view, create, and modify the contents of Figma design and FigJam files.
In both Figma and FigJam, you can access most of the plugin API through the figma global object.
Plugins expose, first and foremost, the contents of a file. That’s anything that exists in the layers panel and any properties associated with that layer in the properties panel. Plugins can view and modify aspects of these layers or nodes, like the color, position, hierarchy, text, etc.
The plugin API doesn’t allow you to access anything in that file that’s outside the canvas. Plugins can’t access:
Document structure
Every file in Figma consists of a tree of nodes and at the root of every Figma or FigJam file is a Document node. The document node is how you access and explore the contents of a file.
In a Figma design file, every DocumentNode will have PageNode that represent each page in that Figma file. There can only be one document node per browser tab and each of it’s children must be PageNodes.
As FigJam files don’t support pages, there won’t be any PageNodes to explore. Instead, the children of the document node will be the layers and objects on that board.
The document node can then have any number of child nodes. Each subtree that stems from the document node represents a layer or object on the canvas. There are specific nodes or classes for different types of layers in Figma — like frames, components, vectors, and rectangles.
Nodes have a number of properties associated with them. Some of these are global properties, that exist on every node, whereas other properties will be specific to the type of node.
You can create plugins for a specific editor type, both editors, or build plugins that perform different actions in each editor. While some node types can only be created in a specific file or editor type, you will generally be able to read and modify most nodes, regardless of the editor type.
Browser based
The Plugins API doesn’t support desktop-specific APIs. While Figma has desktop applications, not everyone accesses Figma via the desktop. We want plugins to be as accessible and cross-platform as Figma itself. There are also security concerns which require a thorough and considerate approach.
Browsers already come with APIs such as reading files and saving files. Browser engineers have already put a lot of hard work into creating secure APIs, and we are content to follow their lead.
Core API
We built the Plugin API around a set of fixed controlled endpoints. There’s a lot of extra functionality we could provide via the Plugin API, including helper functions that perform or automate a sequence of functions or events.
We made a conscious decision to keep the core Plugin API as contained as possible. This reduces the risk of us introducing code-breaking changes to the API and makes it easier for plugin developers to maintain plugins.
This means that we don’t include any helper functions that developers can write using existing functions available in the Plugin API.
Plugins run in Figma or FigJam files and perform one or more user actions. These user actions are usually short-lived and must be initiated by the user.
Plugin UI
You can choose whether your plugin runs immediately, or if users can enter in
Being able to pull from a library of components of Figma buttons, color picker, etc, significantly speeds up plugin development and helps you create a UI that’s mirrors Figma’s own UI.
We don’t provide these components as part of the core Figma Plugin API. Figmate and Figma plugin developer, Tom Lowry, has put together a library of React components which you can use to build the UI of your plugin. Open the Github repo →
Plugin parameters
Developers can create plugins with parameters that allow plugins to accept input from users via the quick actions menu.
Adding parameters means you don’t need to build a custom UI. It also provides a streamlined experience for users of the plugin, who can run a plugin directly from the quick actions menu.
Relaunch plugins
When developing a plugin, you have the option to include a relaunch button. Since it isn’t possible to set keyboard shortcuts for plugins, this makes it easier to run a plugin multiple times and allows collaborators to relaunch the plugin from the same file.
In Figma design files, the relaunch button will appear in the Properties panel. In FigJam files, the relaunch button appears in the properties menu for a node. Relaunch buttons are not available on page or document nodes in FigJam.
Multiple relaunch buttons can be added to the same node. If multiple relaunch buttons from the same plugin are added to the same node, they are grouped together into one button with submenus. The order of buttons is determined by the order of the elements in the manifest’s relaunchButtons array. Learn more about relaunch in the plugin manifest →
Support
Figma does not provide support for third-party applications. As the plugin’s developer it’s your responsibility to assist your plugin’s users with technical issues. You need to add a Support contact when you submit your plugin for approval. This can be an email address users can contact, or a link to a website or help center. Manage plugins as a developer →
Versioning
Once Figma approves your plugin, you don’t need to submit your plugin for further review. This means you can publish any updates immediately. You’ll be able to added a detailed description of any changes or updates in the plugin’s Version history. When you publish an update, Figma will update the plugin for every user. Users who have already installed your plugin will only have access to the latest version of your plugin. It’s not possible for users to revert to a previous version of the plugin. If you need to roll back any changes, you can republish an earlier version of the plugin.
Analytics
Figma doesn’t currently provide any analytics or reporting around plugin usage or error/crash reporting. We recommend using your own analytics or crash reporting service to monitor your plugins performance. Figma will send Plugin developers a notification each week about any Community activity. This includes the total number of likes and installs for that week.