Figma завжди заохочувала співпрацю між розробниками та дизайнерами. Він прагне до нескінченної скарбниці плагінів, створених спільнотою. Потрібні 3D елементи? Для цього є плагін. Потрібні абстрактні SVG? Для цього є плагін, Теж.
Тим не менш, частина дизайну Figma завжди була відносно статичною — завжди працювала з нерухомими прямокутниками, з’єднаними один з одним через попередньо визначені взаємодії користувача. Але що, якби я сказав вам, що ваші проекти можуть раптово ожити — що вони можуть бути анімованими, інтерактивними та навіть підтримувати стан? Тоді що відрізняє концепцію від реалізації?
Figma оголошено в червні що він приносить до столу віджети на основі JavaScript. Тепер дизайнери можуть переглядати та впроваджувати логічно керовані компоненти прямо у Figma!
Привітайся API віджетів! Ви хочете знати, що це таке і як ним користуватися? Це саме те, що ми збираємося робити разом у цій публікації.
Віджети Figma відкривають масу можливостей
Уявіть, що ви цілодобово працюєте зі своїм партнером над розробкою великої ресторанної програми. Ви обоє вже співпрацюєте на одній дошці Figma; ви обоє ділитеся одним і тим самим документом із змінами, які відбуваються на льоту.
Напевно, ви вже знаєте, що співпраця включає не лише процес проектування:
- управління проектами,
- проведення опитувань для збору голосів,
- імпорт і візуалізація макетних даних,
- і, можливо, навіть пограти в багатокористувацьку гру, щоб відпочити після багатьох годин роботи.
Ми просто вимагаємо, щоб одна особа керувала всім і надсилала посилання іншим учасникам групи. Але це не дуже ефективно, чи не так?
Що ж, тут у гру вступають віджети. Імовірно, ми можемо робити все це — так, усе — не покидаючи Figma.
Ось лише кілька способів використання віджетів у Figma:
Список триває знову і знову. Як ви бачите, вже існує безліч віджетів, які ви можете вільно використовувати у своїх документах. Фактично, ви можете додати віджети прямо на свою дошку з меню віджетів (Shift+I).
Але ми тут не для того, щоб навчитися користуватися віджетами, тому що це легко. Давайте зробимо те, що вміємо найкраще: ми створимо власний віджет Figma! Цей буде натхненний Веб-сайт із котируванням дизайну Кріса Койєра. Ми візьмемо API, передамо його у віджет, а потім відобразимо випадкові котирування дизайну безпосередньо у Figma.
Ось що нам потрібно
Я не люблю бути носієм поганих новин, але щоб розробляти віджети, ви повинні бути на Windows або Mac. Користувачі Linux, вибачте, але вам не пощастило. (Ви все ще можете використовувати віртуальну машину якщо ви хочете слідкувати.)
Ми збираємось завантажити Figma Desktop додаток. Найпростіший спосіб почати – створити шаблон віджета прямо з програми.
Давайте створимо нову дошку, відкривши меню віджетів (Shift+ I), перемикаючись на розробка і створення нового елемента.
Після цього Figma запропонує вам назвати новий віджет і вирішити, чи він більше пристосований до дизайнерські дошки або дошки FigJam теж. Першого варіанту достатньо для цілей цієї статті.
І налаштування на цьому не закінчуються; Figma також надасть вам можливість почати з попередньо створеного віджета лічильника або альтернативи з підтримкою iFrame, яка також надасть вам доступ до API Canvas і Fetch (а також до всіх інших API браузера). Ми виберемо простий варіант «Пустий», але згодом ми самостійно змінимо його, щоб використовувати Fetch API.
Потім вам буде запропоновано зберегти ваш новий проект віджета в спеціальний каталог у вашій системі. Коли це буде зроблено, запустіть свій термінал і спрямуйте його до цієї папки. Поки що не запускайте жодних команд — ми зробимо це пізніше й навмисно отримаємо повідомлення про помилку з метою дізнатися більше про API віджетів.
Розробка віджета
Ми беремо дизайн прямо з Веб-сайт із котируванням дизайну Кріса Койєра. Отже, давайте перейдемо туди і заглибимося в DevTools.
Тут я використовую два клавіші швидкого доступу Ctrl+Shift+C (Або Cmd+Shift+C), щоб увімкнути інструмент «Вибрати елемент», і Shift+Click щоб змінити формат кольору на HEX-код. Ми робимо це, щоб дізнатися про кольори, шрифти, щільність і розмір шрифту, які використовуються на веб-сайті Кріса. Уся ця інформація має вирішальне значення для створення схожого на Figma віджета, який буде нашим наступним кроком! Ти можеш захопити розроблений компонент і використовуйте його у своєму власному полотні.
Я не буду вдаватися в подробиці, оскільки основна тема цієї статті — створення віджетів шляхом написання коду. Але я не можу наголосити, наскільки важливо добре піклуватися про себе стиль віджетів… CSS-Tricks вже є безліч навчальні посібники Figma, орієнтовані на дизайн; ви не пошкодуєте, додавши їх до свого списку для читання.
Створення макета для нашого віджета
З дизайном покінчено, настав час забрати наші програмні пальці та почати створювати механізми нашого віджета.
Дуже цікаво, як Figma перетворює свої будівельні блоки дизайну на React-подібні компоненти. Елементи рамки з функцією автоматичного компонування, наприклад, представлені як <AutoLayout /> компонент у коді. Крім цього, ми будемо використовувати ще два компоненти: <Text /> та <SVG />.
Подивіться на мою дошку Figma… Я саме прошу вас зосередитися на дереві об’єктів. Це те, що нам потрібно, щоб мати можливість перекласти дизайн нашого віджета на код JSX.
Як бачите, для нашого віджета котирувань дизайну потрібно імпортувати три компоненти. Це пристойна кількість компонентів, враховуючи, що повний API містить лише вісім шарових вузлів. Але, як ви незабаром побачите, цих модулів більш ніж достатньо для створення будь-яких макетів.
// code.tsx
const { widget } = figma;
const { AutoLayout, Text, SVG } = widget;І з цим у нас є все, що нам потрібно, щоб побудувати скелет нашого віджета, як у React:
function QuotesWidget() {
const quote = `...`;
const author = `...`;
return (
<AutoLayout>
<SVG />
<AutoLayout>
<Text>{quote}</Text>
<Text>— {author}</Text>
</AutoLayout>
<SVG />
</AutoLayout>
);
}
widget.register(QuotesWidget);Цей код, м’яко кажучи, дуже заплутаний. Наразі ми не можемо відрізнити шари дизайну. На щастя, ми можемо легко вирішити цю проблему за допомогою name власність
<AutoLayout name={"Quote"}>
<SVG name={"LeftQuotationMark"} />
<AutoLayout name={"QuoteContent"}>
<Text name={"QuoteText"}>{quote}</Text>
<Text name={"QuoteAuthor"}>— {author}</Text>
</AutoLayout>
<SVG name={"RightQuotationMark"} />
</AutoLayout>;І, звісно, ми все ще не можемо бачити наші лапки SVG, тож давайте попрацюємо над цим. The <SVG/> компонент приймає a srcвластивість, яка бере вихідний код для елемента SVG. Про це не так багато можна сказати, тому давайте будемо простими і повернемося до коду:
const leftQuotationSvgSrc = `<svg width="117" height="103" viewBox="0 0 117 103" fill="none" xmlns="<http://www.w3.org/2000/svg>">
// shortened for brevity
</svg>`;
const rightQuotationSvgSrc = `<svg width="118" height="103" viewBox="0 0 118 103" fill="none" xmlns="<http://www.w3.org/2000/svg>">
// shortened for brevity
</svg>`;
function QuotesWidget() {
return (
<SVG name={"LeftQuotationMark"} src={leftQuotationSvgSrc} />
<SVG name={"RightQuotationMark"} src={rightQuotationSvgSrc} />
);
}Я думаю, ми всі можемо погодитися, що тепер все набагато зрозуміліше! Коли ми називаємо речі, їх призначення раптом стає набагато очевиднішим для читачів нашого коду.
Попередній перегляд нашого віджета в реальному часі
Figma пропонує чудовий досвід для розробників під час створення віджетів, включаючи (але не обмежуючись ними) гаряча перезарядка. За допомогою цієї функції ми можемо кодувати та переглядати зміни в нашому віджеті в реальному часі.
Почніть, відкривши меню віджетів (Shift+I), переключившись на вкладку розробки та клацнувши або перетягнувши новий віджет на дошку. Не можете знайти свій віджет? Не хвилюйтеся, просто натисніть на меню з трьома крапками та імпортуйте свій віджет manifest.json файл. Так, це все, що потрібно, щоб повернути його до існування!
Зачекайте, ви отримали повідомлення про помилку внизу екрана?
Якщо так, давайте розберемося. Натисніть на "Відкрити консоль» і прочитайте, що там сказано. Якщо Відкрити консоль кнопка зникла, є альтернативний спосіб відкрити консоль налагодження. Натисніть на логотип Figma, перейдіть до категорії віджетів і відкрийте меню розробки.
Ймовірно, ця помилка пов’язана з тим, що ми ще не скомпілювали наш TypeScript у JavaScript. Ми можемо зробити це в командному рядку, запустивши npm install та npm run watch. (або yarn та yarn watch ). Цього разу без помилок!
Ще одна перешкода, з якою ви можете зіткнутися, полягає в тому, що віджет не може повторно відобразити кожного разу, коли змінюється код. Ми можемо легко примусово оновити наш віджет за допомогою такої команди контекстного меню: віджети → Повторне відтворення віджета.
Стилізація віджета
У поточному стані виглядає наших віджетів ще досить далекі від нашої кінцевої мети.
Отже, як ми стилізуємо компоненти Figma з коду? Можливо, з CSS, як ми зробили б у проекті React? Негативний. З віджетами Figma, всі стиль відбувається через набір добре задокументований реквізит. На щастя для нас, ці предмети майже названі ідентично до своїх аналогів у Figma.
Ми почнемо з налаштування наших двох <AutoLayout /> компоненти. Як ви можете бачити в інфографіці вище, назви реквізитів досить описують їх призначення. Це полегшує нам перехід безпосередньо до коду та внесення деяких змін. Я не буду знову показувати весь код, тому, будь ласка, покладайтеся на назви компонентів, щоб скерувати вас до місця фрагментів.
<AutoLayout
name={"Quote"}
direction={"horizontal"}
verticalAlignItems={"start"}
horizontalAlignItems={"center"}
spacing={54}
padding={{
horizontal: 61,
vertical: 47,
}}
>
<AutoLayout
name={"QuoteContent"}
direction={"vertical"}
verticalAlignItems={"end"}
horizontalAlignItems={"start"}
spacing={10}
padding={{
horizontal: 0,
vertical: 0,
}}
></AutoLayout>
</AutoLayout>;Ми просто досягли значного прогресу! Давайте збережемо і повернемося до Figma, щоб побачити, як виглядає наш віджет. Пам’ятаєте, як Figma автоматично перезавантажує віджети після нових змін?
Але це ще не зовсім там. Ми також повинні додати фоновий колір до кореневого компонента:
<AutoLayout name={"Quote"} fill={"#ffffff"}>Знову ж таки, подивіться на свою дошку Figma і зверніть увагу на те, як зміни можуть майже одразу відображатися назад у віджеті.
Давайте перейдемо до цього посібника та стилізуємо його <Text> компонентами.
Подивившись на Документація API віджетів, знову зрозуміло, що назви властивостей майже ідентичні їхнім відповідникам у додатку Figma, як можна побачити на інфографіці вище. Ми також використовуватимемо значення з останнього розділу, де ми перевіряли веб-сайт Кріса.
<Text name={'QuoteText'}
fontFamily={'Lora'}
fontSize={36}
width={700}
fill={'#545454'}
fontWeight={'normal'}
>{quote}</Text>
<Text name={'QuoteAuthor'}
fontFamily={'Raleway'}
fontSize={26}
width={700}
fill={'#16B6DF'}
fontWeight={'bold'}
textCase={'upper'}
>— {author}</Text>Додавання стану до віджету
Наш віджет наразі відображає ту саму цитату, але ми хочемо взяти з усього пулу цитат випадковим чином. Треба додати були до нашого віджета, який, як відомо всім розробникам React, є змінною, зміна якої запускає повторний рендеринг нашого компонента.
За допомогою Figma стан створюється за допомогою useSyncedState гачок; це досить багато Реагувати useState, але для цього програмістам потрібно вказати унікальний ключ. Ця вимога випливає з того факту, що Figma має синхронізувати стан нашого віджета всі клієнти, які можуть переглядати ту саму дошку дизайну, але на різних комп’ютерах.
const { useSyncedState } = widget;
function QuotesWidget() {
const [quote, setQuote] = useSyncedState("quote-text", "");
const [author, setAuthor] = useSyncedState("quote-author", "");
}Це всі зміни, які нам зараз потрібні. У наступному розділі ми з’ясуємо, як отримати дані з Інтернету. Спойлер: це не так просто, як здається.
Отримання даних з мережі
Згадайте, коли Figma дала нам вибір почати з віджета з підтримкою iFrame. Хоча ми не вибрали цей варіант, ми все одно маємо реалізувати деякі його функції. Дозвольте мені пояснити, чому ми не можемо просто подзвонити fetch() у коді нашого віджета.
Коли ви використовуєте віджет, ви запускаєте код JavaScript на своєму комп’ютері, написаний кимось іншим. Хоча всі віджети ретельно перевіряються співробітниками Figma, це все одно величезна діра в безпеці, оскільки всі ми знаємо, наскільки пошкодження може бути завдано навіть одним рядком JavaScript.
Як наслідок, Figma не може просто eval() будь-який код віджета, написаний анонімними програмістами. Коротше кажучи, команда вирішила, що найкращим рішенням є запуск стороннього коду в ретельно захищеному середовищі пісочниці. І, як ви могли здогадатися, API браузера недоступні в такому середовищі.
Але не хвилюйтесь, Figma вирішила цю другу проблему <iframe>с. Будь-який HTML-код, який ми записуємо у файл, бажано називати ui.html, матиме доступ до всіх API браузера. Можливо, вам цікаво, як ми можемо запустити цей код із віджета, але ми розглянемо це пізніше. А зараз повернемося до коду:
// manifest.json
{
"ui": "ui.html"
}<!-- ui.html -->
<script>
window.onmessage = async (event) => {
if (event.data.pluginMessage.type === 'networkRequest') {
// TODO: fetch data from the server
window.parent.postMessage({
pluginMessage: {
// TODO: return fetched data
}
}, '*')
}
}
</script>Це загальний шаблон для віджетів до-iframe спілкування. Давайте використаємо його для отримання даних із сервера:
<!-- ui.html -->
<script>
window.onmessage = async (event) => {
if (event.data.pluginMessage.type === 'networkRequest') {
// Get random number from 0 to 100
const randomPage = Math.round(Math.random() * 100)
// Get a random quote from the Design Quotes API
const res = await fetch(`https://quotesondesign.com/wp-json/wp/v2/posts/?orderby=rand&per_page=1&page=${randomPage}&_fields=title,yoast_head_json`)
const data = await res.json()
// Extract author name and quote content from response
const authorName = data[0].title.rendered
const quoteContent = data[0].yoast_head_json.og_description
window.parent.postMessage({
pluginMessage: {
authorName,
quoteContent
}
}, '*')
}
}
</script>Ми не використовуємо обробку помилок, щоб зробити це простим і актуальним. Давайте повернемося до коду віджетів і подивимось, як ми отримуємо доступ до функцій, визначених у <iframe>:
function fetchData() {
return new Promise<void>(resolve => {
figma.showUI(__html__, {visible: false})
figma.ui.postMessage({type: 'networkRequest'})
figma.ui.onmessage = async ({authorName, quoteContent}) => {
setAuthor(authorName)
setQuote(quoteContent)
resolve()
}
})
}Як ви бачите, ми спочатку повідомляємо Figma відкрити доступ до нашого прихованого <iframe> і ініціювати подію з назвою "networkRequest". Ми ведемо цю подію в ui.html файл, перевіривши event.data.pluginMessage.type === 'networkRequest', а потім опублікувати дані назад у віджет.
Але поки нічого не відбувається… Ми ще не додзвонилися fetchData() функція. Якщо ми викликаємо його безпосередньо у функції компонента, у консолі виникає така помилка:
Cannot use showUI during widget rendering.Figma каже нам не телефонувати showUI безпосередньо в тілі функції… Отже, де ми маємо це розмістити? Відповіддю на це є один новий хук і одна нова функція: useEffect та waitForTask. Можливо, ви вже знайомі з useEffect якщо ви розробник React, але ми будемо використовувати його тут для отримання даних із сервера під час монтування компонента віджета.
const { useEffect, waitForTask } = widget;
function QuotesWidget() {
useEffect(() => {
waitForTask(fetchData());
});
}Але це призведе до ще однієї «помилки», через яку наш віджет назавжди повторно відтворюватиме нову цитату. Це відбувається тому, що useEffect, за визначенням, запускається знову щоразу, коли змінюється стан віджета, ні коли ми викликаємо fetchData. І поки є техніка тільки дзвонити useEffect колись у React, він не працює в реалізації Figma. З документів Figma:
Через те, як працюють віджети,
useEffectмає обробляти кілька викликів з тим самим станом.
На щастя, є простий обхідний шлях, яким ми можемо скористатися та зателефонувати useEffect лише один раз, коли компонент вперше монтується, і це шляхом перевірки, чи значення стану все ще порожні:
function QuotesWidget() {
useEffect(() => {
if (!author.length & !quote.length) {
waitForTask(fetchData());
}
});
}Ви можете зіткнутися зі страшним "доступ до пам'яті поза межами" помилка. Його досить часто можна побачити в розробці плагінів і віджетів. Просто перезапустіть Figma, і її більше не буде.
Можливо, ви помітили, що іноді текст цитати містить дивні символи.
Це Символи Unicode і ми повинні правильно відформатувати їх у коді:
<!-- ui.html -->
<script>
window.onmessage = async (event) => {
// ...
const quoteContent = decodeEntities(data[0].yoast_head_json.og_description);
};
// <https://stackoverflow.com/a/9609450>
var decodeEntities = (function () {
// this prevents any overhead from creating the object each time
var element = document.createElement("div");
function decodeHTMLEntities(str) {
if (str && typeof str === "string") {
// strip script/html tags
str = str.replace(/<script[^>]*>([Ss]*?)</script>/gim, "");
str = str.replace(/</?w(?:[^"'>]|"[^"]*"|'[^']*')*>/gim, "");
element.innerHTML = str;
str = element.textContent;
element.textContent = "";
}
return str;
}
return decodeHTMLEntities;
})();
</script>і Вуаля, наш віджет отримував абсолютно нову котирування дизайну кожного разу, коли його додавали до дошки дизайну.
Додавання меню властивостей до нашого віджета
Хоча наш віджет отримує свіжу цитату після створення екземпляра, було б набагато практичніше, якби ми могли повторити цей процес, але не видаляючи його. Цей розділ буде коротким, оскільки розв’язок є досить примітним. с меню властивостей, ми можемо додати інтерактивність до нашого віджета одним викликом до usePropertyMenu гачок.
const { usePropertyMenu } = widget;
function QuotesWidget() {
usePropertyMenu(
[
{
itemType: "action",
propertyName: "generate",
tooltip: "Generate",
icon: `<svg width="22" height="15" viewBox="0 0 22 15" fill="none" xmlns="<http://www.w3.org/2000/svg>">
<!-- Shortened for brevity -->
</svg>`,
},
],
() => fetchData()
);
}За допомогою одного простого хука ми можемо створити кнопку, яка з’являється біля нашого віджета, коли його вибрано. Це була остання частина, яку нам потрібно було додати, щоб завершити цей проект.
Публікація нашого віджета для громадськості
Немає особливої користі в створенні віджета, якщо, ну, ніхто використовує це. І поки Figma надає організаціям можливість запуску приватний віджети для внутрішнього використання набагато частіше випускають ці маленькі програми для світу.
Figma має делікатний процес перевірки віджетів, який може тривати від 5 до 10 робочих днів. І хоча віджет котирувань дизайну, який ми створили разом, є вже в бібліотеці віджетів, я ще продемонструю, як воно туди потрапило. Будь ласка, не намагайтеся знову опублікувати цей віджет, оскільки це призведе лише до видалення. Але якщо ви внесли в нього деякі значні зміни, поділіться своїм власним віджетом із спільнотою!
Почніть, натиснувши меню віджетів (Shift+I) і перехід на розробка вкладку, щоб переглянути наш віджет. Натисніть на меню з трьома крапками та натисніть Публікувати.
Figma запропонує вам ввести деякі деталі про ваш віджет, наприклад назву, опис і деякі теги. Нам також знадобиться зображення значка 128×128 і зображення банера 1920×960.
Після імпорту всіх цих ресурсів нам все одно потрібен знімок екрана нашого віджета. Закрийте режим публікації (не хвилюйтеся, ви не втратите свої дані) і клацніть правою кнопкою миші на віджеті, щоб відкрити цікаве контекстне меню. Знайди Копіювати/Вставити яккатегорію та виберіть Копіювати як PNG.
Зробивши це, давайте повернемося до режиму публікації та вставимо знімок екрана віджета:
Прокрутіть униз і нарешті опублікуйте свій модаль. Святкуйте! 🎉
Figma зв’яжеться з вами за кілька днів щодо статусу перегляду вашого моду. У разі відмови вам буде надано можливість внести зміни та подати знову.
Висновок
Ми щойно створили віджет Figma з нуля! Є багато речей, які тут не розглядаються, наприклад натисніть події, форми введення та набагато більше. Ви можете переглянути повний вихідний код віджета в це репо GitHub.
Тим, хто прагне підняти свої навички Figma на вищий рівень, я пропоную дослідити спільноту Widgets і використати те, що приверне вашу увагу, як натхнення. Продовжуйте створювати більше віджетів, продовжуйте відточувати свої навички React, і перш ніж ви навіть це усвідомите, ви навчите мене, як це все робити.
Подальші ресурси
Під час створення цього віджета мені довелося переглянути багато документації. Я вирішив поділитися тим, що мені найбільше допомогло.
