Normalizace řetězců

Než je jakýkoli uživatelský text uložen, platforma jej provede normalizačním pipeline. Pipeline odstraňuje běžné nekonzistence — duplikované mezery, nešikovné zalomení řádků, neobvyklou kapitalizaci, nebezpečné HTML — aby navazující spotřebitelé (vyhledávání, exporty, e-mailové šablony, faktury, kanály) obdrželi předvídatelný vstup bez ohledu na to, jak nedbalý byl původní záznam.Normalizace je citlivá na kontext. Slug určený pro URL je normalizován velmi odlišně od bohatého popisu určeného pro produktovou stránku. Tento článek dokumentuje jednotlivé normalizátory, kdy který použít a jaké invarianty každý z nich zaručuje na svém výstupu.Každý normalizátor je pokryt automatizovanými testy. Pokud najdete vstup, který platforma normalizuje nesprávně, nahlaste to — oprava je téměř vždy "přidání testovacího případu a úprava transformace" spíše než změna návrhu.

toAscii

Převádí libovolný textový řetězec na znakovou sadu ASCII — písmena anglické abecedy, číslice, pomlčky, mezery a malou sadu zdokumentovaných speciálních symbolů. Diakritika je odstraněna, nelatinské skripty jsou v případě možnosti transliterovány a zbývající nereprezentovatelné znaky jsou odstraněny.Příklad: příliš žluťoučký kůň úpěl ďábelské ódy se stane prilis zlutoucky kun upel dabelske ody.Použijte jej vždy, když navazující spotřebitelé vyžadují čisté ASCII — starší protokoly, generování názvů souborů, některé vyhledávací backends.

toSlug

Převádí libovolný řetězec na URL-bezpečný slug. Interně staví na toAscii a poté nahrazuje mezery a speciální znaky pomlčkami. Tam, kde má speciální znak přirozený slovní ekvivalent, je tento znak před slugifikací rozšířen na dané slovo, aby se zachoval význam pro SEO.Příklady: Joolz Aer+ se stane joolz-aer-plus; Project Review: Q1 & Q2 se stane project-review-q1-and-q2; Привет, мир! se stane priviet-mir.Záruky na výstup:

• Obsahuje pouze malá písmena anglické abecedy, číslice a pomlčky. Žádné mezery, žádná interpunkce.
• Po sobě jdoucí pomlčky jsou sloučeny do jedné. Slug nikdy nezačíná ani nekončí pomlčkou.
• Definovaná podskupina speciálních znaků je rozšířena na anglická slova (+ → plus, & → and, …) spíše než vynechána, pro SEO přívětivost.
• Emoji a další znaky bez URL-bezpečného ekvivalentu jsou odstraněny.
• Nelatinské skripty (cyrilice, řečtina atd.) jsou transliterovány.
• Délka výstupu je standardně omezena na 64 znaků; limit je konfigurovatelný.

convertHtmlToText

Odstraňuje HTML značky a vrací bezpečnou, čistě textovou reprezentaci vstupu. Tam, kde má tag přirozený textový ekvivalent, je tento ekvivalent nahrazen — <br> se stane novým řádkem, položky seznamu jsou opatřeny značkou a tak dále. Použijte jej k odvození čistě textového úryvku z bohatého HTML pro indexování vyhledávání, čistě textové části e-mailů nebo zkrácené náhledy.

htmlSpecialCharsDecode

Dekóduje HTML entity zpět na jejich nativní znaky. Typicky se používá při parsování získaných nadpisů, odkazů nebo popisů, které obsahují nedělitelné mezery, lomené závorky nebo jiné znaky, které jsou v HTML escapovány pro přenos.

camelCaseToHumanLabel

Převádí identifikátor camelCase na lidsky čitelný štítek — před každé velké písmeno se vloží mezera a kapitalizace výsledného řetězce se normalizuje.Příklady: date se stane Date; ToBankName se stane To bank name.Použijte jej k odvození výchozích UI štítků z technických názvů vlastností, pokud není k dispozici ručně vytvořený štítek.

