Figma, geliştiriciler ve tasarımcılar arasındaki işbirliğini her zaman teşvik etmiştir. Topluluk yapımı eklentilerden oluşan sonsuz bir hazine üzerinde çalışır. 3D öğelere mi ihtiyacınız var? Bunun için bir eklenti var. Soyut SVG'lere mi ihtiyacınız var? Bunun için bir eklenti varDe.

Bununla birlikte, Figma'nın tasarım kısmı her zaman nispeten statik olmuştur - her zaman önceden tanımlanmış kullanıcı etkileşimleri yoluyla birbirine bağlı hareket etmeyen dikdörtgenlerle çalışır. Ama ya size tasarımlarınızın aniden hayata geçebileceğini, hareketli, etkileşimli ve hatta durumsal olabileceğini söylesem? O halde, konsepti uygulamadan ayıran ne olabilir?

figma haziran ayında açıklandı JavaScript destekli widget'ları masaya getirdiğini. Artık tasarımcılar, doğrudan Figma'da mantık odaklı bileşenlere göz atabilir ve uygulayabilir!

Merhaba de Widget'lar API'sı! Ne olduğunu ve nasıl kullanılacağını bilmek ister misiniz? İşte bu yazıda birlikte yapacağımız şey tam olarak bu.

Figma widget'ları tonlarca olasılık açar

Büyük bir restoran uygulaması tasarlamak için eşinizle XNUMX saat çalıştığınızı hayal edin. İkiniz de zaten aynı Figma panosunda işbirliği yapıyorsunuz; ikiniz de anında gerçekleşen değişikliklerle aynı belgeyi paylaşıyorsunuz.

Elbette, işbirliğinin tasarım sürecinden daha fazlasını içerdiğini zaten biliyorsunuz:

• proje Yönetimi,
• oy toplamak için anketlere ev sahipliği yapmak,
• sahte verileri içe aktarma ve görselleştirme,
• ve hatta belki de saatlerce çalıştıktan sonra serinlemek için çok oyunculu bir oyun oynamak.

Her şeyi yönetmesi ve grubun diğer üyelerine bağlantılar göndermesi için sadece bir kişiye ihtiyacımız var. Ama oh, bu çok verimli değil, değil mi?

İşte burada widget'lar devreye giriyor. Bunların hepsini - evet, her şeyi - Figma'dan hiç ayrılmadan makul bir şekilde yapabiliriz.

Figma'da widget'ları kullanmak isteyebileceğiniz yollardan sadece birkaçı:

liste gider durmadan. Anlayabileceğiniz gibi, belgelerinizde özgürce kullanabileceğiniz çok sayıda widget zaten var. Aslında, Widget'ları Widget'lar menüsünden doğrudan panonuza ekleyebilirsiniz (Shift+I).

Ancak burada widget'ların nasıl kullanılacağını öğrenmek için bulunmuyoruz çünkü bu çok kolay. En iyi yaptığımız şeyi yapalım: kendi Figma widget'ımızı yaratacağız! Bu ilham kaynağı olacak Chris Coyier'in tasarım alıntıları web sitesi. API'yi alacağız, onu widget'a besleyeceğiz, ardından rastgele tasarım alıntılarını doğrudan Figma'da görüntüleyeceğiz.

İşte ihtiyacımız olan şey

Kötü haberlerin taşıyıcısı olmayı sevmiyorum, ancak widget geliştirmek için Windows veya Mac'te olmalısınız. Linux kullanıcıları, üzgünüm ama şansınız kalmadı. (Hala yapabilirsin sanal makine kullan Takip etmek isterseniz.)

Yapacağız Figma Desktop'ı indirin başvuru. Başlamanın en basit yolu, doğrudan uygulamadan bir widget şablonu oluşturmaktır.

Widgets menüsünü açarak yeni bir pano oluşturalım (Shift+ I), konumuna geçiş gelişme sekmesini seçin ve yeni bir öğe oluşturun.

