Hoe maak je een Sketch-plug-in die symbolen uit uw bibliotheek verbindt met externe documentatie

Bijna een handleiding voor het bouwen van een Sketch-plug-in met skpm

(Sergey Nikishkin) (28 mei 2020)

Als voorbeeld neem ik Google Materiaal Design Kit for Sketch en verbind symbolen met hun beschrijving op material.io/components . Natuurlijk zal ik niet elke regel code uitleggen, maar ik zal enkele delen belichten die vanuit mijn oogpunt belangrijk zijn. Interessant? Laten we dan beginnen.

Als je niet bekend bent met de ontwikkeling van Sketch-plug-ins, maar meer wilt weten, kan ik deze set van 7 artikelen van Marc Mariano aanbevelen als een gids voor beginners:

( De beginnershandleiding voor het schrijven van schetsplug-ins )

Omgeving

Als bouwtool voor onze plug-in, gebruik ik skpm . Dit is een hulpprogramma waarmee u eenvoudig Sketch-plug-ins kunt bouwen, debuggen en publiceren. Voordat we beginnen, zou je ook de volgende dingen op je mac moeten hebben geïnstalleerd:

Installatie van de skpm en ook als het maken van de basis voor de plug-in is het heel eenvoudig en vereist in totaal twee opdrachten. Maak gewoon een nieuwe map, open Terminal.app in deze map en voer één voor één deze opdrachten in:

  • npm install -g skpm
  • skpm create your-plugin-name

Het eerste commando installeert het npm-pakket zelf en alle vereiste afhankelijkheden. De tweede maakt nog een map aan die een set items bevat voor uw nieuwe plug-in. Onze belangrijkste doelen daar zijn:

  • my-plugin.sketchplugin – de plug-in zelf die moet worden geïnstalleerd
  • src – de map met de broncode van de plug-in
Hoe het resultaat eruitziet in de VS-code
Hoe het resultaat eruitziet in de VS-code

Laat me iets vertellen over manifest.json uit de map src. Dit is een JSON-bestand dat metagegevens bevat over de plug-in, zijn opdrachten en bronnen. Het toont de namen van alle commandos die door de plug-in zijn gedefinieerd en vertelt Sketch hoe de corresponderende menu-items moeten worden opgeroepen en welke menus ze moeten plaatsen.

Laten we ook “dapper de naam naar index.js en verwijdert alle code erin. Even later zullen we iets veel interessanters schrijven dan code die “ Het leeft! 🙌 “bericht.

Het schema

Voordat we beginnen met het schrijven van code, laten we eerst begrijpen hoe de plug-in zal werken werk. Allereerst hebben we drie bestanden nodig:

  • config.json – bevat links die zullen worden verbonden met de symbolen
  • index.js —bevat alle hoofdfuncties
  • manifest.json – bevat plugin-metadata
Het werkschema
Het werkschema

Dus. Wanneer we het symbool op het tekengebied selecteren en de plug-in uitvoeren, roept deze een functie aan van index.js die naar config.json gaat, controleert de beschikbaarheid van de link voor het geselecteerde symbool, geeft het antwoord terug in index.js en opent, als alle controles zijn doorstaan, de bron met documentatie. Zoals je kunt zien, is de logica heel eenvoudig.

Functies

Het eerste dat we moeten doen, is config.json importeren naar index.js door de onderstaande code te gebruiken:

De allereerste regel in index.js

Laten we nu verder gaan met de functies.

openLink ()

In deze functie gebruiken we een aantal klassen en methoden van Swift API die ons zal helpen om externe links rechtstreeks vanuit Sketch te openen.

  • NSURL

  • URLWithString

  • NSWorkspace

  • SharedWorkspace

openLink () functie
  • const {link} = config.names[name] – krijgt een string met URL van config.json
  • const url = NSURL.URLWithString(link) – transformeert tekenreeks met URL naar object met URL
  • NSWorkspace.sharedWorkspace().openURL(url) – opent object met URL in uw standaardbrowser

parse ()

In deze functie matchen we het geselecteerde object op het tekengebied met een object in config.json. Als ze overeenkomen, geeft de functie de sleutel met de URL-link terug.

parse () functie

Naar mijn mening is het meest interessante deel hier een regex op regel 13:

