Навигация и маршрутизация в JS-модулях

Скопировать ссылку на статью

Скопировано

Содержание

• API хоста для навигации
• useRouter()
• Query string
• Переходы через goTo()
• Ключевые свойства навигации

Навигация и маршрутизация в JS-модулях строятся вокруг API хоста и данных маршрутизации, которые CRM передает расширению. Эти механизмы нужны для переходов между страницами CRM, генерации ссылок по имени маршрута и синхронизации состояния страницы с query string.

API хоста для навигации

Composable-утилита useHost() возвращает объект API хоста, через который доступны методы навигации:

• goTo(route, params?)
• getLocation()
• replaceQuery(query, options?)
• pushQuery(query, options?).

Типы API хоста описаны в host.d.ts.

Пример:

import { useHost } from '@retailcrm/embed-ui'

const host = useHost()

host.goTo('orders', { page: 1 })
host.replaceQuery({ status: 'new' }, { preserveExisting: true })

useRouter()

Для генерации URL по имени Symfony-маршрута используется useRouter(). Этот composable берет данные из settings['system.routing'] и внутри использует @omnicajs/symfony-router.

Исторический ориентир: генерация ссылок через useRouter() доступна в @retailcrm/embed-ui, начиная с v0.5.15.

Пример:

import { useRouter } from '@retailcrm/embed-ui'
import { useContext as useSettings } from '@retailcrm/embed-ui-v1-contexts/remote/settings'

const settings = useSettings()
await settings.initialize()

const router = useRouter()
const url = router.value.generate('orders')

Это основной способ строить ссылки по имени маршрута без прямого знания внутреннего устройства маршрутизации CRM. Важно, что useRouter() опирается на settings.system.routing, поэтому контекст settings должен быть инициализирован.

Query string

Для сценариев со страницами особенно важны:

• getLocation() — чтение текущего pathname, search, hash и разобранного query;
• replaceQuery() — обновление query без добавления новой записи в историю;
• pushQuery() — обновление query с добавлением новой записи в историю.

Методы replaceQuery() и pushQuery() принимают объект query-параметров и опциональный параметр preserveExisting. Если preserveExisting включен, переданные значения объединяются с текущими query-параметрами страницы.

Это позволяет хранить состояние страницы модуля в URL: фильтры, страницу пагинации, выбранный режим отображения или другие параметры сценария.

Такой подход используется, например, в ReturnsPage.vue, где фильтры и пагинация синхронизируются с query string страницы.

Переходы через goTo()

Для программного перехода на страницы CRM используется метод goTo() из API хоста.

Исторический ориентир: перенаправление через goTo() доступно в @retailcrm/embed-ui, начиная с v0.9.2.

Пример:

import { useHost } from '@retailcrm/embed-ui'

const host = useHost()

host.goTo('crm_orders')
host.goTo('crm_orders_edit', { id: 12345 })

Ключевые свойства навигации

• API навигации связан с settings.system.routing, useRouter() и режимом выполнения страниц;
• query string является нормальным способом хранить состояние сценария страницы;
• навигация через API хоста позволяет модулю встраиваться в общую навигационную модель CRM.

Подробно про сами страницы модулей, их конфигурацию и URL см. в статье Создание собственных страниц JS-модулей.