Соңғы екі жылда мен құжаттамамен көбірек айналыстым. Осы немесе басқа жүйенің қалай жұмыс істейтіні туралы түсіндірме мәтінді жазу, әдетте, өте қарапайым. Барлық негізгі нысандарды және осы нысандар арасындағы байланыстарды көрсететін диаграмманы салу да өте оңай.
Бірақ ең проблемалы аспект - бұл құжаттаманы жаңартып отыру. Ал мәтін жақсы болар еді, бірақ диаграммалар... Өйткені... барлық құжаттама онлайн, яғни. html пішімінде, содан кейін мәтін диаграммаларды нақты көрсететін gif/jpeg/png суреттерімен бірге жүреді. Диаграммалар Visio немесе a la draw.io онлайн қызметтері сияқты әртүрлі бағдарламаларда сызылады. Содан кейін диаграмманы графикалық пішімге экспорттайсыз және оны html файлына тіркейсіз. Бәрі оңай.
Мәселе неде?
Схемалар әдетте қарапайым. Дәлірек айтқанда, аса күрделі емес. Иә, нысандардың саны ондаған немесе екі, қосылымдар саны шамамен бірдей. Плюс қолдар, кейбір белгілер. Қарапайым схемаларды сөзбен сипаттауға болады, бірақ тым күрделі, әхем... (c) «олар түсінбейді, сэр». Көптеген схемалар бар, оларға мезгіл-мезгіл, эпизодтық өзгерістер енгізу қажет, яғни. үнемі, өйткені олар біздің өнімдеріміздің дамуын бақылайды.
Қызметтің html-ін ендіруге болады. Сіз оны қолданып көрдіңіз бе?
Иә, әрине. Мысалы, маған glify.com сайтындағы графика ұнайды. Бірақ өзгертулер енгізу үшін үшінші тарап қызметіне өтіп, сол жерде өңдеу керек. Әріптеске түзетулерді тапсыру қиынырақ.
Не істеу?
Жақында мен ұсыныстарда Github репозиторийін кездестірдім . Диаграмма код ретінде. Анау. js-де бізге қажет схеманы сипаттаймыз. Біз бұл JS файлын басқа құжаттама мәтіні орналасқан html-де тікелей жазамыз.
Айтпақшы, мен құжаттаманы толығымен html-де жазбаймын. Әдетте, құжаттама - бұл төмендетілген мәтіні бар файлдар жиынтығы, кейін оны кейбір қозғалтқыш толыққанды құжаттама сайтына түрлендіреді, мысалы, wintersmith. Немесе вики жүйесі.
Бұл өте ыңғайлы болып шықты: біз мәтінді жаздық, содан кейін сценарий тегі ашылады және онда схеманың JS коды сипатталады.
Тағы не болды?
Маған бұл репозиторий ұнады, бірақ бұл диаграмма кодты немесе мәтінді көрсету арқылы сызылатын жалғыз мысал емес. (Мақаланың соңында мен код ретінде тақырып диаграммасында Google іздеген жобалар мен мақалаларға сілтемелер болады.)
Мен құжаттаманы өңдейтін жалғыз адам емеспін. Кейде әріптестер де үлес қосады - сөзді түзетеді, сипаттаманы өзгертеді, жаңа суреттерді енгізеді.
Сондықтан мен диаграмманы ұзақ оқу қисығын қажет етпейтін оқылатын, түсінікті мәтін пішімінде көргім келеді. Ал кейбір жерлерде жаңа тізбекті қосуды жылдамдату үшін жай ғана көшіріп қоюға болады.
Тағы бір әріптес код, әрине, жақсы екенін атап өтті, бірақ егер сіз құрылымды қолдансаңыз, бәрі өте қатал және мәнерлі болуы мүмкін.
Сондықтан мен диаграмманы түйіндерді, қосылымдарды, түйіндер топтарын, сондай-ақ түйіндердің орналасуын сипаттайтын бірнеше шағын массивтердің жиынтығы ретінде елестетуге тырыстым. Менің ойымша, бұл өте ыңғайлы болды, бірақ, әрине, дәмі мен түсі...
Бұл массивтегі диаграмма қалай?
- Әрбір түйін түйінді бірегей түрде анықтайтын идентификатор арқылы сипатталады.
- Сондай-ақ түйінге белгішені қосып, жазуды қосуға болады.
- Екі түйін арасындағы қатынасты көрсетуге болады.
- Диаграммадағы байланыс үшін түс пен жазуды орнатуға болады.
- Байланыс бағыты көзден мақсатқа қарай анықталады. Ал көз мен мақсат түйін идентификаторлары арқылы көрсетіледі.
- Бір немесе бірнеше түйіндерді топқа қосуға болады.
- Қарым-қатынасты топтан да, топқа да көрсетуге болады.
Осы қарапайым ережелерді қолдана отырып, біз келесі диаграмманы аламыз. Жай? Өте.
Және ол келесі JS коды арқылы сипатталады. Мұнда ең бастысы - элементтер объектісі. Қандай түйіндер көрсетілген - түйіндер, жиектер - қосылыстар.
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);
Әрине, мен схеманың сызбасын өзім ойлап таппадым, бірақ кітапхананы пайдаландым өте қуатты визуализация құралы болып табылады. Мен шешімімде мүмкіндіктердің бір бөлігін ғана қолданамын.
Жарайды, бұл қарапайым мысал. Бұл күрделірек болуы мүмкін бе?
Иә өтінемін. Позицияларды көрсету үшін біз позицияларды қолданамыз, топтарды көрсету үшін топтардағы топтардың тізімін көрсетеміз және элементтердің өздері топтық атрибутқа ие.
Және бұл код:
<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>
Бір жағынан, мұндай схема ноутбуктағы кодтың екі экраны дерлік болса, екінші жағынан, a la json құрылымы барлық деректерді ұқсастық бойынша, жылдам толтыруға мүмкіндік береді және көшіру-қоюға болады.
Неліктен позициялар түйіндерден бөлек орналастырылған?
Бұл ыңғайлырақ. Алдымен біз түйіндерді анықтаймыз. Содан кейін біз бірнеше топты анықтап, оларды түйіндерде көрсете аламыз. Содан кейін біз қосылымдарды белгілейміз. Содан кейін ғана, негізгі объектілер мен олардың арасындағы байланыстар болған кезде, біз диаграммада осы объектілердің орналасуын қабылдаймыз. Немесе керісінше.
Лауазымдарсыз мүмкін бе?
Бұл позицияларсыз мүмкін. Бірақ ол аздап мыжылған болады, сіз бұл опцияны мысалдардан көре аласыз. Бұл цитоскапқа арналған түйіндердің орналасу алгоритмінің болуына байланысты , бұл да топтардың болуын ескереді. Орындарды көрсету диаграмманы басқарылатын етеді, бірақ диаграмманың бірінші жобасының сатысында позицияларсыз мүмкін болады.
Позицияларды жауынгерлік кеме стилінде де көрсетуге болады. Анау. бір түйін a1-де, ал екіншісі d5-те орналасқан. Бұл әсіресе цитоскаптың кенептегі нысандарды жылжымалы етуіне көмектеседі, яғни. біз оларды жылжыта аламыз, әртүрлі орналасу опцияларын көре аламыз, содан кейін кодта бізге ұнайтын элементтердің орналасуын түзете аламыз.
Жалпы, бұл түсінікті. Көруге болады?
Әрине, схемаларды тез жасау үшін мен өзімді кішкентай жасадым , ол өзі схеманы жаңартады және браузерде соңғы нұсқаны сақтайды (localStorage ішінде).
Сіз оны қолданып көрдіңіз бе? Енді сіз оны өз бетіңізге қоса аласыз.
Сосын тағы:
1. Скриптті қосу
<script src="https://unpkg.com/@antirek/[email protected]/dist/code-full.min.js"></script>
2. 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. біз кодты қажетті диаграммаға өңдейміз (менің ойымша, бұл үкі салудан оңай :)
Толығырақ мына жерден github сайтында.
Ақырында не?
Мен өз мақсаттарыма жеттім - құжаттамаға кірістірілген диаграммаларды қосу, формат өте қарапайым және түсінікті. Бұл супер схемалар үшін жарамайды, бірақ қосылымдардың құрылымын түсіндіретін шағын тізбектер үшін бұл өте жақсы. Сіз әрқашан бір нәрсені тез реттей аласыз және уақыт өте келе өзгерте аласыз. Иә, және әріптестер доктағы бірдеңені өздері түзете алады, кем дегенде нысандарға арналған жазулар, арнайы дайындықсыз))
Нені жақсартуға болады?
Мұнда, әрине, көптеген нұсқалар бар. Қосымша белгішелерді қосыңыз (барлық барлар сценарийге кірістірілген қосылады). Белгішелердің неғұрлым мәнерлі жинағын таңдаңыз. Қосылу сызығының стилін көрсетуге мүмкіндік беріңіз. Фондық суретті қосыңыз.
Сен не ойлайсың?
Мәселелерді іске асыру үшін менде бірнеше идеялар бар, сіз өз ойыңызды түсініктемелерде қоса аласыз.
Менің шешімім есептердің тар ауқымында міндетті түрде қолданылады, мүмкін сіз оларды жай кодтау арқылы диаграммаларды салудың ыңғайлы құралын таба аласыз - олар «диаграммаңызды код ретінде көрсетіңіз» дейді.
- (диаграммалардың 9 түрі онлайн редакторы)
- Егер сізге өте егжей-тегжейлі және күрделі диаграммалар ұнаса, онда сіз бұл жобаға таң қаласыз:
Ақпарат көзі: www.habr.com