Sa miaging duha ka tuig mas nalambigit ko sa dokumentasyon. Ang pagsulat sa usa ka pagpatin-aw nga teksto bahin sa kung giunsa kini o kana nga sistema molihok sa kasagaran yano ra. Ang pagdrowing og diagram nga magpakita sa tanang importanteng butang ug ang koneksyon tali niini nga mga butang sayon ββra usab.
Apan ang labing problemado nga aspeto mao ang pagpadayon sa kini nga dokumentasyon nga hangtod karon. Ug maayo ang teksto, apan ang mga diagram... Kay... ang tanang dokumentasyon kay online, i.e. sa html nga pormat, unya ang teksto giubanan sa gif/jpeg/png nga mga hulagway, nga aktuwal nga nagpakita sa mga diagram. Ug ang mga diagram gilaraw sa lainlaing mga programa sama sa Visio o mga serbisyo sa online a la draw.io. Dayon imong i-export ang diagram ngadto sa graphic format ug i-attach kini sa html. Yano ra.
Unsa man ang problema?
Ang mga laraw kasagaran yano. Mas tukma, dili kaayo komplikado. Oo, ang gidaghanon sa mga butang usa ka dosena o duha, ang gidaghanon sa mga koneksyon halos parehas. Dugang nga mga pirma, pipila ka mga ngalan. Ang yano nga mga laraw mahimong mahulagway sa mga pulong, apan labi ka komplikado, ahem... (c) "dili sila makasabut, sir." Adunay daghang mga laraw, ang mga pagbag-o kinahanglan nga himuon sa kanila matag karon ug unya, episodic, i.e. kanunay, tungod kay nagsunod sila sa pagpalambo sa atong mga produkto.
Mahimo nimong i-embed ang html sa serbisyo. Nasulayan na ba nimo kini?
Oo, sigurado. Pananglitan, ganahan ko sa mga graphic gikan sa gliffy.com. Apan aron makahimo mga pagbag-o, kinahanglan nimo nga moadto sa serbisyo sa ikatulo nga partido ug mag-edit didto. Ug mas lisud ang pagtugyan sa mga pagtul-id sa usa ka kauban.
Unsay akong buhaton?
Bag-ohay lang nakit-an nako ang usa ka repository sa Github sa mga rekomendasyon . Diagram isip code. Mga. atong gihulagway ang sirkito nga atong gikinahanglan sa js. Gisulat namon kini nga js direkta sa parehas nga html kung diin ang ubang teksto sa dokumentasyon.
Pinaagi sa dalan, gisulat ko ang dokumentasyon nga dili hingpit sa html. Kasagaran, ang dokumentasyon usa ka set sa mga file nga adunay markdown nga teksto, nga gibag-o sa usa ka hingpit nga site sa dokumentasyon sa pipila nga makina, pananglitan nga tigbuhat sa tingtugnaw. O usa ka sistema sa wiki.
Kini nahimo nga sayon ββββkaayo: gisulat namon ang teksto, dayon gibuksan ang tag sa script ug ang JS code sa laraw gihulagway niini.
Unsa na sab?
Ganahan ko niini nga repository, apan dili lang kini ang pananglitan diin ang usa ka diagram gidrowing gamit ang code o representasyon sa teksto. (Sa katapusan sa artikulo adunay mga link sa mga proyekto ug mga artikulo nga akong gi-Google sa diagram sa hilisgutan isip code.)
Ug dili lang ako ang nag-edit sa dokumentasyon. Usahay ang mga kauban usab nag-amot - pagkorihir sa usa ka pulong, pag-ilis sa usa ka paghulagway, pagsal-ot sa bag-ong mga litrato.
Busa, gusto nakong makita ang diagram sa usa ka mabasa, masabtan nga format sa teksto nga dili magkinahanglan og taas nga kurba sa pagkat-on. Ug sa pipila ka mga lugar mahimo nimong kopyahon-paste aron mapadali ang pagdugang usa ka bag-ong circuit.
Ug ang lain nga kauban nakamatikod nga ang code, siyempre, maayo, apan kung mogamit ka nga istruktura, ang tanan mahimong estrikto ug makapahayag.
Busa, gisulayan nako nga mahanduraw ang diagram isip usa ka set sa daghang gagmay nga mga arrays nga naghulagway sa mga node, koneksyon, mga grupo sa mga node, ingon man ang lokasyon sa mga node. Kini nahimo, sa akong mapainubsanon nga opinyon, medyo kombenyente, bisan pa, siyempre, ang lami ug kolor...
Giunsa kini nga tsart sa usa ka laray?
- Ang matag node gihulagway sa usa ka identifier nga talagsaon nga nagpaila sa node.
- Mahimo ka usab makadugang usa ka icon sa node ug makadugang usa ka inskripsiyon.
- Mahimo nimong itakda ang usa ka relasyon tali sa duha ka mga node.
- Alang sa komunikasyon sa diagram, mahimo nimong itakda ang kolor ug inskripsiyon.
- Ang direksyon sa komunikasyon gihubit nga gikan sa gigikanan hangtod sa target. Ug ang tinubdan ug target gipakita sa node identifiers.
- Ang usa o daghang mga node mahimong idugang sa usa ka grupo.
- Ang relasyon mahimo usab nga ipiho gikan sa grupo ug sa grupo.
Gamit kining yano nga mga lagda, atong makuha ang mosunod nga diagram. Lang? Medyo.
Ug kini gihulagway sa mosunod nga js code. Ang nag-unang butang dinhi mao ang mga elemento nga butang. Kung diin gipakita ang mga node - mga node, mga sulud - mga koneksyon.
const elements = {
nodes: [ // ΠΎΠΏΠΈΡΡΠ²Π°Π΅ΠΌ ΡΠ·Π»Ρ
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [ // ΡΠΊΠ°Π·ΡΠ²Π°Π΅ΠΌ ΡΠ²ΡΠ·ΠΈ
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
Siyempre, wala ako naghimo sa drowing sa sirkito sa akong kaugalingon, apan gigamit ang librarya kay usa ka gamhanan kaayo nga visualization tool. Gigamit ra nako ang usa ka tipik sa mga posibilidad sa akong solusyon.
Okay, kini usa ka yano nga pananglitan. Mahimo ba kini nga mas komplikado?
Oo palihug. Aron ipakita ang mga posisyon, gigamit namon ang mga posisyon, aron ipakita ang mga grupo, gipakita namon ang usa ka lista sa mga grupo sa mga grupo, ug ang mga elemento mismo adunay usa ka kinaiya sa grupo.
Ug kini ang code:
<div id="scheme5" style="height:500px;width:800px;"></div>
<script>
const elements5 = {
groups: [
{ id: 'g1', label: 'ΠΡΡΠΏΠΏΠ° ΡΠ΅ΡΠ²ΠΈΡΠΎΠ² 1'},
{ id: 'g2', label: 'ΠΡΡΠΏΠΏΠ° ΡΠ΅ΡΠ²ΠΈΡΠΎΠ² 2'},
],
nodes: [
{ id: 'man1', type: 'person', label: 'Π§Π΅Π»ΠΎΠ²Π΅ΠΊ'},
{ id: 'client', type: 'smartphone', label: 'Π‘ΠΌΠ°ΡΡΡΠΎΠ½'},
{ id: 'agent-backend', type: 'server', group: 'g1', label: 'agent-backend'},
{ id: 'web', type: 'server', group: 'g1', label: 'ΠΡΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠ΅ admin'},
{ id: 'www', type: 'server', group: 'g1', label: 'ΡΡΡΠ°Π½ΠΈΡΠ° Π·Π°Π³ΡΡΠ·ΠΊΠΈ'},
{ id: 'mongodb1', type: 'database', group: 'g1', label: 'Mongo DB 1'},
{ id: 'mongodb2', type: 'database', group: 'g1', label: 'Mongo DB 2'},
{ id: 'runner-integration1', type: 'worker', group: 'g1', label: 'ΠΎΡΠΏΡΠ°Π²ΠΊΠ°'},
{ id: 'runner-integration2', type: 'worker', group: 'g1', label: 'ΠΎΡΠΏΡΠ°Π²ΠΊΠ°'},
{ id: 'api', type: 'server', group: 'g1', label: 'API'},
{ id: 'server2', type: 'server', group:'g2', label: 'ΡΠ΅ΡΠ²Π΅Ρ'},
{ id: 'otherServer', type: 'server', group:'g2', label: 'ΡΠ΅ΡΠ²Π΅Ρ'},
{ id: 'firebase', type: 'cloud', label: 'Google Firebase'},
],
edges: [
{ source: 'client', target: 'agent-backend', label: 'json', color: 'red' },
{ source: 'agent-backend', target: 'mongodb1', color: 'red' },
{ source: 'agent-backend', target: 'mongodb2', color: 'red' },
{ source: 'mongodb1', target: 'runner-integration1', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'mongodb2', target: 'runner-integration2', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'mongodb1', target: 'web', label: 'Π΄Π°Π½Π½ΡΠ΅ Π΄Π»Ρ ΠΎΡΠΎΠ±ΡΠ°ΠΆΠ΅Π½ΠΈΡ' },
{ source: 'runner-integration1', target: 'server2', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'runner-integration2', target: 'otherServer', label: 'Π΄Π°Π½Π½ΡΠ΅' },
{ source: 'api', target: 'firebase', label: 'Π·Π°ΠΏΡΠΎΡΡ', color: 'blue', },
{ source: 'firebase', target: 'client', label: 'push', color: 'blue'},
{ source: 'server2', target: 'api', label: 'ΡΠ²Π΅Π΄ΠΎΠΌΠ»Π΅Π½ΠΈΡ', color: 'blue'},
{ source: 'man1', target: 'client', },
],
positions: [
{ id: 'client', row: 2, col: 1,},
{ id: 'agent-backend', row: 2, col: 3,},
{ id: 'web', row: 6, col: 3,},
{ id: 'www', row: 1, col: 3,},
{ id: 'mongodb1', row: 1, col: 4,},
{ id: 'mongodb2', row: 2, col: 5,},
{ id: 'runner-integration1', row: 3, col: 3,},
{ id: 'runner-integration2', row: 4, col: 3,},
{ id: 'api', row: 5, col: 3,},
{ id: 'server2', row: 6, col: 7,},
{ id: 'otherServer', row: 4, col: 7,},
{ id: 'firebase', row: 5, col: 1,},
{ id: 'logger', row: 2, col: 7,},
{ id: 'crm', row: 5, col: 8,},
],
};
Diagram('scheme5', elements5, {layout: 'grid'});
</script>
Sa usa ka bahin, ang ingon nga laraw hapit usa ka pares nga mga screen sa code sa usa ka laptop, sa laing bahin, ang istruktura nga a la json nagtugot kanimo nga pun-on ang tanan nga datos pinaagi sa analogy, dali ug mahimo nimong kopyahon-i-paste.
Ngano nga ang mga posisyon gibutang nga lahi sa mga node?
Kini mas komportable. Una atong gipiho ang mga node. Dayon mahimo natong ipiho ang usa ka magtiayon nga mga grupo ug ipaila kini sa mga node. Dayon atong itudlo ang mga koneksyon. Ug unya, kung ang mga nag-unang mga butang ug mga koneksyon sa taliwala nila naa, gikuha namon ang lokasyon sa kini nga mga butang sa diagram. O vice versa.
Posible ba nga walay mga posisyon?
Kini mahimo nga walay mga posisyon. Apan kini mahimong gamay nga kulubot; makita nimo kini nga kapilian sa mga pananglitan. Kini tungod sa kamatuoran nga adunay usa ka algorithm alang sa lokasyon sa mga node alang sa cytoscape , nga gikonsiderar usab ang presensya sa mga grupo. Ang pagtino sa mga posisyon naghimo sa diagram nga mas kontrolado, apan sa yugto sa unang draft sa diagram posible nga walay mga posisyon.
Ang mga posisyon mahimo usab nga ipiho sa istilo sa Battleship. Mga. ang usa ka node nahimutang sa a1, ug ang lain sa d5. Kini ilabinang makatabang nga ang cytoscape makahimo sa mga butang sa canvas nga mapalihok, i.e. mahimo namong ibalhin sila, tan-awa ang lainlaing mga kapilian sa layout, ug dayon ayohon ang kahikayan sa mga elemento nga gusto namon sa code.
Sa kinatibuk-an, kini masabtan. Mahimo usab nimo sulayan?
Siyempre, aron dali nga makahimo og mga sirkito, gihimo nako ang akong kaugalingon nga gamay , nga nag-update mismo sa schema ug nagtipig sa pinakabag-o nga bersyon sa browser (sa localStorage).
Nasulayan na ba nimo kini? Mahimo nimong idugang kini sa imong panid.
Unya pag-usab:
1. Pagkonektar sa script
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. Idugang ang code sa html
<div id="scheme1" style="height:300px;width:800px;"></div>
<script>
const elements = {
nodes: [
{ id: 'client', type: 'smartphone', label: 'Mobile App'},
{ id: 'server', type: 'server', label: 'Main Server'},
{ id: 'db1', type: 'database', label: 'DB 1'},
{ id: 'db2', type: 'database', label: 'DB 2'},
],
edges: [
{ source: 'client', target: 'server', label: 'request' },
{ source: 'server', target: 'db1', label: 'request' },
{ source: 'server', target: 'db2', label: 'request' },
],
};
Diagram('scheme1', elements);
</script>
3. gi-edit namo ang code sa diagram nga among gikinahanglan (sa akong hunahuna mas sayon ββkay sa pagdrowing og bukaw :)
Dugang detalye sa sa github.
Unsa man ang sa katapusan?
Nakab-ot nako ang akong mga katuyoan - aron idugang ang mga inline nga diagram sa dokumentasyon, ang format yano ug masabtan. Dili kini angay alang sa mga super circuit, apan alang sa gagmay nga mga sirkito nga nagpatin-aw sa istruktura sa mga koneksyon, kini hingpit nga maayo. Kanunay ka nga dali nga mag-tweak ug magbag-o sa usa ka butang sa paglabay sa panahon. Oo, ug ang mga kauban mahimong magtul-id sa usa ka butang sa pantalan sa ilang kaugalingon, labing menos mga kapsyon alang sa mga butang, nga walaβy espesyal nga pagbansay))
Unsa ang mapauswag?
Adunay, siyempre, daghang mga kapilian dinhi. Pagdugang og dugang nga mga icon (ang tanan nga anaa gidugang inline sa script). Pagpili og mas makapahayag nga hugpong sa mga icon. Himoa nga posible nga ipiho ang estilo sa linya sa koneksyon. Pagdugang og hulagway sa background.
Unsa sa imong hunahuna?
Naa na koy daghang mga ideya alang sa pagpatuman sa mga isyu, mahimo usab nimo idugang ang imo sa mga komento.
Ang akong solusyon siguradong magamit sa usa ka pig-ot nga lainlain nga mga problema, ug tingali makit-an nimo ang usa ka labi ka kombenyente nga himan alang sa pagdrowing og mga diagram pinaagi lamang sa pag-coding niini - ingon nga giingon nila 'ipakita kanako ang imong diagram ingon code'
- (9 nga matang sa mga tsart sa online editor)
- Ug kung gusto nimo ang labi ka detalyado ug komplikado nga mga diagram, nan siguradong makadayeg ka niini nga proyekto:
Source: www.habr.com