Прымітывы UI — Палявы даведнік
Калі вы калі-небудзь глядзелі на сучасную праграму і думалі: «а як называецца гэта штука?» — гэтая старонка для вас.
Кожны інтэрфейс, якім вы карыстаецеся, пабудаваны з напдзіва невялікага набору шматразовых будаўнічых блокаў, якія называюцца прымітывамі UI. Яны маюць назвы. Часам дзіўныя. Але варта ўбачыць метафару — і вы больш не зможаце яе «развідзець».
En Parlant~ выкарыстоўвае Mantine, бібліятэку кампанентаў React, якая прадастаўляе ўсё гэта з скрынкі. Вось ваш палявы даведнік.
Тыя, якія гучаць як мэбля
Section titled “Тыя, якія гучаць як мэбля”Toast (тост) — гэта маленькае апавяшчэнне, якое выскоквае з краю экрана, вісіць некалькі секунд, а потым знікае. Як кавалак хлеба, які выскоквае з тостара — толькі гравітацыя працуе наадварот, і ён у рэшце рэшт вяртаецца назад.
У En Parlant~ тосты з’яўляюцца ў правым ніжнім куце (праз Mantine @mantine/notifications) для такіх рэчаў, як:
- «База даных паспяхова загружана» — поп
- «Голас TTS не наладжаны» — поп
- «Не ўдалося падключыцца да Lichess» — поп, і вам крыху сумна
Вы іх не прасілі. Яны проста з’яўляюцца, дастаўляюць сваё паведамленне і знікаюць. Яны — паштовыя галубы свету UI.
Card (картка) — гэта прамавугольны кантэйнер з рамкай або ценем, які групуе звязаны кантэнт разам. Уявіце картатэчную картку на стале — у яе ёсць выразны край, яна змяшчае адну рэч, і вы можаце яе ўзяць і перасунуць.
У En Parlant~ вы ўбачыце карткі для:
- Прэв’ю партый у аглядальніку баз даных (
GameCard) — імёны гульцоў, вынік, дата - Рэдактар пазіцыі на дошцы (
EditingCard) — картка, якую вы пераварочваеце пры наладцы ўласнай пазіцыі - Запісы баз даных на старонцы баз — кожная база атрымлівае ўласную картку ў сетцы
У картак ёсць блізкі сваяк — Paper, які, па сутнасці, з’яўляецца карткай, якая скончыла мастацкую школу. Тая ж ідэя — кантэйнер з рамкай або ценем — але з меншым семантычным сэнсам. Paper проста кажа: «Я — паверхня.» Ён з’яўляецца як фон за панэлямі аналізу і адлюстраваннямі інфармацыі пра базы даных.
Drawer / Sheet
Section titled “Drawer / Sheet”Зараз не выкарыстоўваецца ў En Parlant~, але варта ведаць: drawer (шуфлядка) — гэта панэль, якая выязджае з краю экрана, як шуфлядка стала. (Вось і ўсё. Уся метафара. Дызайнеры UI у той дзень былі вельмі літаральныя.)
Тыя, якія перагароджваюць шлях
Section titled “Тыя, якія перагароджваюць шлях”Modal (мадальнае вакно) — гэта ўсплывальны дыялог, які патрабуе вашай увагі. Ён зацямняе фон і прымушае вас разабрацца з ім, перш чым рабіць што-небудзь іншае. Гэта малое дзіця сярод патэрнаў UI — «ГЛЯДЗІ НА МЯНЕ ЗАРАЗ ЖА.»
En Parlant~ выкарыстоўвае мадальныя вокны для момантаў, якія сапраўды патрабуюць вашай увагі:
- «Вы ўпэўнены, што хочаце ачысціць усе даныя?» (
ClearDataModal) — з чэкбоксамі, каб вы маглі выбраць, якія даныя знішчыць - «Даступна абнаўленне» (
UpdateModal) — з індыкатарам прагрэсу падчас спампоўкі - «Імпартаваць партыю» (
ImportModal) — устаўце PGN, увядзіце FEN або скіньце спасылку - «Стварыць новы рэпертуар» (
CreateRepertoireModal) — назавіце, наладзьце, пачніце - «Пра En Parlant~» (
About) — інфармацыя аб версіі, тытры, звычайны заглядальны білет
Мадальныя вокны кажуць: «Гэта размова. Мы яе вядзём зараз.»
Dialog
Section titled “Dialog”Dialog (дыялог) — гэта ветлівы сваяк мадальнага вакна. У Mantine яны, па сутнасці, адзін і той жа кампанент, але ў тэорыі дызайну UI дыялог меншы і больш сфакусаваны — адно пытанне і адказ. «Захаваць змены?» Так / Не. Гатова.
En Parlant~ выкарыстоўвае ConfirmModal для такіх хуткіх момантаў «так ці не», напрыклад, для пацверджання, што вы хочаце адкінуць незахаваныя змены.
Тыя, якія прыходзяць і сыходзяць
Section titled “Тыя, якія прыходзяць і сыходзяць”Tooltip
Section titled “Tooltip”Tooltip (падказка) — гэта маленькі надпіс, які з’яўляецца, калі вы наводзіце курсор на нешта. Гэта дапаможны незнаёмец, які шэпча адказ, калі вы выглядаеце збянтэжаным.
Падказкі — усюды ў En Parlant~. Навядзіце курсор амаль на любую кнопку з іконкай і атрымаеце адну:
- Навядзіце на кнопку ↻ → «Перазагрузіць»
- Навядзіце на скарочаны шлях да файла → з’яўляецца поўны шлях
- Навядзіце на сімвал анатацыі → што гэты сімвал азначае
- Навядзіце на ход у панэлі аналізу → з’яўляецца мініяцюрны прэв’ю дошкі
Падказкі — гэта арыгінальнае «інструкцыя не патрэбна».
Popover
Section titled “Popover”Popover (усплывальнае вакно) — гэта падказка, якая скончыла аспірантуру. Замест простага тэкставага надпісу яно можа змяшчаць што заўгодна — кнопкі, выявы, нават маленькую шахматную дошку.
У En Parlant~, калі вы наводзіце курсор на ход у аналізе рухавічка, усплывальнае вакно паказвае прэв’ю дошкі ў гэтай пазіцыі. Гэта падказка, але з наглядным матэрыялам.
Menu (меню) — гэта спіс дзеянняў, які з’яўляецца, калі вы націскаеце (або правай кнопкай) на нешта. Вы карыстаецеся імі з пачатку камп’ютарнай эры — File, Edit, View. Вы ведаеце парадак.
En Parlant~ мае два варыянты:
- Меню верхняй панэлі — класічная панэль меню File / Edit / View, пабудаваная з дапамогай Mantine
Menu. Спалучэнні клавіш пералічаны справа. Патэрн дызайну настолькі стары, што ўжо на пенсіі. - Кантэкстныя меню — пстрыкніце правай кнопкай мышы на ходзе ў дрэве партыі і атрымаеце опцыі кшталту Прасунуць варыянт, Выдаліць адсюль і Капіяваць лінію. Яны выкарыстоўваюць бібліятэку
mantine-contextmenuдля дадатковага лоску.
Меню маюць уласны падслоўнік: Menu.Target (рэч, на якую вы націскаеце), Menu.Dropdown (спіс, які з’яўляецца), Menu.Item (кожная опцыя) і Menu.Divider (тонкая лінія, якая кажа «цяпер іншы раздзел»).
Тыя, якія арганізуюць прастору
Section titled “Тыя, якія арганізуюць прастору”Stack & Group
Section titled “Stack & Group”Гэта масла і хлеб кампаноўкі.
- Stack размяшчае рэчы вертыкальна — адна над адной. Як стос кніг.
- Group размяшчае рэчы гарызантальна — побач. Як шахматныя фігуры, выстаўленыя ў рад на паліцы.
Яны з’яўляюцца літаральна ў 100+ файлах кожны. Гэта самыя распаўсюджаныя кампаненты ва ўсёй праграме. Кожны раз, калі рэчы акуратна размешчаны, за гэта адказвае Stack або Group.
Flex — гэта швейцарскі армейскі нож, сваяк Stack і Group. Калі рэчам трэба пераносіцца, расцягвацца, сціскацца, мяняць парадак або іншым чынам «бунтаваць», Flex бярэ кіраванне з поўным кантролем над мадэллю CSS Flexbox.
Выкарыстоўваецца ў спісе хадоў панэлі аналізу — тыя паслядоўнасці хадоў, якія пераносяцца і цякуць як тэкст? Гэта Flex цягне на сабе ўсю працу.
Box — гэта <div> у цыліндры. Сам па сабе ён нічога не робіць — гэта проста агульны кантэйнер. Але ён прымае стылявыя уласцівасці Mantine, што робіць яго неверагодна зручнай абгорткай для «мне трэба штосьці вакол гэтай іншай рэчы».
Box з’яўляецца ў 150+ файлах. Гэта ізаляцыйная стужка бібліятэкі кампанентаў.
Center
Section titled “Center”Робіць менавіта тое, што кажа. Ставіць нешта ў цэнтр. Гарызантальна. Вертыкальна. Абодва. Гатова.
З’яўляецца ў пустых станах — калі не падключаны ўліковыя запісы, не загружаны базы даных, яшчэ няма даных. Вялікая іконка, паведамленне і Center, які сочыць за ідэальным пазіцыянаваннем. Нікому не падабаецца зрушаны з цэнтра пусты стан.
SimpleGrid
Section titled “SimpleGrid”Сетка, якая простая. Вы паведамляеце ёй колькасць слупкоў, і яна размяшчае вашы карткі ў акуратнай сетцы, якая перабудоўваецца пры змене памеру вакна. Старонка баз даных выкарыстоўвае яе для размяшчэння картак баз у адаптыўнай сетцы.
ScrollArea
Section titled “ScrollArea”Кантэйнер, які пракручваецца, калі яго змесціва перапаўняецца. Здавалася б, гэта павінна быць бясплатна — і ў пэўным сэнсе так, з CSS overflow: auto — але ScrollArea дадае стылізаваныя палосы пракруткі, інерцыйную пракрутку і выяўленне перапаўнення. Ён абгортвае панэль дрэва партыі, лініі аналізу і ўсюды, дзе змесціва можа стаць вышэйшым за свой кантэйнер.
AppShell
Section titled “AppShell”AppShell — гэта галоўная кампаноўка — шкілет усёй праграмы. Ён вызначае, дзе знаходзіцца загалоўнік, дзе — бакавая панэль, і дзе жыве асноўны кантэнт. Усё астатняе ўкладзена ўнутры яго.
Вы выкарыстоўваеце яго толькі адзін раз. Гэта фундамент дома.
Portal
Section titled “Portal”Portal — гэта магічны чарвячны тунэль. Ён рэндэрыць кампанент па-за яго нармальнай пазіцыяй у дрэве DOM і размяшчае яго ў іншым месцы — звычайна ў корані дакумента. Вось як усплывальныя вокны і прэв’ю дошкі пазбягаюць абразання бацькоўскімі кантэйнерамі з overflow: hidden.
Вы ніколі не бачыце Portal. Вы бачыце толькі яго эфекты. Гэта закулісная каманда UI-кампанентаў.
Тыя, з якімі вы ўзаемадзейнічаеце
Section titled “Тыя, з якімі вы ўзаемадзейнічаеце”Button
Section titled “Button”Прамавугольнік з тэкстам, на які можна націснуць. Вы яго ведаеце. У Mantine кнопкі бываюць розных варыянтаў:
- filled — суцэльны колер, высокая выразнасць. «Націсні мяне, я важная.»
- outline — толькі рамка. «Я варыянт, але без ціску.»
- subtle — ледзь бачная. «Я тут, калі спатрэблюся.»
- default — нейтральная залатая сярэдзіна.
En Parlant~ выкарыстоўвае ўсе гэтыя варыянты ў 150+ файлах. Самы распаўсюджаны патэрн: Group кнопак у ніжняй частцы мадальнага вакна — «Скасаваць» (subtle) і «Пацвердзіць» (filled). Класіка.
ActionIcon
Section titled “ActionIcon”ActionIcon — гэта кнопка, якая адмовілася ад тэкставай пазнакі і цалкам прысвяціла сябе стылю жыцця з іконкамі. Яна кампактная, квадратная і абапіраецца на сваю іконку (плюс падказка), каб данесці сваё прызначэнне.
Кнопкі панэлі інструментаў, элементы кіравання панэлямі, кнопкі закрыцця — усё гэта ActionIcons. Гэта найбольш эканомны па прасторы спосаб прапанаваць дзеянне.
Switch
Section titled “Switch”Switch (пераключальнік) — гэта тоглер, які выглядае як маленькі выключальнік святла. Шчоўкніце налева, шчоўкніце направа. Уключана. Выключана.
У наладах пераключальнікі кіруюць бінарнымі выбарамі:
- Гук уключаны/выключаны
- Агучванне TTS уключана/выключана
- Цёмная тэма / светлая тэма
Фізічная метафара настолькі ўдалая, што нават вашы бабулі і дзядулі яе разумеюць.
Slider
Section titled “Slider”Slider (паўзунок) — гэта дарожка з ручкай, якую вы цягнеце туды-сюды для выбару значэння. Як рэгулятар гучнасці, які сплюшчылі.
En Parlant~ выкарыстоўвае паўзункі для:
- Памер шрыфта — цягніце для налады
- Гучнасць — цягніце для налады (вядома ж)
- Ядра CPU — колькі ядраў павінен выкарыстоўваць рухавічок?
- Хэш-памяць — колькі аператыўнай памяці для хэш-табліцы рухавічка?
Ёсць таксама RangeSlider з дзвюма ручкамі для выбару дыяпазону — выкарыстоўваецца для фільтрацыі партый па рэйтынгу Elo (напрыклад, 2000–2200) і часавых перыядаў.
SegmentedControl
Section titled “SegmentedControl”Рад кнопак, дзе роўна адна выбрана ў адзін момант часу. Гэта як прэсеты аўтамабільнага радыё — націсніце адну, астатнія выскокваюць.
Выкарыстоўваецца для пераключэння паміж:
- Ацэнкай у сантыпешках і працэнтамі перамога/нічыя/параза на графіку аналізу
- Рознымі фарматамі натацыі хадоў
- Колькасцю ліній рухавічка
Checkbox & Select
Section titled “Checkbox & Select”Вы іх ведаеце. Чэкбоксы для «выберыце ўсе, што падыходзяць», выпадальныя спісы Select для «выберыце адзін з гэтага спісу». Яны з’яўляюцца ў наладах, фільтрах і формах па ўсёй праграме. Мадальнае вакно ачысткі даных мае асабліва задавальняючы набор чэкбоксаў, дзе вы можаце выбраць свой уласны шлях знішчэння.
Autocomplete
Section titled “Autocomplete”Тэкставае поле ўводу, якое прапаноўвае завяршэнні па меры набору. Пошук гульца ў аглядальніку баз даных выкарыстоўвае гэта — пачніце ўводзіць імя, і адпаведныя гульцы з’яўляюцца ніжэй.
FileInput & DateInput
Section titled “FileInput & DateInput”FileInput адкрывае выбар файла пры націску — выкарыстоўваецца ў мадальным вакне імпарту для загрузкі файлаў PGN. DateInput адкрывае каляндар для выбару даты — выкарыстоўваецца для фільтрацыі партый па даце. Ёсць таксама MonthPickerInput і YearPickerInput для выпадкаў, калі патрэбна менш дакладнасці (фільтрацыя базы Lichess па месяцы, фільтрацыя базы майстроў па годзе).
Тыя, якія паказваюць прагрэс
Section titled “Тыя, якія паказваюць прагрэс”Progress Bar
Section titled “Progress Bar”Гарызантальная паласа, якая запаўняецца злева направа, каб паказаць, наколькі нешта прасунулася. Выкарыстоўваецца падчас абнаўленняў праграмы (прагрэс спампоўкі) і — больш крэатыўна — для паказу імавернасцей перамогі/нічыі/паразы ў панэлі аналізу. Тры каляровыя секцыі (белая, шэрая, чорная) запаўняюць паласу прапарцыянальна. Гэта маленькая слупковая дыяграма, замаскіраваная пад індыкатар прагрэсу.
Loader
Section titled “Loader”Loader (загрузнік) — гэта круцячаяся анімацыя, якая кажа: «Я працую над гэтым, дайце секунду.» З’яўляецца падчас загрузкі баз даных, атрымання статыстыкі гульцоў або любых асінхронных аперацый.
Skeleton
Section titled “Skeleton”Skeleton (шкілет) — гэта шэрая запаўняльнік, які імітуе форму кантэнту, які яшчэ не загрузіўся. Замест пустога экрана або спінера вы бачыце прывідныя контуры таго, дзе будуць карткі і тэкст. Гэта архітэктурны план стану загрузкі — «сапраўдная мэбля ўжо ў дарозе».
Старонка баз даных выкарыстоўвае шкілеты падчас загрузкі сеткі картак. Значна элегантней, чым адзін спінер.
LoadingOverlay
Section titled “LoadingOverlay”Паўпразрыстае пакрывала, накінутае на кампанент падчас яго загрузкі. Графік аналізу выкарыстоўвае гэта — вы ўсё яшчэ бачыце графік за накладкай, але ён зацемнены, і зверху ёсць спінер. «Я ўсё яшчэ тут, проста абнаўляюся.»
Тыя, якія пазначаюць рэчы
Section titled “Тыя, якія пазначаюць рэчы”Badge (значок) — гэта маленькі каляровы ярлык — як бейджык на канферэнцыі. У En Parlant~ кампанент SpeedBadge выкарыстоўвае значкі для адлюстравання часавых кантроляў з каляровай кадыроўкай:
- 🩷 Ружовы — UltraBullet
- 🔴 Чырвоны — Bullet
- 🟠 Аранжавы — Blitz
- 🟢 Зялёны — Rapid
- 🔵 Сіні — Classical
- 🟣 Фіялетавы — Correspondence
Кожны значок маленькі, каляровы і імгненна паведамляе хуткасць гульні з першага погляду.
Скарачэнне ад keyboard (клавіятура). Адлюстроўвае клавішу клавіятуры з характэрным стылем выпуклай клавішы. Выкарыстоўваецца ў наладах клавіятурных скарачэнняў для паказу такіх рэчаў, як Ctrl + Z. Гэта CSS-рэканструкцыя сапраўднай фізічнай клавішы на вашай клавіятуры. Цудоўна скеўяморфна.
Тыя, якія раздзяляюць і згортваюць
Section titled “Тыя, якія раздзяляюць і згортваюць”Divider
Section titled “Divider”Гарызантальная лінія, якая раздзяляе раздзелы. Вось і ўсё. Гэта лінія. Але гэта стылізаваная лінія, і яна можа мець тэкставы надпіс пасярэдзіне — як раздзяляльнік «— АБО —» у мадальным вакне імпарту, які аддзяляе «устаўце PGN» ад «увядзіце FEN».
Больш за трыццаць файлаў выкарыстоўваюць Divider. Аказваецца, рэчы трэба раздзяляць даволі часта.
Collapse
Section titled “Collapse”Collapse (згортванне) — гэта раздзел, які разгортваецца і згортваецца з плыўнай анімацыяй. Націсніце, каб паказаць, націсніце, каб схаваць. Параметры фільтрацыі базы даных выкарыстоўваюць гэта — вам не заўсёды трэба бачыць кожны фільтр, таму яны хаваюцца за Collapse, пакуль вы іх не захочаце.
Прасунутыя прымітывы
Section titled “Прасунутыя прымітывы”RichTextEditor
Section titled “RichTextEditor”Паўнавартасны тэкставы рэдактар «тое-што-бачыш-тое-і-атрымліваеш», пабудаваны на TipTap. Тоўсты шрыфт, курсіў, спісы — усё як мае быць. Выкарыстоўваецца для напісання анатацый да партый — тых каментарыяў, якія вы дадаеце, каб растлумачыць, чаму ход быў бліскучым або жахлівым.
Гэта адзіны прымітыў, які больш складаны арганізм, чым адзінкавая клетка. Пад капотам гэта TipTap + ProseMirror + стылізацыя Mantine. Але з пункту гледжання карыстальніка — гэта проста тэкставае поле, дзе фарматаванне працуе.
AreaChart
Section titled “AreaChart”З @mantine/charts (які абгортвае Recharts), AreaChart забяспечвае працу графіка ацэнкі — той хвалевай формы, якая ідзе ўздоўж ніжняй часткі панэлі аналізу. Белая вобласць над сярэдняй лініяй азначае, што белыя выйграюць; чорная ніжэй — што чорныя.
Вы можаце націснуць на любую кропку графіка, каб перайсці да гэтага хода. Інтэрактыўная візуалізацыя даных сустракаецца з шахматным аналізам. Ён нават мае ўласныя падказкі і апорныя лініі, якія пазначаюць фазы гульні (дэбют → мітэльшпіль → эндшпіль).
DataTable
Section titled “DataTable”Праз бібліятэку mantine-datatable — паўнафункцыянальная табліца даных з сартаваннем, пагінацыяй, вылучэннем радкоў і фільтрацыяй. Забяспечвае працу спісу партый, спісу гульцоў і спісу турніраў у аглядальніку баз даных. Гэта электронная табліца, якая ведае, што яна ў шахматнай праграме.
Нябачныя прымітывы
Section titled “Нябачныя прымітывы”Некаторыя прымітывы не адлюстроўваюць нічога бачнага самі па сабе, але забяспечваюць працу ўсяго астатняга:
- MantineProvider — абгортвае ўсю праграму і прадастаўляе тэму (колеры, цёмны рэжым, налады кампанентаў па змаўчанні)
- Portal — тэлепартуе адрэндэраны кантэнт у іншую частку DOM
- useHotkeys — хук (не кампанент), які падключае клавіятурныя скарачэнні
- useForm — кіруе станам формы, валідацыяй і апрацоўкай памылак
- useDebouncedValue — чакае, пакуль вы спыніце набіраць, перш чым запусціць пошук. Ветлівы хук.
Поўны інвентар
Section titled “Поўны інвентар”Для даведкі, вось кожнае сямейства прымітываў, якое выкарыстоўваецца ў En Parlant~, згрупаванае па прызначэнні:
| Катэгорыя | Прымітывы |
|---|---|
| Кампаноўка | AppShell, Box, Center, Flex, Group, Stack, SimpleGrid, ScrollArea, Portal |
| Паверхні | Card, Paper |
| Накладкі | Modal, Tooltip, Popover, Menu, ContextMenu, LoadingOverlay |
| Апавяшчэнні | Toast (праз @mantine/notifications) |
| Кнопкі | Button, ActionIcon, CloseButton, ThemeIcon |
| Уводы | TextInput, Textarea, NumberInput, Select, Autocomplete, Checkbox, Switch, Slider, RangeSlider, SegmentedControl, FileInput, DateInput, MonthPickerInput, YearPickerInput |
| Адлюстраванне даных | Table, DataTable, Badge, Code, Kbd, Rating, Image |
| Тыпаграфіка | Text, Title, Anchor |
| Прагрэс | Progress, Loader, Skeleton |
| Структура | Divider, Collapse |
| Багаты кантэнт | RichTextEditor (TipTap), AreaChart (Recharts) |
| Тэмізацыя | MantineProvider, createTheme, useColorScheme |
| Хукі | useForm, useHotkeys, useToggle, useDebouncedValue, useClickOutside, useElementSize |
Усё ўзята з Mantine v8 і яго экасістэмных пакетаў: @mantine/core, @mantine/notifications, @mantine/dates, @mantine/charts, @mantine/form, @mantine/tiptap, mantine-datatable і mantine-contextmenu.
Дык вось, цяпер вы ведаеце
Section titled “Дык вось, цяпер вы ведаеце”Наступным разам, калі вы ўбачыце маленькае паведамленне, якое выслізгвае з кута экрана — гэта тост. Прамавугольнік вакол прэв’ю партыі — гэта картка. Шэрыя плямы, якія мігцяць перад загрузкай кантэнту — гэта шкілеты.
Калі вы вывучыце назвы, вы пачнёце бачыць іх усюды. У кожнай праграме. На кожным сайце. Тая ж пара дзясяткаў прымітываў, перагрупаваных тысячай розных спосабаў.
Гэта Lego, аж да самага нізу.