Figma Plugin API: англійською мовою для розробки інструментів дизайну
Вивчіть англійську лексику для створення додатків Figma — PluginAPI, типи вузлів, гілки інтерфейсу користувача, postMessage, манифест і спільні дані додатків — для розробників ESL.
Додатки Figma — це програми JavaScript, які виконуються у стільничній програмі Figma і у програмах переглядача, і які можуть читати і змінювати поточний документ проекту. Розробка додатків вимагає розуміння специфічної двопоточної архітектури і великої поверхні API для маніпулювання вузлами дизайну. Якщо ви розробник ESL, який створює внутрішні інструменти Figma або публікує додатки для спільноти, словник у цьому повідомленні допоможе вам прочитати документацію з API додатків Figma і обговорити автоматизацію проектування англійською мовою.
Архітектура: Дві стрічки
** головна нитка ** — це середовище JavaScript у пісочниці, де виконується код вашого додатка і де виконуються всі виклики API Figma; воно має безпосередній доступ до документа, але не має доступу до API переглядача, таких як fetch або localStorage.
- “Всі маніпуляції з вузлами повинні виконуватися у головній нитки, оскільки API додатка Figma доступно лише у цій нитки, а не у iframe інтерфейсу користувача.” *
** нитка інтерфейсу користувача ** — окремий iframe у пісочниці, який ваш додаток може відкрити для показу нетипового інтерфейсу HTML; він має доступ до API переглядача, але не може безпосередньо викликати API додатка Figma.
“Ми побудували форму налаштувань в потоці інтерфейсу користувача за допомогою компонента React, і використовували postMessage для відсилання вибору користувача назад до головного потоку для обробки.”
** postMessage ** — стандартний API переглядача, який використовується для передачі повідомлень між головною ниткою і ниткою інтерфейсу користувача у обох напрямках; це єдиний канал зв’ язку між двома пісочницями.
- “Коли користувач натискає кнопку Зберегти у потоці інтерфейсу користувача, ми викликаємо postMessage, щоб надіслати об’ єкт налаштування до головної нитки, яка потім застосує зміни до вибраних вузлів.” *
Маніфест додатка
** manifest ** — файл manifest.json у кореневому каталогу кожного додатка Figma, у якому оголошено назву додатка, ідентифікатор, скрипти пунктів входу, права доступу і пункти меню; Figma читає цей файл, щоб встановити і запустити додаток.
- “Ми додали дозвіл мережі до манифесту після того, як Figma відкинула додаток, оскільки він намагався здійснювати виклики отримання без попереднього оголошення дозволу.” *
** plugin ID ** — унікальний рядок, який буде призначено для вашого додатка під час його створення у Figma; він має збігатися з полем id у манифесті і використовуватиметься для ідентифікації вашого додатка у спільноті Figma і у викликах API.
- “Після перенесення додатка до організації Figma компанії, ми оновили ідентифікатор додатка у манифесті, щоб він відповідав запису додатка нового власника.” *
PluginAPI і доступ до вузлів
** PluginAPI ** — глобальний об’ єкт figma, доступний у головній нитки, який показує всі можливості додатка, зокрема поточний файл, поточну сторінку, вибір, керування інтерфейсом користувача і методи створення вузлів.
“Ми отримуємо доступ до всього через об’єкт PluginAPI: figma.currentPage для знаходження місця вставки вузлів, і figma.ui для відкриття і взаємодії з потоком інтерфейсу користувача.”
** figma. currentPage ** — властивість PluginAPI, яка повертає сторінку, яку користувач переглядає у даний момент, надаючи вам змогу пересуватися по дереву вузлів або додавати до нього нові вузли.
“Ми ітеруємо над figma.currentPage.children, щоб знайти всі рамки верхнього рівня і створити звіт з їхніми назвами і розмірами.”
** createRectangle ** — метод PluginAPI, який створює новий вузол прямокутника і вставляє його до документа; після виклику цього методу вам слід додати вузол до батьківського вузла, щоб зробити його видимим.
- “Ми викликаємо figma. createRectangle (), встановлюємо його ширину, висоту і заповнення, а потім додаємо його до вибраного блоку, щоб розмістити форму тла за вмістом.” *
Типи вузлів і властивості
** типи вузлів ** — категорії об’ єктів проектування у документі Figma, зокрема FRAME, TEXT, RECTANGLE, ELLIPSE, COMPONENT, INSTANCE і GROUP; кожен тип має свій набір властивостей, які можна читати і записувати.
“Ми фільтруємо figma.currentPage.findAll() тільки для вузлів INSTANCE, тому додаток обробляє тільки екземпляри компонентів і ігнорує необроблені форми.”
** setSharedPluginData ** — метод PluginAPI, який зберігає довільні дані ключ- значення на будь- якому вузлі у просторі назв, обмеженому обсягом вашого додатка, зберігаючи ці дані навіть після закриття додатка.
“Ми викликаємо setSharedPluginData на кожному анотованому вузлі, щоб зберегти пов’ язаний ідентифікатор квитка Jira, щоб додаток міг його пошукати під час наступного запуску без повторного запитання користувача.”
** getSharedPluginData ** — допоміжний метод, який читає дані, які раніше було збережено за допомогою setSharedPluginData, надаючи вашим додаткам змогу підтримувати постійний стан, прив’ язаний до певних вузлів проектування.
- “Під час запуску ми викликаємо getSharedPluginData на всіх вузлах, щоб відновити карту існуючих анотацій, щоб додаток не створював дублікатів записів.” *
Закриття додатка
** figma. closePlugin ** — метод PluginAPI, який виключає додаток і, за бажанням, показує сповіщення користувачеві; його виклик необхідний для належного завершення виконання додатка.
“Після застосування всіх змін стилю, ми викликаємо figma.closePlugin(‘Стилі успішно оновлено’), щоб Figma показав користувачеві повідомлення про підтвердження і очистив ресурси додатка.”
Practice
Написати мінімальний додаток для Figma, який знаходить всі вузли TEXT на поточній сторінці і записує їх вміст у консоль. Додати панель інтерфейсу користувача з кнопкою, яка надсилає ** postMessage ** до головної гілки, щоб запустити сканування. Англійською мовою поясніть колегі, чому ви не можете викликати figma.currentPage зсередини потоку UI і яке архітектурне рішення змушує вас до такого розділення.
Навигація Nuance: точність у комунікації з додатками Figma
Як розробник ESL, який занурюється в API додатка Figma, ви швидко усвідомите, що технічний жаргон не просто про те, * що * щось робить; на нього глибоко впливає * як * ви його описуєте. Мова, яку використовують у переглядах коду, розмовах у Slack і описах PR, є критичною для співпраці і чіткого передачі ваших намірів. Часто прямі переклади з вашої рідної мови можуть призвести до непорозумінь або, ще гірше, сприймається недбалості щодо найкращих практик. Розглянемо деякі конкретні області, в яких розробники ESL можуть зіткнутися з викликами.
Одна з найпоширеніших проблем виникає при обговоренні асинхронних операцій. Концепція « потоку інтерфейсу користувача » є фундаментальною у розробці додатків Figma — будь- які оновлення інтерфейсу користувача * повинні * відбуватись у головному потоці, щоб уникнути аварій і забезпечити плавний досвід користувача. Однак, просто заявивши «Я використовую postMessage », не можна повністю передати відповідальність, що з цим пов’язана. Краще було б написати: « Щоб забезпечити швидкість відповіді і запобігти блокуванню потоку інтерфейсу користувача, я структурував цю операцію отримання даних у рамках обіцянки, яка розв’ язується у головному потоці перед запуском оновлення шару Figma. » Уникайте нечітких термінів, на зразок « асинхронне оброблення ». Замість цього зосередьтеся на тому, як ви керуєте асинхронним потоком. Аналогічно, при описі змін типів вузлів, точність є ключем. Сказати « Я змінив прямокутник » не достатньо детально; замість цього використовуйте такі фрази: « Я оновив тип вузла rectangle, щоб включити нову властивість « колір заповнення ». »
Іншою областю, що потребує ретельної уваги, є зворотній зв’язок в рамках переглядів коду. Отримавши коментарі на кшталт «Це виглядає незграбно» або «Чи можете ви переробити це?», Ви можете бути неймовірно розчаровані, не розуміючи основного міркування. Ключ тут - відповідати конкретною, дієвою мовою. Замість того, щоб просто приймати критику, задайте питання, які прояснять ситуацію: « Чи можете ви розібратися у тих аспектах, які вам здаються « незграбними », і запропонувати більш структурований підхід? » Або, обговорюючи можливі рішення, скористайтеся такими фразами, як « Я перероблю цей розділ, щоб дотримуватися найкращих практик PluginAPI щодо обробки даних », щоб продемонструвати розуміння встановлених правил. Пам’ ятайте, що інженери часто спілкуються через намір - вони не обов’ язково шукають вас, щоб просто щось виправити, але щоб зрозуміти * чому * це потребує виправлення і як ви збираєтеся це зробити.
Нарешті, створення ефективних описів PR є ключовим для підтримки. Не просто перераховуйте зміни; надайте контекст: «Ця публікація реалізує нову функцію, що дозволяє користувачам динамічно змінювати розмір форм у Figma за допомогою можливостей маніпулювання вузлами API додатка. Код включає в себе всеосяжну обробку помилок і дотримується встановлених правил назв для поліпшення читабельності. ” Це про демонстрацію * розуміння *, а не просто виконання.
Ось приклад, який показує, як ви можете скористатися командою figma.plugin.canvas.insertNode:
// Example: Inserting a circle node onto the canvas using PluginAPI
const newNode = {
type: 'circle',
x: 100,
y: 100,
radius: 50,
};
figma.plugin.canvas.insertNode(newNode);Цей простий приклад підкреслює важливість точного опису операції — вставлення вузла кола у певних координатах — замість простого повідомлення « Я додав коло ». Прозорість опису є важливою для інших розробників, щоб вони могли зрозуміти і, можливо, розвинути вашу роботу.