Маска и синтаксис её задания

Эта статья содержит общее описание синтаксиса масок используемых в механизме маршрутизации в Wasaby Framework. Из статьи вы получите ответы на такие вопросы, как:

что такое маска;
какие типы масок есть;
как использовать смешанный синтаксис масок;
особенности/ограничения масок;
примеры использования масок.

Что такое маска

Для работы с параметрами контролов используется маска. Маска - это строка с параметрами, синтаксически выделяемыми двоеточием, которая единственным образом определяет подстроку в URL-адресе. Пример маски: /doc/:guid?tab=:tabId

Типы масок

Поддерживается всего три основных типа масок:

path маска - это маска для поиска параметров URL-пути адреса. Разделителем параметров служит символ /. Пример: /path/:param
query маска - это маска, для поиска query-параметров из URL-адреса. Начинается с символа ? (необязательно), разделитель параметров — знак &. Пример: ?query1=:param1&query2=:param2
fragment-маска - это маска, которой описывается якорь URL-адреса. Она должна начинаться с символа #. Эта маска может быть описана в виде одной из двух предыдущих масок:
- path-fragment маска - описана как path маска. Пример: #fragment/:fvalue
- query-fragment маска - описана как query маска. Пример: #fragment=:fvalue

Смешанный синтаксис масок

В прикладных задачах может понадобиться разобрать сложный URL-адрес, в котором могут присутствовать URL-путь, query-параметры и/или якорь. Поэтому описанные выше типы масок могут быть использованы в любой комбинации. Единственное ограничение в том, что порядок частей маски должен полностью соответствовать порядку следования частей URL-адреса:

/doc/:guid?query=:qparam#fragment/:fparam

path маска всегда может быть только вначале строки
query маска всегда идет после path маски (если она есть)
fragment маска всегда может быть только в конце строки маски.

Особенности/ограничения

При составлении масок, необходимо учесть следующие особенности:

если маска начинается с "/", то поиск соответствующего параметра будет вестись строго от начала URL-адреса Напр. маска /doc/:guid для URL-адреса online.sbis.ru/tasks/tab/tasks не вычислит значение параметра guid.
чтобы обозначить, что маска соответствует query маске, необходимо в начале маски добавить знак ?. Если этого не сделать, то будут лишние вычисления при определении типа маски.
чтобы обозначить, что маска соответствует fragment маске, необходимо вначале маски добавить символ #. Т.к. если этого не сделать, то при определении типа маски он может быть "ошибочно" распознан как path маска или query маска
fragment маска может быть только одного подтипа - path-fragment маска или query-fragment маска

Примеры использования масок

URL-адрес /task/name?query=value

// router.json
{
   "/task": "ModuleName/task",
   "/contacts": "ModuleName/contacts"
}

Чтобы вычислить первую часть URL-адреса (напр. task или contacts), необходимо использовать маску ModuleName/:sectionId.

// MyModule.ts
var MaskResolver = require('Router/router').MaskResolver;
const params = MaskResolver.calculateUrlParams('ModuleName/:sectionId');
// params.sectionId = 'task'

/doc/:guid - вначале есть символ /, для
```
online.sbis.ru/doc/c065
```
вычислит guid = c065, а для
```
online.sbis.ru/tasks/doc/c065
```
не вычислит guid. Поэтому для такого URL-адреса необходимо задать маску без символа / вначале - doc/:guid
tasks/:type/:tabId для
```
online.sbis.ru/tasks/OnMe/InWork
```
вычислит type = OnMe и tabId = InWork.
?tab=:tabId или tab=:tabId для
```
online.sbis.ru/doc/c065?tab=SomeTab
```
вычислит tabId = SomeTab.
#doc/:guid для
```
online.sbis.ru/doc/c065#doc/d123
```
вычислит doc = d123.
doc/:guid?tab=:tabId для
```
online.sbis.ru/doc/c065?tab=SomeTab
```
вычислит guid = c065 и tabId = SomeTab.
doc/:guid#tab/:tabId для
```
online.sbis.ru/doc/c065#tab/SomeTab
```
вычислит guid = c065 и tabId = SomeTab.
?doc=:guid#tab/:tabId или doc=:guid#tab/:tabId для
```
online.sbis.ru/page?doc=c065#tab/SomeTab
```
вычислит guid = c065 и tabId = SomeTab.