Bunu takiben Figma, yeni widget'ı adlandırmanızı ve daha uygun olup olmadığına karar vermenizi isteyecektir. tasarım panoları veya FigJam panoları fazla. Önceki seçenek bu makalenin amaçları için yeterlidir.

Ve özelleştirme burada bitmiyor; Figma ayrıca size önceden hazırlanmış bir sayaç widget'ı veya Canvas ve Fetch API'lerine (ve diğer tüm tarayıcı API'lerine) erişmenizi sağlayan iFrame etkin bir alternatifle başlama seçeneği de sunar. Basit "Boş" seçeneğiyle gideceğiz, ancak sonunda Getirme API'sini kullanmak için bunu kendimiz değiştireceğiz.

Ardından yeni widget projenizi sisteminizdeki özel bir dizine kaydetmeniz istenecektir. Bu yapıldıktan sonra, terminalinizi başlatın ve o klasöre yönlendirin. Henüz herhangi bir komut çalıştırmayın - bunu daha sonra yapacağız ve Widgets API hakkında daha fazla bilgi edinmek amacıyla kasıtlı olarak bir hata alacağız.

Widget'ı tasarlama

Tasarımı doğrudan çekiyoruz Chris Coyier'in tasarım alıntıları web sitesi. Öyleyse oraya gidelim ve DevTools'u çalıştırarak dalalım.

Burada kullandığım iki anahtar kısayol Ctrl+Shift+C (Ya da Cmd+Shift+C) "Öğe seç" aracını değiştirmek için ve Shift+Click renk biçimini HEX koduna değiştirmek için. Bunu Chris'in web sitesinde kullanılan renkler, yazı tipleri, yazı tipi ağırlıkları ve yazı tipi boyutları hakkında bilgi edinmek için yapıyoruz. Tüm bu bilgiler, bir sonraki adımımız olacak olan Figma'da yakından benzeyen bir widget oluşturmak için çok önemlidir! Yapabilirsiniz tasarlanmış bileşeni al ve kendi tuvalinizde kullanın.

Bu makalenin ana konusu kod yazarak widget oluşturmak olduğu için burada fazla ayrıntıya girmeyeceğim. Ama sana iyi bakmanın ne kadar önemli olduğunu yeterince vurgulayamam. widget'ların stili… CSS-Tricks zaten çok sayıda tasarım odaklı Figma öğreticileri; okuma listenize eklediğinize pişman olmayacaksınız.

Widget'ımızın düzenini oluşturma

Tasarımın ortadan kalkmasıyla, programlama parmaklarımızı çıkarmanın ve widget'ımızın dişlilerini oluşturmaya başlamanın zamanı geldi.

Figma'nın tasarım yapı taşlarını React benzeri bileşenlere dönüştürmesi çok ilginç. Örneğin, otomatik yerleşim özelliğine sahip çerçeve öğeleri şu şekilde temsil edilir:  koddaki bileşen. Buna ek olarak, iki bileşen daha kullanacağız:  ve .

Figma panoma bir göz atın… Sizden tam olarak nesne ağacına odaklanmanızı istiyorum. Widget tasarımımızı JSX koduna çevirebilmek için ihtiyacımız olan şey bu.

Gördüğünüz gibi, tasarım teklifleri widget'ımız içe aktarılacak üç bileşen talep ediyor. Bu, dikkate alındığında yeterli sayıda bileşendir. tam API yalnızca sekiz katman tabanlı düğüm içerir. Ancak yakında göreceğiniz gibi, bu modüller her türlü düzeni oluşturmak için fazlasıyla yeterli.

// code.tsx
const { widget } = figma;
const { AutoLayout, Text, SVG } = widget;

Ve bununla birlikte, React'te yaptığımız gibi widget'ımızın iskeletini oluşturmak için ihtiyacımız olan her şeye sahibiz:

function QuotesWidget() {
  const quote = `...`;
  const author = `...`;

  return (
    
      
      
        {quote}
        — {author}
      
      
    
  );
}

widget.register(QuotesWidget);

Bu kod, en azından söylemek gerekirse, çok kafa karıştırıcı. Şu anda tasarım katmanlarını ayırt edemiyoruz. Neyse ki, bu sorunu kullanarak bu sorunu kolayca çözebiliyoruz. name özelliği.

  
  
    {quote}
    — {author}
  
  
;

Ve elbette, tırnak işareti SVG'lerimizi hala göremiyoruz, o yüzden bunu düzeltmeye çalışalım. bu  bileşen kabul srcbir SVG öğesinin kaynak kodunu alan özellik. Bu konuda söylenecek fazla bir şey yok, o yüzden basit tutalım ve doğrudan koda geri dönelim:

const leftQuotationSvgSrc = `<svg width="117" height="103" viewBox="0 0 117 103" fill="none" xmlns="">
  // shortened for brevity
`;
const rightQuotationSvgSrc = `<svg width="118" height="103" viewBox="0 0 118 103" fill="none" xmlns="">
// shortened for brevity
`;

function QuotesWidget() {
  return (
    
    
  );
}

Sanırım artık her şeyin çok daha net olduğu konusunda hemfikiriz! Bir şeyleri adlandırdığımızda, amaçları kodumuzun okuyucuları için birdenbire çok daha açık hale gelir.

Widget'ımızı gerçek zamanlı olarak önizleme

Figma, widget'lar oluştururken harika bir geliştirici deneyimi sunar (bunlarla sınırlı olmamak üzere) sıcak yeniden yükleme. Bu özellik sayesinde, widget'ımızdaki değişiklikleri gerçek zamanlı olarak kodlayabiliyor ve önizleyebiliyoruz.

Widget menüsünü açarak başlayın (Shift+I), geliştirme sekmesine geçin ve yeni widget'ınızı tahtaya tıklayın veya sürükleyin. Widget'ınızı bulamıyor musunuz? Endişelenmeyin, sadece üç noktalı menüyü tıklayın ve widget'larınızı içe aktarın. manifest.json dosya. Evet, onu varoluşa döndürmek için gereken tek şey bu!

Bekle, ekranınızın altında bir hata mesajı mı aldınız?

Eğer öyleyse, araştıralım. Tıklamak "Konsolu aç” ve ne söylendiğini okuyun. Eğer Konsolu aç düğmesi gitti, hata ayıklama konsolunu açmanın alternatif bir yolu var. Figma logosuna tıklayın, widget kategorisine atlayın ve geliştirme menüsünü ortaya çıkarın.

Bu hata muhtemelen TypeScript'imizi henüz JavaScript'e derlememiş olmamızdan kaynaklanıyor. Bunu komut satırında çalıştırarak yapabiliriz. npm install ve npm run watch. (veya yarn ve yarn watch ). Bu sefer hata yok!

Vurabileceğiniz bir diğer engel, kod her değiştirildiğinde widget'ın yeniden oluşturulamamasıdır. Aşağıdaki bağlam menüsü komutunu kullanarak widget'ımızı güncellemeye kolayca zorlayabiliriz: widget'lar → Widget'ı yeniden oluştur.

Widget'ı şekillendirme

Halihazırda mevcut haliyle, görünüyor Widget'larımızın çoğu hala nihai hedefimizden oldukça uzakta.

Peki, Figma bileşenlerini koddan nasıl şekillendiririz? Belki bir React projesinde yapacağımız gibi CSS ile? Olumsuz. Figma widget'ları ile, herşey stil bir dizi aracılığıyla gerçekleşir iyi belgelenmiş aksesuarlar. Şansımıza bu eşyaların adı neredeyse aynı şekilde Figma'daki meslektaşlarına.

İkimizi yapılandırarak başlayacağız  bileşenler. Yukarıdaki infografikte görebileceğiniz gibi, pervane isimleri amaçlarını oldukça açıklayıcıdır. Bu, doğrudan koda atlamamızı ve bazı değişiklikler yapmaya başlamamızı kolaylaştırıyor. Kodun tamamını bir daha göstermeyeceğim, bu yüzden lütfen parçacıkların ait olduğu yere rehberlik etmesi için bileşen adlarına güvenin.

  
;

Az önce çok ilerleme kaydettik! Widget'ımızın nasıl göründüğünü görmek için kaydedip Figma'ya geri dönelim. Figma'nın yeni değişiklikler üzerine widget'ları nasıl otomatik olarak yeniden yüklediğini hatırlıyor musunuz?

Ama henüz tam olarak orada değil. Ayrıca kök bileşene bir arka plan rengi eklemeliyiz:

Yine, Figma panonuza bir göz atın ve değişikliklerin neredeyse anında widget'a nasıl yansıtılabileceğine dikkat edin.

Bu kılavuz boyunca ilerleyelim ve  bileşenler.

Bir göz attıktan sonra Widget'lar API belgeleri, mülk adlarının, yukarıdaki infografikte görülebileceği gibi, Figma uygulamasındaki benzerleriyle neredeyse aynı olduğu bir kez daha açıktır. Ayrıca Chris'in web sitesini incelediğimiz son bölümdeki değerleri de kullanacağız.

{quote}

— {author}

Widget'a durum ekleme

Widget'ımız şu anda aynı alıntıyı gösteriyor, ancak tüm alıntı havuzundan rastgele çekmek istiyoruz. eklemeliyiz belirtmek, bildirmek tüm React geliştiricilerinin, değişikliği bileşenimizin yeniden oluşturulmasını tetikleyen bir değişken olduğunu bildiği widget'ımıza.

Figma ile durum, useSyncedState kanca; oldukça fazla React'in useState, ancak programcıların benzersiz bir anahtar belirtmesini gerektirir. Bu gereklilik, Figma'nın widget'ımızın durumunu aşağıdakiler arasında senkronize etmesi gerektiği gerçeğinden kaynaklanmaktadır. herşey aynı tasarım panosunu ancak farklı bilgisayarlar aracılığıyla görüntüleyebilen istemciler.

const { useSyncedState } = widget;

function QuotesWidget() {
  const [quote, setQuote] = useSyncedState("quote-text", "");
  const [author, setAuthor] = useSyncedState("quote-author", "");
}

Şimdilik ihtiyacımız olan tüm değişiklik bu. Bir sonraki bölümde, İnternet'ten nasıl veri getirileceğini bulacağız. Spoiler Uyarısı: Göründüğü kadar basit değil.

Ağdan veri alma

Figma'nın bize iFrame özellikli bir widget ile başlama seçeneği sunduğu zamanı hatırlayın. Bu seçeneğe gitmemiş olsak da, yine de bazı özelliklerini uygulamalıyız. Neden basitçe arayamayacağımızı açıklamama izin ver fetch() widget kodumuz içinde.

Bir widget kullandığınızda, kendi bilgisayarınızda başka biri tarafından yazılmış JavaScript kodunu çalıştırıyorsunuz. Tüm gereçler Figma personeli tarafından kapsamlı bir şekilde gözden geçirilse de, hepimizin bildiği gibi hala büyük bir güvenlik açığıdır. bir satır JavaScript bile zarar verebilir.

Sonuç olarak, Figma basitçe eval() anonim programcılar tarafından yazılmış herhangi bir widget kodu. Uzun lafın kısası, ekip en iyi çözümün yakından korunan bir sanal alan ortamında üçüncü taraf kodu çalıştırmak olduğuna karar verdi. Tahmin edebileceğiniz gibi, tarayıcı API'leri böyle bir ortamda kullanılamaz.

Ama endişelenme, Figma'nın bu ikinci soruna çözümü s. Bir dosyaya yazdığımız, tercihen adı verilen herhangi bir HTML kodu ui.html, tüm tarayıcı API'lerine erişebilecek. Bu kodu widget'tan nasıl tetikleyebileceğimizi merak ediyor olabilirsiniz, ancak bunu daha sonra inceleyeceğiz. Şimdi koda geri dönelim:

// manifest.json
{
  "ui": "ui.html"
}

window.onmessage = async (event) => {
  if (event.data.pluginMessage.type === 'networkRequest') {
    // TODO: fetch data from the server

    window.parent.postMessage({
      pluginMessage: {
        // TODO: return fetched data
      }
    }, '*')
  }
}

Widget-to- için genel şablon budur.iframe iletişim. Sunucudan veri almak için kullanalım:

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
      }
    }, '*')
  }
}

