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

В основе архитектуры Univer лежит система плагинов. Она предоставляет разработчикам гибкий и расширяемый фреймворк для приложений, работающих с электронными документами. Благодаря такой архитектуре в Univer легко интегрировать различные функциональные модули под потребности разных пользователей. Однако она также усложняет приложение, особенно для разработчиков, которые только начинают знакомство с Univer.

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

Различия между режимами пресетов и плагинов:

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

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

Ниже показано, как менее чем за двадцать строк кода быстро создать приложение Univer Docs.

С помощью менеджера пакетов

Если в вашем проекте уже используются современные инструменты фронтенд-разработки, интегрировать Univer будет очень просто. Для сборки приложений Univer рекомендуем инструменты с хорошей поддержкой ES Modules, например Vite, esbuild или Webpack 5. Для других инструментов сборки, например Webpack 4, может потребоваться дополнительная настройка.

Установка

Установите @univerjs/presets с помощью выбранного менеджера пакетов:

pnpm add @univerjs/presets @univerjs/preset-docs-core

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

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

Следующий код запускает приложение Univer Docs:

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

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¹. Через него можно обращаться ко многим функциям Univer.

Метод createUniver

Метод createUniver принимает объект с настройками Univer, например языком, темой и плагинами. Он возвращает объект, содержащий экземпляр Univer и экземпляр Univer Facade API.

Некоторые свойства объекта конфигурации:

• locale: языковая среда; может быть значением перечисления LocaleType.
• locales: объект локалей, в котором ключом служит языковая среда, а значением — объект языкового пакета.
• theme: необязательный объект темы.
• presets: массив регистрируемых пресетов, например UniverDocsCorePreset.
• plugins: массив дополнительных регистрируемых плагинов.

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

Импорт из CDN

Если вы не хотите использовать менеджер пакетов или просто хотите быстро попробовать возможности Univer, необходимые ресурсы можно импортировать через CDN. Подробнее см. в разделе Использование Univer через CDN.

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

Для сенсорного интерфейса Univer Docs используйте мобильные UI-плагины.² Выберите режим до создания редактора.

В примере режима плагинов выше замените следующие импорты и регистрации UI до вызова createUnit(). Не добавляйте их к уже инициализированному настольному редактору. Сохраните плагины моделей, движки, локализации, CSS и импорты Facade. Классы экспортируются под разными именами из одной точки входа пакета.

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 к своему приложению.

Контейнер и сенсорное управление

Задайте явную высоту контейнера и viewport страницы. 100dvh соответствует динамической высоте области просмотра. Проверьте прокрутку, масштабирование двумя пальцами, выделение текста, буфер обмена и экранную клавиатуру в целевых мобильных браузерах. Уменьшение ширины не включает мобильные плагины.

UniverMobileUIPlugin по умолчанию использует disableAutoFocus: true, чтобы редактор не получал фокус автоматически при инициализации.

<meta name="viewport" content="width=device-width, initial-scale=1" /><div id="app" style="height: 100dvh"></div>

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

Возможности Univer предоставляются в виде набора плагинов. Помимо основных плагинов, необходимых для работы продукта, вы можете подключать другие по мере необходимости. Ниже на примере простейшего приложения Univer Docs показано, как вручную подобрать и установить плагины.

В отличие от режима пресетов, в режиме плагинов Facade API по умолчанию не подключается. В примерах ниже используется Facade API, поэтому перед созданием его экземпляра импортируйте соответствующие пакеты.

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

Установка

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

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

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

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

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

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

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

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'

2. Импортируйте пакеты Facade API, используемые в примере:

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. Затем создайте экземпляр 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({})

   Развернуть код

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

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

Ленивая загрузка плагинов

Одно из распространённых преимуществ режима плагинов — возможность гибко управлять временем их загрузки. Например, при инициализации приложения можно загрузить только основные плагины, а остальные — после завершения первого рендеринга.

// ...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.

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

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

Выпуски Alpha / Beta

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

pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

npm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta version

yarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta version

bun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@beta # Beta version

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

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

Что дальше

• Основные понятия — познакомьтесь с основными понятиями Univer.
• Возможности — узнайте о возможностях Univer и работе с данными.