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

- Human documentation: [https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/installation](https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/installation)

- Agent Markdown: [https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/installation.md](https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/installation.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [pdfs/getting-started/installation/index.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/getting-started/installation/index.ru-RU.mdx)

---

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

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

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

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

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

#### Установка

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

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

#### pnpm

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

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui react react-dom rxjs
```

#### bun

```shell
bun 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 и объедините пакеты локалей, включённые в приложении:
   
   ```ts
   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'
   ```

1.
   Импортируйте точку входа фасада PDF. Этот импорт с побочным эффектом добавляет в `FUniver` методы и перечисления PDF:
   
   ```ts
   import '@univerjs-pro/pdfs/facade'
   ```

1.
   Создайте среду выполнения, явно зарегистрируйте набор плагинов и создайте PDF:
   
   ```ts
   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`:

```ts
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

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

```ts
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`, как описано в разделе [Совместное редактирование](https://docs.univer.ai/ru-RU/guides/pdfs/features/collaboration.md), а затем установите и зарегистрируйте плагин жизненного цикла редактора PDF.

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

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

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

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

### Выпуски Alpha / Beta

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

#### npm

```bash
npm install @univerjs-pro/pdfs@alpha # Alpha version
npm install @univerjs-pro/pdfs@beta # Beta version
```

#### pnpm

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

#### yarn

```bash
yarn add @univerjs-pro/pdfs@alpha # Alpha version
yarn add @univerjs-pro/pdfs@beta # Beta version
```

#### bun

```bash
bun add @univerjs-pro/pdfs@alpha # Alpha version
bun add @univerjs-pro/pdfs@beta # Beta version
```

Если при использовании alpha- или beta-версий вы обнаружите проблему или захотите поделиться отзывом, сообщите об этом команде разработчиков Univer через [GitHub Issues](https://github.com/dream-num/univer/issues).

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

## Что дальше

* [Быстрый старт](https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/ru-RU/guides/pdfs/getting-started/facade.md)
* [Настройка лицензии](https://docs.univer.ai/ru-RU/server/license.md)
* [Интеграция Server SDK](https://docs.univer.ai/ru-RU/server.md)

[^peer-dependency]: `peerDependencies` — зависимости, совместимые версии которых предоставляет основное приложение. Это позволяет Univer и приложению использовать общую копию библиотек, например React.