Figma har altid opfordret til samarbejde mellem udviklere og designere. Det stræber efter en endeløs skatkammer af community-made plugins. Har du brug for 3D-elementer? Der er et plugin til det. Har du brug for abstrakte SVG'er? Der er et plugin til det, Også.
Når det er sagt, har designdelen af Figma altid været relativt statisk - altid arbejdet med ubevægelige rektangler forbundet med hinanden gennem foruddefinerede brugerinteraktioner. Men hvad nu hvis jeg fortalte dig, at dine designs pludselig kunne komme til live - at de kunne være animerede, interaktive og endda statelige? Hvad vil så adskille koncept fra implementering?
figma annonceret i juni at det bringer JavaScript-drevne widgets til bordet. Nu kan designere gennemse og implementere logikdrevne komponenter direkte i Figma!
Sig hej til Widgets API! Vil du vide, hvad det er, og hvordan du bruger det? Det er præcis, hvad vi skal gøre sammen i dette indlæg.
Figma-widgets åbner tonsvis af muligheder
Forestil dig, at du arbejder døgnet rundt med din partner for at designe en stor restaurantapplikation. I samarbejder allerede begge på det samme Figma-kort; I deler begge præcis det samme dokument med ændringer, der sker undervejs.
Du ved sikkert allerede, at samarbejde involverer mere end blot designprocessen:
- projektledelse,
- afholdelse af afstemninger for at samle stemmer,
- import og visualisering af falske data,
- og måske endda spille et multiplayer-spil for at køle af efter mange timers arbejde.
Vi kræver blot, at én person administrerer alt og sender links til andre medlemmer af gruppen. Men åh, det er ikke særlig effektivt, er det?
Nå, det er her widgets kommer i spil. Vi kan tænkes at gøre alt det - ja, alt - uden nogensinde at forlade Figma.
Her er blot nogle af de måder, du måske ønsker at bruge widgets i Figma:
Listen går vi og vi. Som du kan se, er der allerede et væld af widgets, som du frit kan bruge i dine dokumenter. Faktisk kan du tilføje Widgets direkte til dit board fra Widgets-menuen (Shift+I).
Men vi er ikke her for at lære at bruge widgets, for det er nemt. Lad os gøre det, vi er bedst til: Vi vil skabe vores egen Figma-widget! Denne vil blive inspireret af Chris Coyiers hjemmeside for designcitater. Vi tager API'en, indlæser den i widget'en og viser derefter tilfældige designcitater direkte i Figma.
Her er hvad vi har brug for
Jeg kan ikke lide at være bærer af dårlige nyheder, men for at udvikle widgets skal du være på Windows eller Mac. Linux-brugere, jeg er ked af det, men du er uheldig. (Du kunne stadig bruge en VM hvis du vil følge med.)
Vi skal download Figma Desktop Ansøgning. Den nemmeste måde at komme i gang på er ved at generere en widgetskabelon direkte fra appen.
Lad os oprette en ny tavle ved at åbne widgets-menuen (Shift+ I), skifter til Udvikling fanen og oprette et nyt element.
Efter det vil Figma bede dig om at navngive den nye widget og beslutte, om den er mere skræddersyet til designtavler eller FigJam-tavler også. Den førstnævnte mulighed er tilstrækkelig til formålet med denne artikel.
Og tilpasningen slutter ikke her; Figma vil også give dig mulighed for at starte med en forudlavet tæller-widget eller et iFrame-aktiveret alternativ, der også giver dig adgang til Canvas og Fetch API'erne (såvel som alle andre browser API'er). Vi vil gå med den enkle "Empty"-indstilling, men vi vil i sidste ende selv ændre den for at gøre brug af Fetch API.
Du bliver derefter bedt om at gemme dit nye widgetprojekt i en særlig mappe i dit system. Når det er gjort, skal du starte din terminal og dirigere den til den mappe. Kør ikke nogen kommandoer endnu – vi gør det senere og får målrettet en fejl med det formål at lære mere om Widgets API.
Design af widgetten
Vi trækker designet direkte fra Chris Coyiers hjemmeside for designcitater. Så lad os tage derhen og dykke ned i ved at starte DevTools.
De to nøglegenveje, som jeg bruger her, er Ctrl+Shift+C (eller Cmd+Shift+C) for at skifte værktøjet "Vælg element", og Shift+Click for at ændre farveformatet til HEX-kode. Vi gør dette for at lære om de farver, skrifttyper, skrifttypevægte og skriftstørrelser, der bruges på Chriss hjemmeside. Alle disse oplysninger er afgørende for at bygge en widget, der ligner meget i Figma, hvilket vil være vores næste skridt! Du kan tag fat i den designede komponent og brug det i dit eget lærred.
Jeg vil ikke gå i detaljer her, da denne artikels hovedemne er at bygge widgets ved at skrive kode. Men jeg kan ikke understrege nok, hvor vigtigt det er at passe godt på sin widgets stil… CSS-Tricks har allerede et væld af designorienterede Figma tutorials; du vil ikke fortryde at tilføje dem til din læseliste.
Oprettelse af layoutet til vores widget
Med design af vejen, er det tid til at tage vores programmeringsfingre ud og begynde at bygge gearene til vores widget.
Det er meget interessant, hvordan Figma oversætter sine designbyggesten til React-lignende komponenter. Rammeelementer med auto-layout-funktionen er for eksempel repræsenteret som <AutoLayout /> komponent i kode. Ud over det bruger vi yderligere to komponenter: <Text /> , <SVG />.
Tag et kig på min Figma-tavle… Jeg beder dig netop om at fokusere på objekttræet. Det er det, vi skal bruge for at kunne oversætte vores widget-design til JSX-kode.
Som du kan se, kræver vores designcitat-widget, at tre komponenter skal importeres. Det er et anstændigt antal komponenter i betragtning af, at fuld API indeholder kun otte lagbaserede noder. Men som du snart vil se, er disse moduler mere end tilstrækkelige til at lave alle slags layouts.
// code.tsx
const { widget } = figma;
const { AutoLayout, Text, SVG } = widget;Og med dette har vi alt, hvad vi behøver for at gå videre og bygge skelettet af vores widget, som vi ville have i React:
function QuotesWidget() {
const quote = `...`;
const author = `...`;
return (
<AutoLayout>
<SVG />
<AutoLayout>
<Text>{quote}</Text>
<Text>— {author}</Text>
</AutoLayout>
<SVG />
</AutoLayout>
);
}
widget.register(QuotesWidget);Denne kode er mildest talt meget forvirrende. Lige nu kan vi ikke skelne designlagene fra hinanden. Heldigvis er vi i stand til nemt at løse dette problem ved at bruge name ejendom.
<AutoLayout name={"Quote"}>
<SVG name={"LeftQuotationMark"} />
<AutoLayout name={"QuoteContent"}>
<Text name={"QuoteText"}>{quote}</Text>
<Text name={"QuoteAuthor"}>— {author}</Text>
</AutoLayout>
<SVG name={"RightQuotationMark"} />
</AutoLayout>;Og selvfølgelig kan vi stadig ikke se vores anførselstegn SVG'er, så lad os arbejde på at rette det. Det <SVG/> komponent acceptere en srcegenskab, der tager kildekoden til et SVG-element. Der er ikke meget at sige om denne, så lad os holde det enkelt og hoppe direkte tilbage til koden:
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} />
);
}Jeg tror, vi alle kan blive enige om, at alt er meget klarere nu! Når vi navngiver ting, bliver deres formål pludselig meget mere indlysende for læserne af vores kode.
Forhåndsvisning af vores widget i realtid
Figma tilbyder en fantastisk udvikleroplevelse, når du bygger widgets, inklusive (men ikke begrænset til) varm-genladning. Med denne funktion er vi i stand til at kode og forhåndsvise ændringer til vores widget i realtid.
Kom i gang ved at åbne widgets-menuen (Shift+I), skifte til udviklingsfanen og klikke eller trække din nye widget til tavlen. Kan du ikke finde din widget? Bare rolig, klik blot på menuen med tre prikker og importer din widgets manifest.json fil. Ja, det er alt, hvad der skal til, bringe det tilbage til eksistensen!
Vent, fik du en fejlmeddelelse nederst på skærmen?
Hvis ja, lad os undersøge det. Klik på "Åbn konsollen” og læs hvad den har at sige. Hvis Åbn konsollen knappen er væk, er der en alternativ måde at åbne fejlfindingskonsollen på. Klik på Figma-logoet, hop til widgets-kategorien og afslør udviklingsmenuen.
Denne fejl skyldes sandsynligvis det faktum, at vi endnu ikke har kompileret vores TypeScript til JavaScript. Vi kan gøre det på kommandolinjen ved at køre npm install , npm run watch. (eller yarn , yarn watch ). Ingen fejl denne gang!
Endnu en hindring, du kan støde på, er, at widgetten ikke gengives igen, hver gang koden ændres. Vi kan nemt tvinge vores widget til at opdatere ved hjælp af følgende kontekstmenukommando: Widgets → Gengiv widget.
Styler widgetten
Som det er i øjeblikket, er udseende af vores widgets er stadig temmelig langt fra vores endelige mål.
Så hvordan styler vi Figma-komponenter fra kode? Måske med CSS, som vi ville gøre i et React-projekt? Negativ. Med Figma-widgets, alle stylingen sker gennem et sæt af veldokumenterede rekvisitter. Heldigt for os er disse varer næsten navngivet identisk til deres kolleger i Figma.
Vi starter med at konfigurere vores to <AutoLayout /> komponenter. Som du kan se i infografikken ovenfor, er propnavne ret beskrivende for deres formål. Dette gør det nemt for os at hoppe direkte ind i koden og begynde at lave nogle ændringer. Jeg vil ikke vise hele koden igen, så stol venligst på komponentnavnene til at guide dig, hvor uddragene hører hjemme.
<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>;Vi har lige gjort store fremskridt! Lad os gemme og hoppe tilbage til Figma for at se, hvordan vores widget ser ud. Kan du huske, hvordan Figma genindlæser widgets automatisk ved nye ændringer?
Men det er der ikke helt endnu. Vi skal også tilføje en baggrundsfarve til rodkomponenten:
<AutoLayout name={"Quote"} fill={"#ffffff"}>Igen, tag et kig på din Figma-tavle og læg mærke til, hvordan ændringer kan afspejles næsten øjeblikkeligt tilbage i widgetten.
Lad os bevæge os langs denne guide og style den <Text> komponenter.
Efter at have kigget på Widgets API dokumentation, er det igen tydeligt, at ejendomsnavne er næsten identiske med deres modstykker i Figma-appen, som det kan ses i infografikken ovenfor. Vi vil også bruge værdier fra det sidste afsnit, hvor vi inspicerede Chris' hjemmeside.
<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>Tilføjer tilstand til widgetten
Vores widget viser i øjeblikket det samme citat, men vi ønsker at trække fra hele puljen af citater tilfældigt. Vi må tilføje tilstand til vores widget, som alle React-udviklere ved er en variabel, hvis ændring udløser gengengivelsen af vores komponent.
Med Figma skabes tilstand med useSyncedState krog; det er ret meget Reager useState, men det kræver, at programmører angiver en unik nøgle. Dette krav stammer fra det faktum, at Figma skal synkronisere vores widgets tilstand på tværs alle klienter, der kan se det samme designboard, men gennem forskellige computere.
const { useSyncedState } = widget;
function QuotesWidget() {
const [quote, setQuote] = useSyncedState("quote-text", "");
const [author, setAuthor] = useSyncedState("quote-author", "");
}Det er al den forandring, vi har brug for lige nu. I næste afsnit finder vi ud af, hvordan man henter data fra internettet. Spoiler Alert: det er ikke så simpelt, som det ser ud til.
Henter data fra netværket
Husk, da Figma gav os valget om at starte med en iFrame-aktiveret widget. Selvom vi ikke valgte denne mulighed, skal vi stadig implementere nogle af dens funktioner. Lad mig forklare hvorfor vi ikke bare kan ringe fetch() i vores widget-kode.
Når du bruger en widget, kører du JavaScript-kode på din egen computer, som er skrevet af en anden. Selvom alle widgets bliver grundigt gennemgået af Figma-personalet, er det stadig et stort sikkerhedshul, da vi alle ved, hvor meget skade kan skabes af selv en linje JavaScript.
Som et resultat kan Figma ikke blot eval() enhver widget-kode skrevet af anonyme programmører. Lang historie kort, holdet besluttede, at den bedste løsning var at køre tredjepartskode i et tæt bevogtet sandkassemiljø. Og som du måske har gættet, er browser-API'er ikke tilgængelige i et sådant miljø.
Men fortvivl ikke, Figmas løsning på dette andet problem er <iframe>s. Enhver HTML-kode, som vi skriver i en fil, helst kaldet ui.html, vil have adgang til alle browser-API'er. Du undrer dig måske over, hvordan vi kan udløse denne kode fra widgetten, men vi vil se nærmere på det senere. Lige nu, lad os springe tilbage til koden:
// 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>Det er den generelle skabelon for widget-til-iframe meddelelse. Lad os bruge det til at hente data fra serveren:
<!-- 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>Vi udelader fejlhåndtering for at holde dette enkelt og præcist. Lad os springe tilbage til widgetkoden og se, hvordan vi får adgang til funktioner, der er defineret i <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()
}
})
}Som du kan se, fortæller vi først Figma at afsløre adgangen til vores skjulte <iframe> og for at udløse en begivenhed med navnet "networkRequest". Vi håndterer denne begivenhed i ui.html fil ved at kontrollere event.data.pluginMessage.type === 'networkRequest', og derefter sende data tilbage til widget'en.
Men der sker ikke noget endnu... Vi har stadig ikke ringet til fetchData() fungere. Hvis vi kalder det direkte i komponentfunktionen, opstår følgende fejl i konsollen:
Cannot use showUI during widget rendering.Figma fortæller os ikke at ringe showUI direkte i funktionslegemet... Så hvor skal vi placere det? Svaret på det er én ny krog og én ny funktion: useEffect , waitForTask. Du har måske allerede kendskab til useEffect hvis du er en React-udvikler, men vi vil bruge det her til at hente data fra serveren, når widget-komponenten monteres.
const { useEffect, waitForTask } = widget;
function QuotesWidget() {
useEffect(() => {
waitForTask(fetchData());
});
}Men dette vil resultere i endnu en "fejl", hvor vores widget vil blive ved med at gengive med et nyt citat, for evigt. Dette sker pga useEffect, per definition, udløses igen, hver gang widgetens tilstand ændres, nej når vi kalder fetchData. Og mens der er en teknik kun at ringe useEffect en gang i React, virker det ikke på Figmas implementering. Fra Figmas dokumenter:
På grund af hvordan widgets kører,
useEffectskal klare at blive kaldt flere gange med samme tilstand.
Heldigvis er der en enkel løsning, som vi kan drage fordel af og ringe til useEffect kun én gang, når komponenten først monteres, og det er ved at kontrollere, om tilstandens værdier stadig er tomme:
function QuotesWidget() {
useEffect(() => {
if (!author.length & !quote.length) {
waitForTask(fetchData());
}
});
}Du kan løbe ind i en skræmmende "hukommelsesadgang uden for grænserne" fejl. Det er ret almindeligt at se i plugin- og widgetudvikling. Bare genstart Figma, så er den der ikke længere.
Du har måske bemærket, at citatteksten nogle gange indeholder mærkelige tegn.
Disse er Unicode-tegn og vi skal formatere dem korrekt i kode:
<!-- 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>og voilà, hentede vores widget et helt nyt designtilbud, hver gang den blev føjet til designtavlen.
Tilføjelse af en ejendomsmenu til vores widget
Mens vores widget henter et nyt tilbud ved instansiering, ville det være meget mere praktisk, hvis vi kunne gøre denne proces igen, men uden at slette den. Dette afsnit bliver kort, da løsningen er ret bemærkelsesværdig. Med ejendomsmenuer, kan vi tilføje interaktivitet til vores widget med et enkelt opkald til usePropertyMenu krog.
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()
);
}Med en simpel krog er vi i stand til at oprette en knap, der vises i nærheden af vores widget, når den er valgt. Det var det sidste stykke, vi skulle tilføje for at fuldføre dette projekt.
Udgivelse af vores widget til offentligheden
Der er ikke meget brug for at bygge en widget, hvis der ikke er nogen bruger det. Og mens Figma giver organisationer mulighed for at lancere private widgets til internt brug er det meget mere almindeligt at udgive disse små programmer til verden.
Figma har en delikat widgetgennemgang, der kan tage op til 5 til 10 hverdage. Og mens design citater widget vi byggede sammen er allerede i widgetbiblioteket, jeg vil stadig demonstrere, hvordan det kom dertil. Forsøg ikke at genudgive denne widget igen, da det kun vil resultere i fjernelse. Men hvis du har givet den nogle væsentlige ændringer, så fortsæt og del din egen widget med fællesskabet!
Kom i gang ved at klikke på widgets-menuen (Shift+I) og skifte til Udvikling fanen for at se vores widget. Klik på menuen med tre prikker, og tryk på Udgiv.
Figma vil bede dig om at indtaste nogle detaljer om din widget, såsom en titel, beskrivelse og nogle tags. Vi skal også bruge et 128×128 ikonbillede og et 1920×960 bannerbillede.
Efter at have importeret alle disse aktiver, har vi stadig brug for et skærmbillede af vores widget. Luk udgivelsesmodalen (bare rolig, du mister ikke dine data) og højreklik på widgetten for at afsløre en interessant kontekstmenu. Find Kopiér/indsæt somkategori og vælg Kopiér som PNG.
Når det er gjort, lad os gå tilbage til udgivelsesmodalen og indsætte widgettens skærmbillede:
Rul ned og udgiv endelig din modal. Fejre! 🎉
Figma kontakter dig om et par dage om status for din modals gennemgang. I tilfælde af et afslag, vil du blive givet mulighed for at foretage ændringer og indsende igen.
Konklusion
Vi har lige bygget en Figma-widget fra bunden! Der er mange ting, der ikke er dækket her, som f.eks klik på begivenheder, input formularerog meget mere. Du kan grave i den fulde kildekode for widgetten i denne GitHub-repo.
Til dem, der stræber efter at tage deres Figma-færdigheder til et højere niveau, foreslår jeg, at du udforsker Widgets-fællesskabet og bruger det, der fanger dit øje, som inspiration. Bliv ved med at bygge flere widgets, fortsæt med at skærpe dine React-færdigheder, og før du overhovedet indser det, vil du lære mig, hvordan man gør alt dette.
Yderligere ressourcer
Jeg var nødt til at henvise til masser af dokumentation, mens jeg lavede denne widget. Jeg tænkte, at jeg ville dele, hvad jeg fandt for at hjælpe mest.
