Figma zawsze zachęcała do współpracy między programistami a projektantami. Dąży do nieskończonego skarbca wtyczek stworzonych przez społeczność. Potrzebujesz elementów 3D? Jest do tego wtyczka. Potrzebujesz abstrakcyjnych plików SVG? Jest do tego wtyczkaTeż.
To powiedziawszy, część projektowa Figmy zawsze była stosunkowo statyczna — zawsze pracowała z nieruchomymi prostokątami połączonymi ze sobą poprzez predefiniowane interakcje użytkownika. Ale co, jeśli powiem ci, że twoje projekty mogą nagle ożyć — że mogą być animowane, interaktywne, a nawet stanowe? Co zatem oddzieliłoby koncepcję od realizacji?
figma ogłoszono w czerwcu że wprowadza do tabeli widżety oparte na JavaScript. Teraz projektanci mogą przeglądać i wdrażać komponenty sterowane logiką bezpośrednio w Figma!
Powiedz cześć API widżetów! Chcesz wiedzieć, co to jest i jak z niego korzystać? Dokładnie to zrobimy razem w tym poście.
Widżety Figma otwierają mnóstwo możliwości
Wyobraź sobie, że pracujesz ze swoim partnerem przez całą dobę, aby zaprojektować dużą aplikację restauracyjną. Oboje już współpracujecie na tej samej tablicy Figma; oboje udostępniacie ten sam dokument ze zmianami zachodzącymi w locie.
Z pewnością wiesz już, że współpraca to coś więcej niż sam proces projektowania:
- zarządzanie projektami,
- prowadzenie ankiet do zbierania głosów,
- import i wizualizacja makiety danych,
- a może nawet grając w grę wieloosobową, aby ochłodzić się po wielu godzinach pracy.
Potrzebujemy tylko jednej osoby do zarządzania wszystkim i wysyłania linków do innych członków grupy. Ale och, to nie jest zbyt wydajne, prawda?
Cóż, w tym miejscu pojawiają się widżety. Możemy to wszystko zrobić – tak, wszystko – bez opuszczania Figmy.
Oto tylko kilka sposobów, w jakie możesz chcieć używać widżetów w Figma:
Lista idzie my i my. Jak widać, istnieje już mnóstwo widżetów, których możesz swobodnie używać w swoich dokumentach. W rzeczywistości możesz dodawać widżety bezpośrednio do swojej tablicy z menu widżetów (Shift+I).
Ale nie jesteśmy tutaj, aby nauczyć się korzystać z widżetów, ponieważ jest to łatwe. Zróbmy to, co umiemy najlepiej: stworzymy własny widget Figma! Ten będzie inspirowany Strona internetowa z cytatami autorstwa Chrisa Coyiera. Weźmiemy API, wprowadzimy go do widżetu, a następnie wyświetlimy losowe cytaty projektu bezpośrednio w Figma.
Oto czego potrzebujemy
Nie lubię być zwiastunem złych wiadomości, ale aby tworzyć widgety, musisz być na Windowsie lub Macu. Użytkownicy Linuksa, przepraszam, ale nie masz szczęścia. (Możesz nadal użyj maszyny wirtualnej jeśli chcesz kontynuować.)
Będziemy pobierz Pulpit Figma aplikacja. Najprostszym sposobem na rozpoczęcie jest wygenerowanie szablonu widżetu bezpośrednio z aplikacji.
Utwórzmy nową tablicę, otwierając menu widżetów (Shift+ I), przełączając się na oprogramowania zakładka i tworzenie nowej pozycji.
Następnie Figma poprosi Cię o nazwanie nowego widżetu i zdecyduje, czy jest on bardziej dostosowany do tablice projektowe lub tablice FigJam także. Pierwsza opcja jest wystarczająca do celów tego artykułu.
A personalizacja nie kończy się tutaj; Figma daje również możliwość rozpoczęcia od gotowego widżetu licznika lub alternatywy obsługującej iFrame, która daje również dostęp do interfejsów API Canvas i Fetch (jak również wszystkich innych interfejsów API przeglądarki). Pójdziemy z prostą opcją „Opróżnij”, ale ostatecznie sami ją zmodyfikujemy, aby korzystać z interfejsu Fetch API.
Następnie zostaniesz poproszony o zapisanie nowego projektu widżetu w specjalnym katalogu w systemie. Gdy to zrobisz, uruchom terminal i skieruj go do tego folderu. Nie uruchamiaj jeszcze żadnych poleceń — zrobimy to później i celowo otrzymamy błąd, aby dowiedzieć się więcej o interfejsie API widżetów.
Projektowanie widżetu
Projekt czerpiemy prosto z Strona internetowa z cytatami autorstwa Chrisa Coyiera. Więc chodźmy tam i zanurzmy się, uruchamiając DevTools.
Dwa skróty klawiszowe, których tu używam, to Ctrl+Shift+C (lub Cmd+Shift+C), aby przełączyć narzędzie „Wskaż element”, oraz Shift+Click aby zmienić format koloru na kod HEX. Robimy to, aby dowiedzieć się o kolorach, czcionkach, grubościach i rozmiarach czcionek używanych na stronie Chrisa. Wszystkie te informacje są niezbędne do zbudowania bardzo podobnego widżetu w Figmie, który będzie naszym następnym krokiem! Możesz chwyć zaprojektowany komponent i użyj go na swoim własnym płótnie.
Nie będę się tutaj zagłębiał, ponieważ głównym tematem tego artykułu jest budowanie widżetów poprzez pisanie kodu. Ale nie mogę wystarczająco podkreślić, jak ważne jest, aby dobrze o siebie dbać styl widżetów… CSS-Tricks ma już mnóstwo zorientowane na projektowanie tutoriale Figma; nie pożałujesz dodania ich do swojej listy lektur.
Tworzenie layoutu dla naszego widżetu
Po usunięciu projektowania nadszedł czas, aby wyjąć nasze programistyczne palce i zacząć budować koła zębate naszego widżetu.
To bardzo interesujące, jak Figma przekłada swoje elementy konstrukcyjne na komponenty podobne do Reacta. Na przykład elementy ramek z funkcją automatycznego rozmieszczania są reprezentowane jako <AutoLayout /> składnik w kodzie. Oprócz tego użyjemy jeszcze dwóch komponentów: <Text /> i <SVG />.
Spójrz na moją tablicę Figma… właśnie proszę o skupienie się na drzewie obiektów. To jest to, czego potrzebujemy, aby móc przetłumaczyć nasz projekt widżetu na kod JSX.
Jak widać, nasz widżet ofert projektowych wymaga zaimportowania trzech komponentów. To przyzwoita liczba komponentów, biorąc pod uwagę, że pełne API zawiera tylko osiem węzłów opartych na warstwach. Ale jak wkrótce się przekonasz, te moduły są więcej niż wystarczające do tworzenia wszelkiego rodzaju układów.
// code.tsx
const { widget } = figma;
const { AutoLayout, Text, SVG } = widget;A dzięki temu mamy wszystko, czego potrzebujemy, aby zbudować szkielet naszego widżetu, tak jak w React:
function QuotesWidget() {
const quote = `...`;
const author = `...`;
return (
<AutoLayout>
<SVG />
<AutoLayout>
<Text>{quote}</Text>
<Text>— {author}</Text>
</AutoLayout>
<SVG />
</AutoLayout>
);
}
widget.register(QuotesWidget);Ten kod jest co najmniej bardzo mylący. W tej chwili nie możemy odróżnić warstw projektowych. Na szczęście możemy łatwo rozwiązać ten problem, korzystając z name własność.
<AutoLayout name={"Quote"}>
<SVG name={"LeftQuotationMark"} />
<AutoLayout name={"QuoteContent"}>
<Text name={"QuoteText"}>{quote}</Text>
<Text name={"QuoteAuthor"}>— {author}</Text>
</AutoLayout>
<SVG name={"RightQuotationMark"} />
</AutoLayout>;I oczywiście nadal nie widzimy naszych plików SVG w cudzysłowie, więc popracujmy nad tym. The <SVG/> komponent akceptuje a srcwłaściwość, która pobiera kod źródłowy elementu SVG. Nie ma wiele do powiedzenia na ten temat, więc zachowajmy prostotę i wróćmy od razu do kodu:
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} />
);
}Myślę, że wszyscy możemy się zgodzić, że teraz wszystko jest znacznie jaśniejsze! Kiedy nazywamy rzeczy, ich cel nagle staje się znacznie bardziej oczywisty dla czytelników naszego kodu.
Podgląd naszego widżetu w czasie rzeczywistym
Figma oferuje wspaniałe wrażenia programistyczne podczas tworzenia widżetów, w tym (ale nie tylko) przeładowanie na gorąco. Dzięki tej funkcji możemy kodować i wyświetlać podgląd zmian w naszym widżecie w czasie rzeczywistym.
Zacznij od otwarcia menu widżetów (Shift+I), przechodząc do zakładki deweloperskiej i klikając lub przeciągając nowy widżet na tablicę. Nie możesz znaleźć widżetu? Nie martw się, po prostu kliknij menu z trzema kropkami i zaimportuj widżety manifest.json plik. Tak, wystarczy przywrócić go do życia!
Czekaj, czy na dole ekranu pojawił się komunikat o błędzie?
Jeśli tak, zbadajmy. Kliknij "Otwórz konsolę” i przeczytaj, co ma do powiedzenia. Jeśli Otwórz konsolę przycisk zniknął, istnieje alternatywny sposób otwarcia konsoli debugowania. Kliknij logo Figma, przejdź do kategorii widżetów i wyświetl menu programistyczne.
Ten błąd jest prawdopodobnie spowodowany faktem, że nie skompilowaliśmy jeszcze naszego TypeScript do JavaScript. Możemy to zrobić w wierszu poleceń, uruchamiając npm install i npm run watch. (lub yarn i yarn watch ). Tym razem bez błędów!
Jeszcze jedną przeszkodą, którą możesz napotkać, jest to, że widżet nie wyświetla się ponownie za każdym razem, gdy zmienia się kod. Możemy łatwo wymusić aktualizację naszego widżetu za pomocą następującego polecenia menu kontekstowego: widgety → Ponownie renderuj widżet.
Stylizacja widżetu
W obecnym stanie wygląd naszych widżetów wciąż jest daleko od naszego ostatecznego celu.
Jak więc stylizujemy komponenty Figma z kodu? Może z CSS jak w projekcie React? Negatywny. Dzięki widżetom Figma cała kolekcja stylizacja odbywa się poprzez zestaw dobrze udokumentowane rekwizyty. Na szczęście dla nas te przedmioty są prawie nazwane identycznie do ich odpowiedników w Figma.
Zaczniemy od konfiguracji naszych dwóch <AutoLayout /> składniki. Jak widać na powyższej infografice, nazwy rekwizytów dość dobrze opisują ich przeznaczenie. Ułatwia nam to przejście od razu do kodu i rozpoczęcie wprowadzania pewnych zmian. Nie będę ponownie pokazywać całego kodu, więc proszę polegać na nazwach komponentów, aby wskazać, gdzie należy umieścić fragmenty.
<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>;Właśnie zrobiliśmy duży postęp! Zapiszmy i wróćmy do Figmy, aby zobaczyć jak wygląda nasz widżet. Pamiętasz, jak Figma automatycznie przeładowuje widżety po nowych zmianach?
Ale to jeszcze nie koniec. Musimy również dodać kolor tła do głównego komponentu:
<AutoLayout name={"Quote"} fill={"#ffffff"}>Ponownie spójrz na swoją tablicę Figma i zauważ, jak zmiany mogą zostać odzwierciedlone niemal natychmiast z powrotem w widżecie.
Przejdźmy dalej po tym przewodniku i opracujmy styl <Text> składniki.
Po przyjrzeniu się plikowi Dokumentacja API widżetów, ponownie jest jasne, że nazwy właściwości są prawie identyczne z ich odpowiednikami w aplikacji Figma, jak widać na powyższej infografice. Będziemy również używać wartości z ostatniej sekcji, w której sprawdzaliśmy witrynę Chrisa.
<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>Dodawanie stanu do widżetu
Nasz widżet wyświetla obecnie ten sam cytat, ale chcemy losowo pobierać z całej puli cytatów. Musimy dodać były do naszego widżetu, o którym wszyscy programiści React wiedzą, że jest zmienną, której zmiana powoduje ponowne renderowanie naszego komponentu.
W Figma stan jest tworzony za pomocą useSyncedState hak; to prawie React useState, ale wymaga od programistów określenia unikalnego klucza. Wymóg ten wynika z faktu, że Figma musi synchronizować stan naszego widżetu w poprzek cała kolekcja klienci, którzy mogą oglądać tę samą tablicę projektową, ale za pośrednictwem różnych komputerów.
const { useSyncedState } = widget;
function QuotesWidget() {
const [quote, setQuote] = useSyncedState("quote-text", "");
const [author, setAuthor] = useSyncedState("quote-author", "");
}To cała zmiana, której na razie potrzebujemy. W następnej sekcji dowiemy się, jak pobrać dane z Internetu. Spoiler Alert: to nie jest takie proste, jak się wydaje.
Pobieranie danych z sieci
Przypomnij sobie, kiedy Figma dała nam wybór, aby zacząć od widżetu obsługującego iFrame. Chociaż nie zdecydowaliśmy się na tę opcję, nadal musimy zaimplementować niektóre jej funkcje. Pozwól mi wyjaśnić, dlaczego nie możemy po prostu zadzwonić fetch() w naszym kodzie widżetu.
Kiedy używasz widżetu, uruchamiasz na swoim komputerze kod JavaScript napisany przez kogoś innego. Chociaż wszystkie widżety są dokładnie sprawdzane przez personel Figma, wciąż jest to ogromna luka w zabezpieczeniach, ponieważ wszyscy wiemy, ile uszkodzenie może spowodować nawet jedna linia JavaScript.
W rezultacie Figma nie może po prostu eval() dowolny kod widgetu napisany przez anonimowych programistów. Krótko mówiąc, zespół zdecydował, że najlepszym rozwiązaniem jest uruchamianie kodu firm trzecich w ściśle strzeżonym środowisku piaskownicy. Jak można się domyślić, interfejsy API przeglądarki są niedostępne w takim środowisku.
Ale nie martw się, rozwiązanie Figmy na ten drugi problem jest <iframe>s. Dowolny kod HTML, który zapisujemy w pliku, najlepiej o nazwie ui.html, będzie mieć dostęp do wszystkich interfejsów API przeglądarki. Być może zastanawiasz się, jak możemy wywołać ten kod z widżetu, ale zajmiemy się tym później. Teraz wróćmy do kodu:
// 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>To jest ogólny szablon dla widżetu doiframe Komunikacja. Użyjmy go do pobrania danych z serwera:
<!-- 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>Pomijamy obsługę błędów, aby było to proste i rzeczowe. Wróćmy do kodu widżetu i zobaczmy, jak uzyskujemy dostęp do funkcji zdefiniowanych w <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()
}
})
}Jak widać, najpierw mówimy Figmie, aby ujawniła dostęp do naszego ukrytego <iframe> i wywołać zdarzenie o nazwie "networkRequest". Obsługujemy to wydarzenie w ui.html plik sprawdzając event.data.pluginMessage.type === 'networkRequest', a następnie przesyłanie danych z powrotem do widżetu.
Ale jeszcze nic się nie dzieje… Nadal nie dzwoniliśmy fetchData() funkcjonować. Jeśli wywołamy go bezpośrednio w funkcji komponentu, w konsoli pojawi się następujący błąd:
Cannot use showUI during widget rendering.Figma każe nam nie dzwonić showUI bezpośrednio w treści funkcji… Więc gdzie powinniśmy to umieścić? Odpowiedzią na to jest jeden nowy haczyk i jedna nowa funkcja: useEffect i waitForTask. Być może znasz już useEffect jeśli jesteś programistą React, ale użyjemy go tutaj, aby pobrać dane z serwera po zamontowaniu komponentu widgetu.
const { useEffect, waitForTask } = widget;
function QuotesWidget() {
useEffect(() => {
waitForTask(fetchData());
});
}Ale spowoduje to kolejny „błąd”, w którym nasz widżet będzie na zawsze renderował się z nowym cytatem. Dzieje się tak, ponieważ useEffect, z definicji, uruchamia się ponownie za każdym razem, gdy zmieni się stan widżetu, nie, gdy wywołamy fetchData. I podczas gdy jest technika tylko dzwonić useEffect raz w React nie działa na implementacji Figmy. Z dokumentów Figmy:
Ze względu na sposób działania widżetów
useEffectpowinien obsługiwać wielokrotne wywoływanie z tym samym stanem.
Na szczęście istnieje proste obejście, z którego możemy skorzystać i zadzwonić useEffect tylko raz, gdy komponent montuje się po raz pierwszy, i sprawdza się, czy wartości stanu są nadal puste:
function QuotesWidget() {
useEffect(() => {
if (!author.length & !quote.length) {
waitForTask(fetchData());
}
});
}Możesz wpaść w przerażające „dostęp do pamięci poza granicami” błąd. Jego dość powszechne w rozwoju wtyczek i widżetów. Po prostu uruchom ponownie Figmę i już jej tam nie będzie.
Być może zauważyłeś, że czasami tekst cytatu zawiera dziwne znaki.
To są Znaki Unicode i musimy je odpowiednio sformatować w kodzie:
<!-- 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>oraz voilà, nasz widżet pobierał zupełnie nowy cytat z projektu za każdym razem, gdy był dodawany do tablicy projektów.
Dodanie menu właściwości do naszego widżetu
Podczas gdy nasz widżet pobiera nowy cytat po utworzeniu instancji, byłoby o wiele bardziej praktyczne, gdybyśmy mogli wykonać ten proces ponownie, ale bez jego usuwania. Ta sekcja będzie krótka, ponieważ rozwiązanie jest dość niezwykłe. Z menu właściwości, możemy dodać interaktywność do naszego widżetu za pomocą jednego wywołania usePropertyMenu hak.
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()
);
}Za pomocą jednego prostego haka jesteśmy w stanie utworzyć przycisk, który pojawi się obok naszego widżetu, gdy zostanie wybrany. To był ostatni element, który musieliśmy dodać, aby ukończyć ten projekt.
Publikowanie naszego widżetu publicznie
Nie ma sensu budować widżetu, jeśli, no cóż, nikt zastosowania to. I kiedy Figma daje organizacjom możliwość uruchomienia prywatny widgety do użytku wewnętrznego znacznie częściej udostępnia się te małe programy światu.
Figma ma delikatny proces przeglądu widżetów, który może potrwać od 5 do 10 dni roboczych. I chociaż widżet cytatów projektowych, który wspólnie zbudowaliśmy, jest już w bibliotece widżetów, nadal pokażę, jak się tam dostało. Nie próbuj ponownie publikować tego widżetu, ponieważ spowoduje to tylko usunięcie. Ale jeśli dokonałeś znaczących zmian, śmiało udostępnij swój własny widżet społeczności!
Zacznij od kliknięcia menu widżetów (Shift+I) i przełączenie na oprogramowania zakładka, aby wyświetlić nasz widżet. Kliknij menu z trzema kropkami i naciśnij Publikować.
Figma poprosi o wprowadzenie pewnych szczegółów dotyczących widżetu, takich jak tytuł, opis i kilka tagów. Potrzebny będzie również obraz ikony 128×128 i obraz banera 1920×960.
Po zaimportowaniu wszystkich tych zasobów nadal potrzebujemy zrzutu ekranu naszego widżetu. Zamknij tryb publikowania (nie martw się, nie stracisz swoich danych) i kliknij prawym przyciskiem myszy widżet, aby wyświetlić interesujące menu kontekstowe. Znaleźć Kopiuj/Wklej jakokategorię i wybierz Skopiuj jako PNG.
Po wykonaniu tych czynności wróćmy do modalności publikowania i wklejmy zrzut ekranu widżetu:
Przewiń w dół i na koniec opublikuj swój mod. Świętować!
Za kilka dni Figma skontaktuje się z Tobą w sprawie statusu przeglądu Twojego modalu. W przypadku odrzucenia otrzymasz możliwość wprowadzenia zmian i ponownego zgłoszenia.
Wnioski
Właśnie zbudowaliśmy widżet Figma od podstaw! Jest tu wiele rzeczy, których nie omówiono, takich jak kliknij wydarzenia, formularze wejściowe, wiele więcej. Możesz zagłębić się w pełny kod źródłowy widżetu w to repozytorium GitHub.
Tym, którzy dążą do wzniesienia swoich umiejętności Figma na wyższy poziom, sugeruję zbadanie społeczności Widgets i wykorzystanie tego, co przyciąga wzrok, jako inspiracji. Buduj więcej widżetów, doskonal swoje umiejętności React, a zanim nawet zdasz sobie z tego sprawę, nauczysz mnie, jak to wszystko robić.
Dalsze zasoby
Podczas tworzenia tego widżetu musiałem odwołać się do wielu dokumentacji. Pomyślałem, że podzielę się tym, co znalazłem, aby pomóc najbardziej.