Bunu basit ve güncel tutmak için hata işlemeyi dışarıda bırakıyoruz. Widget koduna geri dönelim ve tanımlı fonksiyonlara nasıl eriştiğimizi görelim. :

function fetchData() {
  return new Promise(resolve => {
    figma.showUI(__html__, {visible: false})
    figma.ui.postMessage({type: 'networkRequest'})

    figma.ui.onmessage = async ({authorName, quoteContent}) => {
      setAuthor(authorName)
      setQuote(quoteContent)

      resolve()
    }
  })
}

Gördüğünüz gibi, ilk önce Figma'ya gizli bilgilerimize erişimi açığa çıkarmasını söylüyoruz.  ve adıyla bir olayı tetiklemek için "networkRequest". Biz bu olayı ui.html kontrol ederek dosya event.data.pluginMessage.type === 'networkRequest', ve ardından verileri widget'a geri gönderme.

Ama henüz bir şey olmuyor… Hala aramadık. fetchData() işlev. Doğrudan component fonksiyonunda çağırırsak konsolda aşağıdaki hata oluşur:

Cannot use showUI during widget rendering.

Figma bize aramamamızı söylüyor showUI doğrudan fonksiyon gövdesinde… Peki nereye koyalım? Bunun cevabı yeni bir kanca ve yeni bir işlevdir: useEffect ve waitForTask. zaten aşina olabilirsin useEffect Eğer bir React geliştiricisiyseniz, ancak widget bileşeni bağlandığında sunucudan veri almak için onu burada kullanacağız.

