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

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

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

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

Типы масок

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

  1. path маска - это маска для поиска параметров URL-пути адреса. Разделителем параметров служит символ /. Пример: /path/:param
  2. query маска - это маска, для поиска query-параметров из URL-адреса. Начинается с символа ? (необязательно), разделитель параметров — знак &. Пример: ?query1=:param1&query2=:param2
  3. 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 маска всегда может быть только в конце строки маски.

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

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

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

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

  1. 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'
  2. /doc/:guid - вначале есть символ /, для
    online.sbis.ru/doc/c065
    вычислит guid = c065, а для
    online.sbis.ru/tasks/doc/c065
    не вычислит guid. Поэтому для такого URL-адреса необходимо задать маску без символа / вначале - doc/:guid
  3. tasks/:type/:tabId для
    online.sbis.ru/tasks/OnMe/InWork
    вычислит type = OnMe и tabId = InWork.
  4. ?tab=:tabId или tab=:tabId для
    online.sbis.ru/doc/c065?tab=SomeTab
    вычислит tabId = SomeTab.
  5. #doc/:guid для
    online.sbis.ru/doc/c065#doc/d123
    вычислит doc = d123.
  6. doc/:guid?tab=:tabId для
    online.sbis.ru/doc/c065?tab=SomeTab
    вычислит guid = c065 и tabId = SomeTab.
  7. doc/:guid#tab/:tabId для
    online.sbis.ru/doc/c065#tab/SomeTab
    вычислит guid = c065 и tabId = SomeTab.
  8. ?doc=:guid#tab/:tabId или doc=:guid#tab/:tabId для
    online.sbis.ru/page?doc=c065#tab/SomeTab
    вычислит guid = c065 и tabId = SomeTab.