Składnia Xportera: co działa
Ta strona przedstawia, jak składnia szablonów w stylu Xportera jest obsługiwana podczas przesyłania dokumentu Word do trybu szablonu Word. Odzwierciedla działanie skanera migracji uruchamianego przy każdym przesyłaniu — są to te same klasyfikacje, które pojawiają się w raporcie zgodności edytora.
Szczera obietnica
Exportelier nie jest zgodny z Xporterem, nie jest jego zamiennikiem i nie uruchamia szablonów Xportera. Pomaga natomiast w migracji: podczas przesyłania skaner rozpoznaje typową składnię w stylu Xportera i wskazuje dla każdej konstrukcji, czy już działa, może zostać automatycznie przekonwertowana, wymaga ręcznej zmiany lub celowo nie jest obsługiwana.
Dwie twarde gwarancje:
- Obca składnia jest tylko rozpoznawana, nigdy wykonywana. Skaner odczytuje postać konstrukcji —
#{for …},${dateformat(…)}— a żadna część przesłanego szablonu nie jest wykonywana jako kod. - Kod innego dostawcy nie jest kopiowany. Wzorce wykrywania i sugestie aliasów zostały opracowane przez Exportelier na podstawie publicznie udokumentowanych form składni.
Każde odkrycie należy do jednej z czterech klas.
1. Obsługiwane w obecnym stanie
Jeśli Twój szablon korzysta już z kanonicznej składni Exportelier, po prostu działa. Stanowią one notatkę informacyjną, a nie ostrzeżenie.
| Konstrukcja | Przykład |
|---|---|
| Token wartości | ${issue.key} |
| Pętla | ${#each issue.subtasks as sub}…${/each} |
| Warunkowy | ${#if issue.assignee}…${#else}…${/if} |
2. Automatyczna konwersja
Typowa składnia Xportera z bezpiecznym odpowiednikiem „jeden do jednego”. Edytor wyświetla ostrzeżenie i oferuje możliwość skopiowania zamiennika.
| Konstrukt Xportera | Exportelier odpowiednik | Notatki |
|---|---|---|
${Key}, ${Summary}, ${Status}, … | ${issue.key}, ${issue.summary}, ${issue.status}, … | Aliasy pól skalarnych. |
${Assignee.displayName} | ${issue.assignee.displayName} | Znany alias główny; pozostała część ścieżki jest zachowana. |
#{for comments} | ${#each comments as c} | Otwarcie pętli. |
#{if(Assignee)} | ${#if issue.assignee} | Prosty warunek prawdziwości. |
#{else} | ${#else} | Inny znacznik. |
Rozpoznawane aliasy skalarne (16): Key, Summary, Description, Status, Priority, Resolution, Assignee, Reporter, Creator, Created, Updated, DueDate, IssueType, Type, Project, Labels.
Rozpoznawane aliasy kolekcji (5): Comments, Attachments, Subtasks, Links, Worklogs.
Sugerowane przepisanie ma właściwą postać, ale cel nadal musi być prawidłowym powiązaniem opisanym w dokumentacji tokenów. Niektóre aliasy wymagają ręcznej korekty:
- Brak powiązania:
Creator→issue.creator,Resolution→issue.resolution,Project→issue.project,IssueType/Type→issue.issuetype. Żadne z nich nie jest powiązaniem poziomu A. - Niezgodność wielkości liter:
DueDatejest sugerowane jakoissue.duedate; prawidłowe powiązanie toissue.dueDate. - Niezgodność rodzaju:
Labelsjest sugerowane jako wartość skalarna, aleissue.labelsjest kolekcją — użyj${#each issue.labels as l}…. - Linki do problemu:
Linksjest sugerowane jakolinks, ale prawdziwe powiązanie toissue.issueLinks.
3. Nieobsługiwane, ale możliwe do wyjaśnienia
Nie ma bezpośredniego mapowania jeden do jednego, ale istnieje jasny sposób wyrażenia tej samej intencji. Edytor objaśnia potrzebną zmianę; jest to ostrzeżenie, a nie blokada.
| Konstrukt Xportera | Dlaczego | Co zamiast tego zrobić |
|---|---|---|
${Comments[0].Body} | Ścieżki nie mają indeksowania nawiasów. | Powtórz: ${#each comments as c}${c.body}${/each}. |
#{end} | Jeden ogólny terminator. | Użyj pasującego zamknięcia — ${/each} lub ${/if}. |
#{if(votes > 0)} | Warunki sprawdzają tylko prawdziwość pojedynczej ścieżki — bez operatorów. | Zamiast tego sprawdź obecność: ${#if issue.votes}. |
#{elseif(…)} | Nie ma elseif. | Zagnieżdżanie warunków warunkowych. |
Jakakolwiek inna #{…} dyrektywa | Nie rozpoznano. | Zastąp składnią ${…}. |
Niezrównoważony ${#each}/${/if}, zła ścieżka, niezakończona ${ | Przechwycone przez parser. | Napraw token; raport pokazuje dokładną pozycję. |
4. Niebezpieczny lub nieobsługiwany
Celowo poza zakresem — obsługa ich zamieniłaby szablon w silnik skryptowy, którym Exportelier celowo nie jest. Edytor wyświetla błąd i konstrukcja nigdy nie jest wykonywana.
| Konstrukcja Xportera | Status | Co zamiast tego zrobić |
|---|---|---|
${dateformat("yyyy-MM-dd")} i inne wywołania funkcji lub filtrów | Funkcje nigdy nie są uruchamiane. | Użyj stałego zestawu formatującego, np. ${issue.created | date("yyyy-MM-dd")}. |
${jql("project = ABC")} / #{JQL: …} | JQL nigdy nie jest uruchamiane z szablonu. | Wybierz problemy za pomocą kontekstu eksportu. |
| JavaScript, Groovy, Velocity, FreeMarker, filtry JS | To nie jest język skryptowy. | Wyraź układ za pomocą tokenów, pętli, warunków i formaterów. |
set zmienne, break/continue, arytmetyka, wyrażenia | Nie jest to język skryptowy. | Przekształć w obsługiwane konstrukcje. |
Co walidator robi z tymi ustaleniami
W momencie przesyłania każdy wynik staje się komunikatem diagnostycznym o wadze:
- info — obsługiwane w obecnym stanie, brak działań.
- warning — automatyczna konwersja lub wyjaśnienie; eksport nadal trwa, chociaż wartość może stać się pusta, jeśli powiązanie jest nieznane.
- error — niebezpieczna lub nieobsługiwana składnia, niebezpieczna ścieżka lub błąd analizy.
Konstrukcje, które Word zachowuje, ale nie wypełnia – pola tekstowe, przypisy, kontrolki treści, kody pól, komentarze i prześledzone zmiany – są raportowane osobno jako ostrzeżenia unsupported-location. Dokument je przechowuje, ale znajdujące się w nich żetony nie są wypełnione.