new RegExp(".*(" + set.join("|") + ")(\/|$), "i")

Door te gebruiken deze regex kunnen we objecten op verschillende nestniveaus zoeken en matchen. In ons geval is het object de naam van het symbool of de naam van de groep waar het symbool is geplaatst. Laten we eens kijken naar de neststructuur voor de Chips-component en zijn varianten in Material Design Kit for Sketch:

Structuur van nesting voor chips-component in Material Design Kit for Sketch
Structuur van nesten voor Chips-component in Material Design Kit for Sketch

En hoe deze nesting in het lagenpaneel kan worden vergeleken met config.json:

Hoe afstemmen werkt
Hoe matching werkt

Voor onze reguliere expressie maakt het niet uit op welk niveau je het symbool wilt verbinden met documentatie. De hoofdregel is dat de namen aan beide kanten hetzelfde moeten zijn. Het maakt ook niet uit welke notatie u gebruikt voor het groeperen van symbolen, of het nu gaat om cijfers, letters, onderstrepingstekens, enzovoort. De diepte van de nesting doet er ook niet toe.

isValidType ()

Als je sel ect iets op het tekengebied en start de plug-in, deze functie controleert het type geselecteerd object. En als het object een van de vermelde typen heeft, retourneert het antwoord met true parameter.

isValidType ( ) functie

Gewoon een kleine bonus met de mogelijkheid om niet alleen symbolen maar groepen en vormen met elkaar te verbinden door Sketch Headers te gebruiken.

https://developer.sketch.com/plugins/internal-api

onRun()

Laat me Mathieu Dutour citeren, die de maker is van de skpm.

skpm verwacht ook van jou export default function (context) {} in plaats van een onRun functie op het hoogste niveau te schrijven.

onRun () functie

config.json

So. Het is tijd om een ​​JSON-bestand voor te bereiden dat links naar externe documentatie bevat. Ik heb drie componenten uit de Material Design Kit geselecteerd die we gaan testen: "Banner", "Input chip" en "Card".

config.json met echte gegevens

Zoals je kunt zien, de structuur van het JSON-bestand is heel eenvoudig. Vergeet niet dat de naam van het object in de config.json hetzelfde moet zijn als een deel van de naam van het object in Sketch, zoals ik hierboven heb genoemd.

Overigens kunnen we niet alleen http:// of https:// gebruiken, maar ook zpl:// links waarmee we Zeplin.app-secties kunnen openen.

manifest.json

Zoals ik hierboven al zei, is dit een JSON-bestand dat metadata bevat over de plug-in, zijn opdrachten en resources. De uiteindelijke structuur van manifest.json voor onze plug-in ziet er als volgt uit:

De uiteindelijke structuur van manifest. json

Meer parameters, ook als een gedetailleerde beschrijving van elke parameter die we in dit bestand gebruiken, kun je in de officiële documentatie vinden.

https://developer.sketch.com/plugins/plugin-manifest

Het resu lt

Het is tijd om terug te gaan naar Terminal.app en een plug-in te bouwen:

npm run build

Dat is alles. De plug-in is klaar om te worden geïnstalleerd en getest. Laten we dat eindelijk doen en naar het resultaat kijken.

Het werkt!
Het werkt!

Tot slot

Laten we eerlijk zijn. Dit is meer een experiment dan een kant-en-klaar product, en het is natuurlijk geen ideale implementatie. Ons belangrijkste doel was om niet veel tijd te besteden aan ontwikkeling en dit is de reden waarom we op sommige plaatsen die oplossingen hebben gebruikt die eenvoudiger waren in plaats van correcter. Maar we gebruiken deze plug-in al meer dan een jaar in het dagelijkse werk.En ik zou willen zeggen dat het briljant is voor nieuwe ontwerpers die onlangs in het team zijn beland en net kennis zijn gaan maken met de componenten die u gebruikt.

Ik wil ook graag bedanken aan Kirill Savelov en Dmitry Kozlov voor hun geduld en hulp.

Meer verhalen over ontwerpsysteem en tools

  • (Ontwerpsysteem, deel 2. Pictogrammen, SVG-lettertypen, Gulp)
  • (Ontwerpsysteem, deel 3. Zelfgemaakte tools die we gebruiken in het dagelijkse werk)
  • (ffmpeg + ImageMagick. Converteer video naar GIF met Terminal.app in macOS)
  • (Hoe afbeeldingen optimaliseren met macOS Terminal + TinyPNG CLI)

Handige links

Volg Acronis Design op