const { useEffect, waitForTask } = widget;

function QuotesWidget() {
  useEffect(() => {
    waitForTask(fetchData());
  });
}

Ancak bu, widget'ımızın sonsuza kadar yeni bir alıntıyla yeniden oluşturmaya devam edeceği başka bir "hata" ile sonuçlanacaktır. Bu olur çünkü useEffect, tanım olarak, widget'ın durumu değiştiğinde, hayır çağırdığımızda yeniden tetiklenir fetchData. Ve süre bir teknik var sadece aramak useEffect React'te bir kez, Figma'nın uygulamasında çalışmaz. Figma'nın dokümanlarından:

Widget'ların Nasıl Çalıştığı Nedeniyle, useEffect aynı durumla birden çok kez çağrılmayı işlemelidir.

Neyse ki, yararlanabileceğimiz ve arayabileceğimiz basit bir geçici çözüm var. useEffect bileşen ilk bağlandığında yalnızca bir kez ve durum değerlerinin hala boş olup olmadığını kontrol ederek:

function QuotesWidget() {
  useEffect(() => {
    if (!author.length & !quote.length) {
      waitForTask(fetchData());
    }
  });
}

Korkunç bir durumla karşılaşabilirsiniz”sınırların dışında hafıza erişimi” hata. Onun eklenti ve widget geliştirmede görmek oldukça yaygın. Sadece Figma'yı yeniden başlatın ve artık orada olmayacak.

