# Установка и основы использования - Human documentation: [https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation](https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation) - Agent Markdown: [https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation.md](https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation.md) - Requested language: `ru-RU` - Content language: `ru-RU` - Documentation version: `1.2.0` - Source: [docs/getting-started/installation/index.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/installation/index.ru-RU.mdx) --- В основе архитектуры Univer лежит система плагинов. Она предоставляет разработчикам гибкий и расширяемый фреймворк для приложений, работающих с электронными документами. Благодаря такой архитектуре в Univer легко интегрировать различные функциональные модули под потребности разных пользователей. Однако она также усложняет приложение, особенно для разработчиков, которые только начинают знакомство с Univer. Чтобы упростить быструю интеграцию и начало работы с Univer, предусмотрено два варианта: **режим плагинов** и **режим пресетов**. **Пресет** представляет собой набор предварительно настроенных плагинов, поэтому без сложных расширений оба режима предоставляют одинаковые возможности. > [!WARNING: Внимание] > * **Одинаковые версии зависимостей**: независимо от того, используете вы режим пресетов или плагинов, версии всех зависимостей должны совпадать. > * **Осторожно сочетайте плагины и пресеты**: если плагин уже входит в пресет, при использовании этого пресета не нужно импортировать плагин отдельно. Иначе возможны конфликты плагинов или некорректная работа функций. Различия между режимами пресетов и плагинов: | Режим плагинов | Режим пресетов | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Соответствующие пакеты Facade API нужно импортировать вручную | Пакеты Facade API не нужно импортировать вручную | | Необходимо учитывать порядок регистрации плагинов с одинаковой функциональностью | Не нужно учитывать порядок регистрации функций, входящих в пресеты | | Поддерживается ленивая загрузка отдельных плагинов | Настроенные пресеты загружаются синхронно при инициализации | Univer поддерживает два способа интеграции: *режим предустановок* и *режим плагинов*. Предустановки упрощают настройку благодаря готовым наборам плагинов. Для **глубокой настройки и расширения возможностей** рекомендуем режим плагинов, позволяющий комбинировать и настраивать плагины по отдельности. ## Настройка в режиме пресетов Ниже показано, как менее чем за двадцать строк кода быстро создать приложение Univer Docs. ### С помощью менеджера пакетов Если в вашем проекте уже используются современные инструменты фронтенд-разработки, интегрировать Univer будет очень просто. Для сборки приложений Univer рекомендуем инструменты с хорошей поддержкой ES Modules, например [Vite](https://vitejs.dev/), [esbuild](https://esbuild.github.io/) или [Webpack 5](https://webpack.js.org/). Для других инструментов сборки, например Webpack 4, может потребоваться дополнительная настройка. #### Установка Установите `@univerjs/presets` с помощью выбранного менеджера пакетов: #### npm ```bash npm install @univerjs/presets @univerjs/preset-docs-core ``` #### pnpm ```bash pnpm add @univerjs/presets @univerjs/preset-docs-core ``` #### yarn ```bash yarn add @univerjs/presets @univerjs/preset-docs-core ``` #### bun ```bash bun add @univerjs/presets @univerjs/preset-docs-core ``` #### Использование > [!WARNING] > Если ваш инструмент сборки не поддерживает поле `exports` в package.json, как это часто бывает с Webpack 4, необходимо вручную заменить сопоставленные пути фактическими. Следующий код запускает приложение Univer Docs: ```html title="index.html"
``` ```typescript import { UniverDocsCorePreset } from '@univerjs/preset-docs-core' import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US' import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import '@univerjs/preset-docs-core/lib/index.css' const { univer, univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetDocsCoreEnUS, ), }, presets: [ UniverDocsCorePreset({ container: 'app', }), ], }) univerAPI.createDocument({}) ``` Возвращаемый объект `univerAPI` называется Univer Facade API[^facade-entry]. Через него можно обращаться ко многим функциям Univer. > Interactive example: [Open the playground](/playground/docs/slim-via-preset) > [!WARNING] > `UniverDocsCorePreset` также можно импортировать из `@univerjs/presets/preset-docs-core`, но при этом необходимо убедиться, что ваш инструмент сборки поддерживает поле `exports` в package.json. #### Метод `createUniver` Метод `createUniver` принимает объект с настройками Univer, например языком, темой и плагинами. Он возвращает объект, содержащий экземпляр Univer и экземпляр Univer Facade API. Некоторые свойства объекта конфигурации: * `locale`: языковая среда; может быть значением перечисления `LocaleType`. * `locales`: объект локалей, в котором ключом служит языковая среда, а значением — объект языкового пакета. * `theme`: необязательный объект темы. * `presets`: массив регистрируемых пресетов, например `UniverDocsCorePreset`. * `plugins`: массив дополнительных регистрируемых плагинов. Плагины, которые не входят ни в один пакет пресета, а также собственные плагины можно зарегистрировать через свойство `plugins`. Кроме того, после получения экземпляра Univer плагины можно регистрировать методом `univer.registerPlugin`. > [!NOTE] > Подробнее о методе `createUniver` см. в [справочнике API: createUniver](https://docs.univer.ai/ru-RU/reference/methods/create-univer.md). ### Импорт из CDN Если вы не хотите использовать менеджер пакетов или просто хотите быстро попробовать возможности Univer, необходимые ресурсы можно импортировать через CDN. Подробнее см. в разделе [Использование Univer через CDN](https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation/cdn.md#plugin-mode). ## Поддержка мобильных устройств > [!WARNING] > Для примеров нужны пакеты SDK, экспортирующие перечисленные мобильные плагины. Все зависимости `@univerjs/*` и `@univerjs-pro/*` должны иметь **одинаковую версию**. > > `1.0.0-rc.0` не экспортирует `UniverDocsMobileUIPlugin`. Для этого примера используйте сборку, содержащую соответствующую мобильную точку входа. Для сенсорного интерфейса Univer Docs используйте **мобильные UI-плагины**.[^mobile-ui-mode] Выберите режим до создания редактора. В примере режима плагинов выше **замените** следующие импорты и регистрации UI до вызова `createUnit()`. Не добавляйте их к уже инициализированному настольному редактору. Сохраните плагины моделей, движки, локализации, CSS и импорты Facade. Классы экспортируются под разными именами из **одной точки входа пакета**. ```typescript import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui' import { UniverMobileUIPlugin } from '@univerjs/ui' univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' }) univer.registerPlugin(UniverDocsMobileUIPlugin) ``` Текущие `UniverSheetsCorePreset` и `UniverDocsCorePreset` регистрируют настольный UI и не имеют параметра `mobile: true`. Для мобильного режима явно соберите набор плагинов. Добавление мобильных плагинов после настольного пресета не заменяет его UI. ### Соответствие плагинов Регистрируйте только нужные функции, сохраняя плагины моделей и зависимости. Наличие мобильного UI не означает одинаковый набор элементов управления на обеих платформах. Функциям Pro по-прежнему нужны соответствующая лицензия. Для функций, которым нужен backend, подключите соответствующие модули [Univer Server SDK](https://docs.univer.ai/ru-RU/server.md) к своему приложению. | Пакет | Настольная регистрация | Мобильная регистрация | | ---------------------------------- | --------------------------------- | --------------------------------------- | | `@univerjs/ui` | `UniverUIPlugin` | `UniverMobileUIPlugin` | | `@univerjs/docs-ui` | `UniverDocsUIPlugin` | `UniverDocsMobileUIPlugin` | | `@univerjs/drawing-ui` | `UniverDrawingUIPlugin` | `UniverDrawingMobileUIPlugin` | | `@univerjs/thread-comment-ui` | `UniverThreadCommentUIPlugin` | `UniverThreadCommentMobileUIPlugin` | | `@univerjs-pro/shape-editor-ui` | `UniverShapeEditorUIPlugin` | `UniverShapeEditorMobileUIPlugin` | | `@univerjs-pro/chart-ui` | `UniverChartUIPlugin` | `UniverChartMobileUIPlugin` | | `@univerjs-pro/exchange-client` | `UniverExchangeClientPlugin` | `UniverExchangeClientMobileUIPlugin` | | `@univerjs/docs-drawing-ui` | `UniverDocsDrawingUIPlugin` | `UniverDocsDrawingMobileUIPlugin` | | `@univerjs/docs-hyper-link-ui` | `UniverDocsHyperLinkUIPlugin` | `UniverDocsHyperLinkMobileUIPlugin` | | `@univerjs/docs-thread-comment-ui` | `UniverDocsThreadCommentUIPlugin` | `UniverDocsThreadCommentMobileUIPlugin` | | `@univerjs-pro/docs-callout-ui` | `UniverDocsCalloutUIPlugin` | `UniverDocsCalloutMobileUIPlugin` | | `@univerjs-pro/docs-chart-ui` | `UniverDocsChartUIPlugin` | `UniverDocsChartMobileUIPlugin` | | `@univerjs-pro/docs-code-ui` | `UniverDocsCodeUIPlugin` | `UniverDocsCodeMobileUIPlugin` | | `@univerjs-pro/docs-column-ui` | `UniverDocsColumnUIPlugin` | `UniverDocsColumnMobileUIPlugin` | | `@univerjs-pro/docs-formula-ui` | `UniverDocsFormulaUIPlugin` | `UniverDocsFormulaMobileUIPlugin` | | `@univerjs-pro/docs-latex-ui` | `UniverDocsLatexUIPlugin` | `UniverDocsLatexMobileUIPlugin` | | `@univerjs-pro/docs-list-ui` | `UniverDocsListUIPlugin` | `UniverDocsListMobileUIPlugin` | | `@univerjs-pro/docs-quote-ui` | `UniverDocsQuoteUIPlugin` | `UniverDocsQuoteMobileUIPlugin` | | `@univerjs-pro/docs-shape-ui` | `UniverDocsShapeUIPlugin` | `UniverDocsShapeMobileUIPlugin` | | `@univerjs-pro/docs-table-ui` | `UniverDocsTableUIPlugin` | `UniverDocsTableMobileUIPlugin` | ### Контейнер и сенсорное управление Задайте явную высоту контейнера и viewport страницы. `100dvh` соответствует динамической высоте области просмотра. Проверьте прокрутку, масштабирование двумя пальцами, выделение текста, буфер обмена и экранную клавиатуру в целевых мобильных браузерах. Уменьшение ширины не включает мобильные плагины. `UniverMobileUIPlugin` по умолчанию использует `disableAutoFocus: true`, чтобы редактор не получал фокус автоматически при инициализации. ```html
``` ## Настройка в режиме плагинов Возможности Univer предоставляются в виде набора плагинов. Помимо основных плагинов, необходимых для работы продукта, вы можете подключать другие по мере необходимости. Ниже на примере простейшего приложения Univer Docs показано, как вручную подобрать и установить плагины. В отличие от режима пресетов, в режиме плагинов Facade API по умолчанию не подключается. В примерах ниже используется Facade API, поэтому перед созданием его экземпляра импортируйте соответствующие пакеты. ### Использование менеджера пакетов #### Установка 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/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui ``` #### npm ```shell npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui ``` #### yarn ```shell yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs ``` #### bun ```shell bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui ``` #### Использование Перед инициализацией Univer создайте контейнер и задайте ему явную высоту: ```html
``` Перед вызовом `FUniver.newAPI(univer)` импортируйте точки входа facade из примера ниже. Импортируйте CSS в порядке: `@univerjs/design`, `@univerjs/ui`, затем CSS продукта. > [!WARNING: Внимание] > * Пакеты Facade API, языковые пакеты и файлы стилей есть не у всех плагинов. Это указывается в документации каждой функции. > * Порядок импорта файлов стилей имеет значение. Импортируйте CSS-стили `@univerjs/design` и `@univerjs/ui` перед стилями остальных плагинов. 1. Импортируйте в проект файлы стилей Univer, языковые пакеты и необходимые плагины: ```typescript import { LocaleType, mergeLocales, Univer } from '@univerjs/core' import { FUniver } from '@univerjs/core/facade' import DesignEnUS from '@univerjs/design/locale/en-US' import { UniverDocsPlugin } from '@univerjs/docs' import { UniverDocsUIPlugin } from '@univerjs/docs-ui' import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US' import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula' import { UniverRenderEnginePlugin } from '@univerjs/engine-render' 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/docs-ui/lib/index.css' ``` 1. Импортируйте пакеты Facade API, используемые в примере: ```typescript import '@univerjs/engine-formula/facade' import '@univerjs/ui/facade' import '@univerjs/docs/facade' import '@univerjs/docs-ui/facade' ``` 1. Затем создайте экземпляр Univer и зарегистрируйте плагины: ```typescript const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( DesignEnUS, UIEnUS, DocsUIEnUS, ), }, }) univer.registerPlugin(UniverRenderEnginePlugin) univer.registerPlugin(UniverFormulaEnginePlugin) univer.registerPlugin(UniverUIPlugin, { container: 'app', }) univer.registerPlugin(UniverDocsPlugin) univer.registerPlugin(UniverDocsUIPlugin) const univerAPI = FUniver.newAPI(univer) univerAPI.createDocument({}) ``` > Interactive example: [Open the playground](/playground/docs/slim-via-plugin) #### Методы `univer.registerPlugin` и `univer.registerPlugins` Метод `univer.registerPlugin` используется для регистрации плагина в экземпляре Univer. После создания экземпляра Univer вызовите этот метод, чтобы зарегистрировать плагины. Плагин можно зарегистрировать с помощью метода `univer.registerPlugin(Plugin, options)`, где `Plugin` — регистрируемый плагин, а `options` — необязательные параметры конфигурации, которые могут различаться в зависимости от плагина. Для одновременной регистрации нескольких плагинов передайте массив в `univer.registerPlugins`. Это удобно, когда требуется централизованно управлять плагинами. ```typescript univer.registerPlugins([ UniverRenderEnginePlugin, UniverFormulaEnginePlugin, [UniverUIPlugin, { container: 'app', }], UniverDocsPlugin, UniverDocsUIPlugin, ]) ``` #### Ленивая загрузка плагинов Одно из распространённых преимуществ режима плагинов — возможность гибко управлять временем их загрузки. Например, при инициализации приложения можно загрузить только основные плагины, а остальные — после завершения первого рендеринга. ```typescript // ... const univerAPI = FUniver.newAPI(univer) univerAPI.createDocument({}) import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => { univer.registerPlugin(UniverWatermarkPlugin, { textWatermarkSettings: { content: 'Hello, Univer!', fontSize: 36, }, }) }) ``` ### Импорт из CDN Если вы не хотите использовать менеджер пакетов или просто хотите быстро попробовать возможности Univer, необходимые ресурсы можно импортировать через CDN. Подробнее см. в разделе [Использование Univer через CDN](https://docs.univer.ai/ru-RU/guides/docs/getting-started/installation/cdn.md#plugin-mode). ## Другие каналы выпуска Помимо стабильных выпусков, Univer предлагает каналы alpha / beta и nightly. Они позволяют заранее получить доступ к новейшим функциям, которые еще не выпущены официально. Однако вместе с новыми возможностями возрастают и риски: такие версии могут содержать ошибки, неполные или нестабильные функции. По возможности не используйте их в рабочей среде. ### Выпуски Alpha / Beta После завершения работы над новой функцией или существенным изменением команда разработчиков Univer может предварительно опубликовать их в канале alpha или beta. Установить alpha- или beta-версию пакета Univer можно следующей командой: #### npm ```bash npm install @univerjs/@alpha # Alpha version npm install @univerjs/@beta # Beta version ``` #### pnpm ```bash pnpm add @univerjs/@alpha # Alpha version pnpm add @univerjs/@beta # Beta version ``` #### yarn ```bash yarn add @univerjs/@alpha # Alpha version yarn add @univerjs/@beta # Beta version ``` #### bun ```bash bun add @univerjs/@alpha # Alpha version bun add @univerjs/@beta # Beta version ``` Если при использовании alpha- или beta-версий вы обнаружите проблему или захотите поделиться отзывом, сообщите об этом команде разработчиков Univer через [GitHub Issues](https://github.com/dream-num/univer/issues). Мы будем рады вашим отзывам о предварительных выпусках. ## Что дальше * [Основные понятия](https://docs.univer.ai/ru-RU/guides/docs/getting-started/quickstart.md#basic-concepts) — познакомьтесь с основными понятиями Univer. * [Возможности](https://docs.univer.ai/ru-RU/guides/docs/features/core.md) — узнайте о возможностях Univer и работе с данными. [^facade-entry]: Facade — прикладной API зарегистрированных плагинов. Импорт точки входа Facade добавляет методы API, но не регистрирует сам функциональный плагин. [^peer-dependency]: `peerDependencies` — зависимости, совместимые версии которых предоставляет основное приложение. Это позволяет Univer и приложению использовать общую копию библиотек, например React. [^mobile-ui-mode]: Мобильный UI-плагин выбирает сенсорные элементы управления и мобильные сервисы при инициализации. Он не определяет устройство автоматически и не переключает существующий экземпляр при изменении размера окна. Чтобы сменить режим, сохраните состояние документа, уничтожьте старый экземпляр и инициализируйте выбранный набор плагинов.