castValueToScalar

Převádí skalární řetězec na jeho nejkonkrétnější skalární typ. Užitečné pro parsování routing parametrů nebo URL query hodnot, kde není předem znám podkladový typ.Příklady: 'test' zůstane jako řetězec 'test'; '123' se stane číslem 123; 'true' se stane boolean hodnotou true.

compressHtml

Komprimuje libovolné HTML do kompaktní, sémanticky ekvivalentní formy. Mezery mezi tagy jsou normalizovány, HTML komentáře a nekontentní značky jsou odstraněny a výstup je minimalizován bez změny vykresleného výsledku.Kompresor pracuje s tokeny; nevaliduje strukturu dokumentu. Použijte jej ke zmenšení uložených HTML šablon nebo archivovaných e-mailových těl, kde záleží na velikosti přenosu a žádný navazující spotřebitel nespoléhá na kosmetické formátování.

firstUpper

Převádí první znak řetězce na velké písmeno, pokud má tento znak velkou formu. Číslice a symboly procházejí nedotčeny. Užitečné při skládání vět z uživatelsky zadaných fragmentů, které mohou, ale nemusí začínat velkým písmenem.

foldLine

Normalizuje víceřádkové řetězce ořezáním bílých znaků na začátku a na konci každého řádku a předřazením každého jiného než prvního řádku jednou mezerou odsazení. Hlavním případem použití je generování souborů ICS (iCalendar), jejichž pravidla pro zalamování vyžadují přesně tento vzor.

formatDescriptionForFrontend

Nejtěžší normalizátor — univerzální formátovač pro uživatelské popisy určené k veřejnému vykreslování ve výloze obchodníka. Uživatelé jsou známí svou nepřesností: míchají styly formátování, zapomínají nedělitelné mezery, zneužívají úrovně nadpisů, vytvářejí nekonzistentní odsazení, vkládají HTML fragmenty do markdown editorů a markdown fragmenty do HTML editorů a obecně platformě poskytují velmi hrubý návrh toho, co zamýšleli.formatDescriptionForFrontend se velmi snaží interpretovat cokoli, co uživatel napsal, a vykreslit to do čistého, bezpečného HTML dokumentu, který může výloha zobrazit bez dalšího zpracování. Holé textové bloky jsou obaleny do tagů <p>, i když na to uživatel zapomněl. Nebezpečné konstrukty (script tags, event handlery) jsou odstraněny. Specifické typografické detaily pro dané národní prostředí (české uvozovky, nedělitelné mezery před krátkými slovy) jsou vkládány tam, kde je to vhodné.Návratový typ je TrustedHTML — platforma ručí za bezpečnost výstupu a ten může být vložen do vykreslené stránky bez dodatečné sanitizace. Preferovaný vstupní dialekt je markdown, ale funkce také přijímá prostý text, HTML a volné směsi těchto dvou.

formatSecretMask

Maskuje citlivý řetězec, odhaluje pouze prvních N znaků a nikdy neprozrazuje celkovou délku originálu. Výchozí jsou čtyři viditelné znaky.Používá se pro zobrazení hodnot, které musí být alespoň částečně viditelné, aby si člověk mohl ověřit "ano, toto je ono" — čísla bankovních účtů, bezpečnostní tokeny, otisky API-key — aniž by se odhalilo dostatečně velké množství hodnoty, aby to bylo užitečné pro útočníka.

normalizeString

Nejjemnější normalizátor: bezpečné, generické opravy formátování, které lze aplikovat na jakýkoli řetězec. Ořezává vnější mezery, sbaluje duplicitní mezery, normalizuje konce řádků. Použijte jej jako univerzální řešení před trvalým uložením volně formulovaného uživatelského vstupu, kde se neuplatňuje žádný specifičtější normalizátor.

Související články

• Utils — rejstřík bezstavových utilit platformy.
• Normalizace telefonních čísel — vyhrazená pravidla normalizace pro telefonní čísla.