Alıntı metninin bazen tuhaf karakterler içerdiğini fark etmiş olabilirsiniz.

Bunlar Unicode karakterler ve bunları kodda uygun şekilde biçimlendirmeliyiz:

window.onmessage = async (event) => {
  // ...
  const quoteContent = decodeEntities(data[0].yoast_head_json.og_description);
};

// 
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(/]*>([Ss]*?)/gim, "");
      str = str.replace(/]|"[^"]*"|'[^']*')*>/gim, "");
      element.innerHTML = str;
      str = element.textContent;
      element.textContent = "";
    }

    return str;
  }

  return decodeHTMLEntities;
})();

Ve voilà, widget'ımız tasarım panosuna her eklendiğinde yepyeni bir tasarım teklifi getirdi.

Widget'ımıza bir özellik menüsü ekleme

Widget'ımız somutlaştırma üzerine yeni bir alıntı getirirken, bu işlemi tekrar ama silmeden yapabilseydik çok daha pratik olurdu. Çözüm oldukça dikkat çekici olduğu için bu bölüm kısa olacak. İle birlikte özellik menüleri, tek bir çağrı ile widget'ımıza etkileşim ekleyebiliriz. usePropertyMenu kancası.

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="">
          
        `,
      },
    ],
    () => fetchData()
  );
}

Basit bir kanca ile, seçildiğinde widget'ımızın yanında görünen bir düğme oluşturabiliyoruz. Bu projeyi tamamlamak için eklememiz gereken son parça buydu.

Widget'ımızı halka yayınlamak

Hiç kimse yoksa, bir widget oluşturmanın pek bir faydası yoktur. kullanım BT. Ve süre Figma, kuruluşlara lansman seçeneği sunuyor özel widget'ları dahili kullanım için, bu küçük programları dünyaya yayınlamak çok daha yaygındır.

Figma, 5 ila 10 iş günü sürebilen hassas bir widget inceleme sürecine sahiptir. Ve birlikte oluşturduğumuz tasarım tırnak widget'ı zaten widget kitaplığında, yine de oraya nasıl geldiğini göstereceğim. Lütfen bu widget'ı yeniden yayınlamaya çalışmayın, çünkü bu yalnızca kaldırılmasıyla sonuçlanacaktır.. Ancak bazı önemli değişiklikler yaptıysanız, devam edin ve kendi widget'ınızı toplulukla paylaşın!

Widget menüsüne tıklayarak başlayın (Shift+I) ve konumuna geçiş gelişme Widget'ımızı görüntülemek için sekmesine tıklayın. Üç nokta menüsüne tıklayın ve Yayınlamak.

Figma, widget'ınız hakkında başlık, açıklama ve bazı etiketler gibi bazı ayrıntıları girmenizi isteyecektir. Ayrıca 128×128 simge resmine ve 1920×960 başlık resmine ihtiyacımız olacak.

Tüm bu varlıkları içe aktardıktan sonra, yine de widget'ımızın ekran görüntüsüne ihtiyacımız var. Yayınlama modunu kapatın (endişelenmeyin, verilerinizi kaybetmezsiniz) ve ilginç bir bağlam menüsü ortaya çıkarmak için widget'a sağ tıklayın. Bul Farklı Kopyala/Yapıştırkategori ve seçin PNG olarak kopyala.

Bunu yaptıktan sonra, yayınlama modeline geri dönelim ve widget'ın ekran görüntüsünü yapıştıralım:

Aşağı kaydırın ve son olarak modelinizi yayınlayın. Kutlamak! 🎉

Figma, modelinizin inceleme durumu hakkında birkaç gün içinde sizinle iletişime geçecektir. Reddedilmesi durumunda, size verilecek değişiklik yapma ve tekrar gönderme fırsatı.

Sonuç

Sıfırdan bir Figma widget'ı oluşturduk! gibi burada ele alınmayan birçok şey var. tıklama etkinlikleri, giriş formları, ve daha fazla. Widget'ın tam kaynak kodunu şuradan inceleyebilirsiniz: bu GitHub deposu.

Figma becerilerini daha üst seviyelere çıkarmak isteyenlere, Widgets topluluğunu keşfetmeyi ve gözünüze çarpanları ilham kaynağı olarak kullanmanızı öneririm. Daha fazla widget oluşturmaya devam edin, React becerilerinizi geliştirmeye devam edin ve siz daha farkına bile varmadan bana tüm bunları nasıl yapacağımı öğretmiş olacaksınız.

Ek kaynaklar

Bu widget'ı yaparken birçok belgeye başvurmak zorunda kaldım. En çok yardımcı olacak bulduğum şeyi paylaşayım dedim.

Daha fazla widget oluşturun:

Widget'ları daha derinlemesine öğrenin:

Widget'lar ve eklentiler