A Figma sempre incentivou a colaboração entre desenvolvedores e designers. Ele se esforça em um tesouro infinito de plugins feitos pela comunidade. Precisa de elementos 3D? Existe um plugin para isso. Precisa de SVGs abstratos? Existe um plugin para isso, Também.
Dito isso, a parte de design do Figma sempre foi relativamente estática - sempre trabalhando com retângulos imóveis conectados uns aos outros por meio de interações predefinidas do usuário. Mas e se eu lhe disser que seus designs podem ganhar vida de repente – que podem ser animados, interativos e até mesmo com estado? Então, o que separaria conceito de implementação?
Figma anunciado em junho que está trazendo widgets baseados em JavaScript para a mesa. Agora, os designers podem navegar e implementar componentes orientados por lógica diretamente no Figma!
Diga Olá para a API de widgets! Quer saber o que é e como usar? É exatamente isso que vamos fazer juntos neste post.
Widgets Figma abrem toneladas de possibilidades
Imagine que você está trabalhando XNUMX horas por dia com seu parceiro para projetar um grande aplicativo de restaurante. Vocês dois já estão colaborando no mesmo quadro do Figma; vocês dois estão compartilhando exatamente o mesmo documento com as mudanças acontecendo em tempo real.
Certamente, você já sabe que a colaboração envolve mais do que apenas o processo de design:
- Gerenciamento de Projetos,
- realizar enquetes para coletar votos,
- importação e visualização de dados simulados,
- e talvez até jogar um jogo multiplayer para se refrescar depois de muitas horas de trabalho.
Exigimos apenas que uma pessoa gerencie tudo e envie links para outros membros do grupo. Mas oh, isso não é muito eficiente, é?
Bem, é aí que os widgets entram em jogo. Podemos fazer tudo isso – sim, tudo – sem sair da Figma.
Aqui estão apenas algumas das maneiras pelas quais você pode usar widgets no Figma:
A lista vai e assim por diante. Como você pode ver, já existe uma infinidade de widgets que você pode usar livremente em seus documentos. Na verdade, você pode adicionar Widgets diretamente ao seu quadro a partir do menu Widgets (Shift+I).
Mas não estamos aqui para aprender a usar widgets, porque isso é fácil. Vamos fazer o que fazemos de melhor: vamos criar nosso próprio widget Figma! Este será inspirado Site de citações de design de Chris Coyier. Pegaremos a API, alimentaremos o widget e exibiremos citações aleatórias de design diretamente no Figma.
Aqui está o que precisamos
Eu não gosto de ser o portador de más notícias, mas para desenvolver widgets, você deve estar no Windows ou Mac. Usuários de Linux, sinto muito, mas você está sem sorte. (Você ainda pode usar uma VM se você quiser acompanhar.)
Nós vamos baixe o Figma Desktop inscrição. A maneira mais simples de começar é gerando um modelo de widget diretamente do aplicativo.
Vamos criar um novo quadro abrindo o menu de widgets (Shift+ I), passando para o Desenvolvimento guia e criando um novo item.
Depois disso, o Figma solicitará que você nomeie o novo widget e decida se ele é mais adequado para placas de design ou placas FigJam também. A primeira opção é suficiente para os fins deste artigo.
E a customização não termina aqui; O Figma também lhe dará a opção de começar com um widget de contador pré-fabricado ou uma alternativa habilitada para iFrame que também oferece acesso às APIs Canvas e Fetch (assim como todas as outras APIs do navegador). Iremos com a opção simples “Empty”, mas eventualmente a modificaremos para fazer uso da API Fetch.
Você será solicitado a salvar seu novo projeto de widget em um diretório especial em seu sistema. Feito isso, inicie seu terminal e direcione-o para essa pasta. Não execute nenhum comando ainda — faremos isso mais tarde e obteremos um erro propositalmente com o objetivo de aprender mais sobre a API Widgets.
Projetando o widget
Estamos puxando o design direto de Site de citações de design de Chris Coyier. Então, vamos lá e mergulhar no DevTools.
Os dois atalhos de teclas que estou usando aqui são Ctrl+Shift+C (ou Cmd+Shift+C) para alternar a ferramenta "Selecionar elemento" e Shift+Click para alterar o formato de cor para código HEX. Estamos fazendo isso para aprender sobre as cores, fontes, pesos de fonte e tamanhos de fonte usados no site de Chris. Todas essas informações são fundamentais para construir um widget bem parecido no Figma, que será nosso próximo passo! Você pode pegue o componente projetado e use-o em sua própria tela.
Não entrarei em muitos detalhes aqui, pois o tópico principal deste artigo é construir widgets escrevendo código. Mas eu não posso enfatizar o suficiente como é importante cuidar bem do seu estilo dos widgets… CSS-Tricks já tem uma infinidade de tutoriais Figma orientados ao design; você não vai se arrepender de adicioná-los à sua lista de leitura.
Criando o layout do nosso widget
Com o design fora do caminho, é hora de tirar nossos dedos de programação e começar a construir as engrenagens do nosso widget.
É muito interessante como o Figma traduz seus blocos de construção de design para componentes do tipo React. Os elementos de quadro com o recurso de layout automático, por exemplo, são representados como o <AutoLayout /> componente no código. Além disso, usaremos mais dois componentes: <Text /> e <SVG />.
Dê uma olhada no meu quadro Figma… Estou exatamente pedindo que você se concentre na árvore de objetos. É o que precisamos para poder traduzir nosso design de widget para código JSX.
Como você pode ver, nosso widget de cotações de design exige que três componentes sejam importados. Esse é um número decente de componentes, considerando que o API completa contém apenas oito nós baseados em camada. Mas, como você verá em breve, esses módulos são mais do que suficientes para criar todos os tipos de layouts.
// code.tsx
const { widget } = figma;
const { AutoLayout, Text, SVG } = widget;E com isso, temos tudo o que precisamos para seguir em frente e construir o esqueleto do nosso widget como faríamos no React:
function QuotesWidget() {
const quote = `...`;
const author = `...`;
return (
<AutoLayout>
<SVG />
<AutoLayout>
<Text>{quote}</Text>
<Text>— {author}</Text>
</AutoLayout>
<SVG />
</AutoLayout>
);
}
widget.register(QuotesWidget);Este código é muito confuso, para dizer o mínimo. No momento, não podemos distinguir as camadas de design. Felizmente, conseguimos resolver esse problema facilmente com o uso do name propriedade.
<AutoLayout name={"Quote"}>
<SVG name={"LeftQuotationMark"} />
<AutoLayout name={"QuoteContent"}>
<Text name={"QuoteText"}>{quote}</Text>
<Text name={"QuoteAuthor"}>— {author}</Text>
</AutoLayout>
<SVG name={"RightQuotationMark"} />
</AutoLayout>;E, claro, ainda não podemos ver nossos SVGs com aspas, então vamos trabalhar para corrigir isso. o <SVG/> componente aceitar um srcpropriedade que recebe o código-fonte de um elemento SVG. Não há muito a dizer sobre isso, então vamos simplificar e voltar direto para o código:
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} />
);
}Acho que todos podemos concordar que tudo está muito mais claro agora! Quando nomeamos as coisas, seu propósito de repente se torna muito mais óbvio para os leitores do nosso código.
Visualizando nosso widget em tempo real
O Figma oferece uma ótima experiência ao desenvolvedor ao criar widgets, incluindo (mas não limitado a) recarga a quente. Com esse recurso, podemos codificar e visualizar alterações em nosso widget em tempo real.
Comece abrindo o menu de widgets (Shift+I), alternando para a guia de desenvolvimento e clicando ou arrastando seu novo widget para o quadro. Não foi possível localizar seu widget? Não se preocupe, basta clicar no menu de três pontos e importar o seu widget manifest.json Arquivo. Sim, é tudo o que é preciso para trazê-lo de volta à existência!
Espere, você recebeu uma mensagem de erro na parte inferior da tela?
Se sim, vamos investigar. Clique em "Abra o console” e leia o que tem a dizer. Se o Abra o console botão desaparecer, há uma maneira alternativa de abrir o console de depuração. Clique no logotipo do Figma, vá para a categoria de widgets e revele o menu de desenvolvimento.
Esse erro provavelmente se deve ao fato de ainda não compilarmos nosso TypeScript para JavaScript. Podemos fazer isso na linha de comando executando npm install e npm run watch. (ou yarn e yarn watch ). Sem erros desta vez!
Mais um obstáculo que você pode encontrar é que o widget falha ao renderizar novamente sempre que o código é alterado. Podemos facilmente forçar nosso widget a atualizar usando o seguinte comando de menu de contexto: Widgets → Rerenderizar widget.
Estilizando o widget
Tal como está atualmente, o looks dos nossos widgets ainda estão muito longe do nosso objetivo final.
Então, como estilizamos os componentes do Figma a partir do código? Talvez com CSS como faríamos em um projeto React? Negativo. Com widgets Figma, todos os a estilização acontece através de um conjunto de adereços bem documentados. Para nossa sorte, esses itens são nomeados quase identicamente aos seus homólogos na Figma.
Vamos começar configurando nossos dois <AutoLayout /> componentes. Como você pode ver no infográfico acima, os nomes dos props são bastante descritivos de seu propósito. Isso torna mais fácil para nós ir direto para o código e começar a fazer algumas alterações. Não mostrarei todo o código novamente, portanto, confie nos nomes dos componentes para guiá-lo onde os snippets pertencem.
<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>;Acabamos de avançar muito! Vamos salvar e voltar ao Figma para ver como nosso widget se parece. Lembre-se de como o Figma recarrega os widgets automaticamente após novas alterações?
Mas ainda não está lá. Também devemos adicionar uma cor de fundo ao componente raiz:
<AutoLayout name={"Quote"} fill={"#ffffff"}>Mais uma vez, dê uma olhada no seu quadro Figma e observe como as alterações podem ser refletidas quase imediatamente de volta ao widget.
Vamos seguir este guia e estilizar o <Text> componentes.
Depois de dar uma olhada no Documentação da API de widgets, fica claro novamente que os nomes das propriedades são quase idênticos aos seus equivalentes no aplicativo Figma, como pode ser visto no infográfico acima. Também usaremos os valores da última seção em que inspecionamos o site de Chris.
<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>Adicionando estado ao widget
Nosso widget atualmente exibe a mesma cotação, mas queremos extrair de todo o conjunto de cotações aleatoriamente. Devemos adicionar estado ao nosso widget, que todos os desenvolvedores do React sabem que é uma variável cuja mudança aciona a re-renderização do nosso componente.
Com o Figma, o estado é criado com o useSyncedState gancho; é bastante React's useState, mas exige que os programadores especifiquem uma chave exclusiva. Esse requisito decorre do fato de que o Figma deve sincronizar o estado do nosso widget entre todos os clientes que podem estar visualizando a mesma placa de projeto, mas através de computadores diferentes.
const { useSyncedState } = widget;
function QuotesWidget() {
const [quote, setQuote] = useSyncedState("quote-text", "");
const [author, setAuthor] = useSyncedState("quote-author", "");
}Essa é toda a mudança que precisamos por enquanto. Na próxima seção, descobriremos como buscar dados da Internet. Alerta de spoiler: não é tão simples quanto parece.
Buscando dados da rede
Lembre-se de quando o Figma nos deu a opção de começar com um widget habilitado para iFrame. Embora não tenhamos optado por essa opção, ainda devemos implementar alguns de seus recursos. Deixe-me explicar por que não podemos simplesmente ligar fetch() dentro do nosso código de widget.
Quando você usa um widget, está executando um código JavaScript em seu próprio computador que foi escrito por outra pessoa. Embora todos os widgets sejam minuciosamente revisados pela equipe da Figma, ainda é uma enorme falha de segurança, pois todos sabemos o quanto danos podem ser criados por até mesmo uma linha de JavaScript.
Como resultado, a Figma não pode simplesmente eval() qualquer código de widget escrito por programadores anônimos. Para encurtar a história, a equipe decidiu que a melhor solução era executar código de terceiros em um ambiente de sandbox bem protegido. E como você deve ter adivinhado, as APIs do navegador não estão disponíveis em tal ambiente.
Mas não se preocupe, a solução da Figma para este segundo problema é <iframe>s. Qualquer código HTML que escrevemos em um arquivo, de preferência chamado ui.html, terá acesso a todas as APIs do navegador. Você pode estar se perguntando como podemos acionar esse código a partir do widget, mas veremos isso mais tarde. Agora, vamos voltar ao código:
// 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>Esse é o modelo geral para widget-to-iframe comunicação. Vamos usá-lo para buscar dados do servidor:
<!-- 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>Estamos deixando de lado o tratamento de erros para manter isso simples e direto ao ponto. Vamos voltar ao código do widget e ver como acessamos as funções definidas no <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()
}
})
}Como você pode ver, primeiro estamos dizendo ao Figma para expor o acesso ao nosso <iframe> e para acionar um evento com o nome "networkRequest". Estamos lidando com este evento no ui.html arquivo verificando event.data.pluginMessage.type === 'networkRequest', e, em seguida, postando os dados de volta no widget.
Mas nada está acontecendo ainda... Ainda não ligamos para o fetchData() função. Se chamarmos diretamente na função componente, ocorre o seguinte erro no console:
Cannot use showUI during widget rendering.Figma está nos dizendo para não ligar showUI diretamente no corpo da função... Então, onde devemos colocá-lo? A resposta para isso é um novo gancho e uma nova função: useEffect e waitForTask. Você já deve ter familiaridade com useEffect se você for um desenvolvedor React, mas vamos usá-lo aqui para buscar dados do servidor quando o componente do widget for montado.
const { useEffect, waitForTask } = widget;
function QuotesWidget() {
useEffect(() => {
waitForTask(fetchData());
});
}Mas isso resultará em mais um “erro” em que nosso widget continuará sendo renderizado novamente com uma nova cotação, para sempre. Isso acontece porque useEffect, por definição, dispara novamente sempre que o estado do widget muda, ou melhor, quando chamamos fetchData. E enquanto existe uma técnica para ligar apenas useEffect uma vez no React, ele não funciona na implementação do Figma. Dos documentos da Figma:
Por causa de como os widgets são executados,
useEffectdeve lidar com ser chamado várias vezes com o mesmo estado.
Felizmente, há uma solução simples que podemos aproveitar e chamar useEffect apenas uma vez quando o componente é montado pela primeira vez, e é verificando se os valores do estado ainda estão vazios:
function QuotesWidget() {
useEffect(() => {
if (!author.length & !quote.length) {
waitForTask(fetchData());
}
});
}Você pode se deparar com um assustador “acesso à memória fora dos limites” erro. Isso é bastante comum ver no desenvolvimento de plugins e widgets. Basta reiniciar o Figma e ele não estará mais lá.
Você deve ter notado que, às vezes, o texto da citação contém caracteres estranhos.
Esses são Caracteres Unicode e devemos formatá-los corretamente em código:
<!-- 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>E aqui, nosso widget buscava uma nova cotação de design toda vez que era adicionado ao quadro de design.
Adicionando um menu de propriedades ao nosso widget
Embora nosso widget busque uma nova cotação na instanciação, seria muito mais prático se pudéssemos fazer esse processo novamente, mas sem excluí-lo. Esta seção será curta, pois a solução é bastante notável. Com menus de propriedades, podemos adicionar interatividade ao nosso widget com uma única chamada ao usePropertyMenu gancho.
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()
);
}Com um simples gancho, podemos criar um botão que aparece próximo ao nosso widget quando ele é selecionado. Essa foi a última peça que precisávamos adicionar para concluir este projeto.
Publicando nosso widget para o público
Não há muita utilidade em construir um widget se, bem, ninguém usos isto. E enquanto A Figma concede às organizações a opção de lançar privado Widgets para uso interno, é muito mais comum lançar esses pequenos programas para o mundo.
O Figma possui um delicado processo de revisão de widgets que pode levar de 5 a 10 dias úteis. E enquanto o widget de citações de design que construímos juntos é já na biblioteca de widgets, ainda vou demonstrar como chegou lá. Por favor, não tente republicar este widget novamente, pois isso só resultará na remoção. Mas se você fez algumas alterações significativas, vá em frente e compartilhe seu próprio widget com a comunidade!
Comece clicando no menu de widgets (Shift+I) e mudar para o Desenvolvimento guia para ver nosso widget. Clique no menu de três pontos e pressione Publique.
O Figma solicitará que você insira alguns detalhes sobre seu widget, como título, descrição e algumas tags. Também precisaremos de uma imagem de ícone de 128×128 e uma imagem de banner de 1920×960.
Depois de importar todos esses ativos, ainda precisamos de uma captura de tela do nosso widget. Feche o modal de publicação (não se preocupe, você não perderá seus dados) e clique com o botão direito do mouse no widget para revelar um menu de contexto interessante. Encontre o Copiar/Colar comocategoria e selecione Copiar como PNG.
Feito isso, vamos voltar ao modal de publicação e colar a captura de tela do widget:
Role para baixo e finalmente publique seu modal. Comemoro! 🎉
A Figma entrará em contato com você em alguns dias sobre o status da revisão do seu modal. No caso de uma rejeição, você receberá o oportunidade de fazer alterações e enviar novamente.
Conclusão
Acabamos de construir um widget Figma do zero! Há muitas coisas não cobertas aqui, como clique em eventos, formulários de entrada e muito mais. Você pode explorar o código-fonte completo do widget em este repositório GitHub.
Para aqueles que desejam levar suas habilidades do Figma para níveis maiores, sugiro explorar a comunidade Widgets e usar o que chamar sua atenção como inspiração. Continue construindo mais widgets, continue aprimorando suas habilidades de React e, antes mesmo de perceber, você estará me ensinando como fazer tudo isso.
Recursos adicionais
Eu tive que consultar muita documentação enquanto fazia este widget. Eu pensei em compartilhar o que eu encontrei para ajudar mais.
