Web SDK

Установка и основы использования

Univer PDFs входит в состав Univer Office SDK и пока не предоставляет готовой конфигурации. Создавайте приложения PDF в режиме плагинов.

Univer поддерживает два способа интеграции: режим предустановок и режим плагинов. Предустановки упрощают настройку благодаря готовым наборам плагинов. Для глубокой настройки и расширения возможностей рекомендуем режим плагинов, позволяющий комбинировать и настраивать плагины по отдельности.

Настройка в режиме плагинов

Использование менеджера пакетов

Используйте сборщик с поддержкой ES Modules и поля exports в package.json.

Установка

Univer использует React для интерфейса и RxJS для потоков данных; его также можно встроить в Vue или Angular. Убедитесь, что peer dependencies1 react, react-dom и rxjs установлены. Команда Yarn ниже включает их явно.

Используйте одинаковую версию всех пакетов @univerjs/* и @univerjs-pro/*.

Shell
pnpm add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui

Используйте одну и ту же версию для всех пакетов @univerjs/* и @univerjs-pro/*.

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

Перед инициализацией Univer создайте контейнер и задайте ему явную высоту:

HTML
<div id="app" style="height: 600px"></div>

Перед вызовом FUniver.newAPI(univer) импортируйте точки входа facade из примера ниже. Импортируйте CSS в порядке: @univerjs/design, @univerjs/ui, затем CSS продукта.

  1. Импортируйте стили общего интерфейса перед стилем интерфейса PDF и объедините пакеты локалей, включённые в приложении:

    TypeScript
    import { UniverLicensePlugin } from '@univerjs-pro/license'import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs-pro/pdfs-ui/lib/index.css'

  2. Импортируйте точку входа фасада PDF. Этот импорт с побочным эффектом добавляет в FUniver методы и перечисления PDF:

    TypeScript
    import '@univerjs-pro/pdfs/facade'

  3. Создайте среду выполнения, явно зарегистрируйте набор плагинов и создайте PDF:

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      PdfsUIEnUS,    ),  },})univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverPdfsPlugin)univer.registerPlugin(UniverPdfsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createPdf({ name: 'Untitled PDF' })

Методы univer.registerPlugin и univer.registerPlugins

Метод univer.registerPlugin используется для регистрации плагина в экземпляре Univer. После создания экземпляра Univer вызовите этот метод, чтобы зарегистрировать плагины.

Плагин можно зарегистрировать с помощью метода univer.registerPlugin(Plugin, options), где Plugin — регистрируемый плагин, а options — необязательные параметры конфигурации, которые могут различаться в зависимости от плагина.

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

TypeScript
univer.registerPlugins([  [UniverUIPlugin, { container: 'app' }],  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverPdfsPlugin,  UniverPdfsUIPlugin,])

Поддержка мобильных устройств

Пакет @univerjs-pro/pdfs-ui сейчас не экспортирует отдельный мобильный UI-плагин. Не используйте несуществующие импорты MobileUIPlugin или параметр mobile: true. Узкий контейнер не гарантирует полноценную поддержку касаний; проверьте существующий UI на целевых устройствах.

Необязательный воркер миниатюр

Миниатюры страниц могут отрисовываться в основном потоке без дополнительной настройки. Для больших документов передайте выделенный модульный воркер через thumbnailWorkerURL.

Создайте точку входа воркера, например pdf-thumbnail.worker.ts:

TypeScript
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'startPdfPageThumbnailWorker()

Затем передайте его URL при регистрации плагина интерфейса PDF:

TypeScript
univer.registerPlugin(UniverPdfsUIPlugin, {  thumbnailWorkerURL: new Worker(new URL('./pdf-thumbnail.worker.ts', import.meta.url), { type: 'module' }),})

Параметр также принимает строковый URL или существующий объект Worker. Если воркеры или OffscreenCanvas недоступны, миниатюры отрисовываются в основном потоке.

Совместное редактирование

@univerjs-pro/pdfs-editor не входит в локальный стек. Не регистрируйте его отдельно: сначала установите и зарегистрируйте полный стек @univerjs-pro/collaboration, @univerjs-pro/collaboration-client и @univerjs-pro/collaboration-client-ui, как описано в разделе Совместное редактирование, а затем установите и зарегистрируйте плагин жизненного цикла редактора PDF.

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

Сервисы Node.js могут регистрировать только UniverPdfsPlugin без браузерных пакетов интерфейса. Добавляйте полный стек совместной работы, описанный выше, только если сервису нужно загружать или синхронизировать сохранённые модули PDF.

Другие каналы выпуска

Помимо стабильных выпусков, Univer предлагает каналы alpha / beta и nightly. Они позволяют заранее получить доступ к новейшим функциям, которые еще не выпущены официально. Однако вместе с новыми возможностями возрастают и риски: такие версии могут содержать ошибки, неполные или нестабильные функции. По возможности не используйте их в рабочей среде.

Выпуски Alpha / Beta

После завершения работы над новой функцией или существенным изменением команда разработчиков Univer может предварительно опубликовать их в канале alpha или beta. Установить alpha- или beta-версию пакета Univer можно следующей командой:

Shell
pnpm add @univerjs-pro/pdfs@alpha # Alpha version
pnpm add @univerjs-pro/pdfs@beta # Beta version

Если при использовании alpha- или beta-версий вы обнаружите проблему или захотите поделиться отзывом, сообщите об этом команде разработчиков Univer через GitHub Issues.

Мы будем рады вашим отзывам о предварительных выпусках.

Что дальше

Footnotes

  1. peerDependencies — зависимости, совместимые версии которых предоставляет основное приложение. Это позволяет Univer и приложению использовать общую копию библиотек, например React. ↩

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.