@napopravku/nplink

Установка

npm install @napopravku/nplink

Использование

Зарегистрируйте действие в модуле приложения, входящем в клиентскую сборку. Vite-плагин не требуется: API и перехват ссылок устанавливаются при первом обращении в браузере.

import { nplink } from '@napopravku/nplink';

nplink.register('aicopilot/open', (url, params) => {
  aiCopilotStore.open();
  console.log(params.message);
});

url — полный объект URL, params — объект с декодированными query-параметрами. Регистрация безопасна при SSR: на сервере пропускается, в браузере выполняется. registration сохранён как устаревший совместимый алиас register. has(action) и remove(action) принимают ключ действия (aicopilot/open), а не полную ссылку.

Глобальный перехват кликов

По умолчанию клики по ссылкам nplink: перехватываются глобально. Если приложение обрабатывает их самостоятельно, отключите перехват при инициализации:

nplink.init({ interceptClicks: false });

register и handle продолжают работать. init({ interceptClicks: true }) или init() снова включают перехват. Повторная инициализация не дублирует слушатели и не очищает действия.

Ручная обработка

Для кликов по телу баннера, программных переходов и ссылок с stop.prevent вызывайте handle явно:

function onBannerClick(link: string): void {
  if (nplink.handle(link)) return;
  window.location.assign(link);
}

handle(link) возвращает true для ссылок протокола nplink:, включая неизвестные действия, и false для обычных или некорректных ссылок. true означает, что ссылку не нужно передавать обычной навигации, а не успешное завершение асинхронного действия. Неизвестное действие вызывает console.warn; ошибки обработчиков передаются в window.reportError.

Если обработчик вызывается из DOM-события, приложение само вызывает preventDefault и при необходимости stopPropagation. Глобальный перехват уважает defaultPrevented.

В разметке используйте обычную ссылку:

<a href="nplink://aicopilot/open?message=hello">Подобрать врача</a>

SSR

На сервере init, register и registration ничего не делают, handle возвращает false, list() — [], has() и remove() — false. Импорт не требует DOM.

Необязательный Vite-плагин

Для приложений, которым нужна установка window.nplink до выполнения собственного кода, можно оставить плагин. В SSR-приложениях, где transformIndexHtml не вызывается, достаточно импортировать nplink в клиентском entry point.

import { defineConfig } from 'vite';
import nplinkPlugin from '@napopravku/nplink';

export default defineConfig({ plugins: [nplinkPlugin()] });

Протокол

nplink://[объект]/[действие]?параметр=значение&параметр2=значение2

• nplink:// — схема протокола.
• [объект] — получатель действия, например aicopilot.
• /[действие] — действие, например /open.
• ?параметр=значение — необязательные параметры; несколько разделяются &. Специальные символы в именах и значениях кодируются как в обычном URL.

Ключ регистрации — объект/действие, без nplink:// и query-параметров. Значения в params — строки; при повторении ключа берётся последнее значение. Для ссылки из примера обработчик получает params = { message: 'hello' }.