JavaScript API

Когда использовать

Этот API нужен, когда опубликованный document должен не только показывать контент, но и взаимодействовать с внешним кодом.

• отправлять page view и другие события в аналитику
• программно открывать section, API page или anchor
• реагировать на смену route, language и завершение рендера
• использовать встроенный поиск без стандартного поискового интерфейса
• связывать экспортированный файл с кнопками, виджетами и section scripts

Точка входа

Публичный объект доступен в браузере как window.OneFileDocsViewer.

const api = window.OneFileDocsViewer;

api.onReady(({ state, page }) => {
  console.log("ready", state.language, page?.title);
});

На внутренний window.viewer опираться не стоит. Для интеграций стабильным контрактом считается только window.OneFileDocsViewer и методы, описанные в справке.

Основные методы

У API есть три основные группы возможностей: подписки на события, чтение state и команды управления.

Для подписок используются on(), off(), once() и сокращения вроде onReady(), onRouteChange() и onError().

Для чтения текущего состояния используются getState(), getCurrentPage() и getPages().

Для управления экспортированным файлом используются navigate(), setLanguage() и search().

const state = api.getState();
const page = api.getCurrentPage();
const pages = api.getPages();

api.navigate({ itemId: "guide", anchorId: "installation" });
api.setLanguage("ru");
const results = api.search("installation", { limit: 5 });

navigate() принимает строковый hash или объект с itemId, pageId и anchorId. search() возвращает массив результатов и не открывает стандартный search UI.

События

API публикует константы событий в api.events и передает в обработчики объект вида { type, timestamp, ...payload }.

Основные события, на которые обычно подписываются интеграции:

• init после загрузки данных и базовой сборки UI
• ready после первой успешной отрисовки стартовой страницы
• routeChange при смене page view
• anchorChange при смене anchor внутри текущей страницы
• languageChange после переключения языка
• pageRender после каждого рендера страницы
• error при диагностируемых ошибках экспортированного файла

Дополнительно доступны события поиска, копирования ссылок, мобильных панелей и section scripts. Это полезно для аналитики и отладки сложных интеграций.

Практические сценарии

Чаще всего JavaScript API используют для аналитики и внешнего управления навигацией.

api.onReady(({ state }) => {
  trackPage(state.route.hash, state.language);
});

api.onRouteChange(({ to, state }) => {
  trackPage(to.hash, state.language);
});

document.getElementById("switch-to-ru")?.addEventListener("click", () => {
  api.setLanguage("ru");
});

Если нужно открыть страницу из собственного интерфейса, используйте navigate(). Если нужно встроить собственный search flow, сначала вызовите search(), а затем передайте выбранный href в navigate().

Границы контракта

Для безопасной интеграции опирайтесь на публичные методы, структуру событий и данные из getState().

Не используйте внутренние поля DocumentationViewer, не завязывайтесь на DOM-структуру экспортированного файла и не вызывайте внутренние методы рендера. Эти детали могут меняться без сохранения совместимости.