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

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

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

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

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

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

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

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

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

Установка

Для разработки представления мы используем React (это не мешает использовать Univer с Vue или Angular), а для обработки потоков данных — Rxjs. Обе библиотеки широко применяются в современной фронтенд-разработке, поэтому мы указываем их как peerDependencies². Однако менеджеры пакетов по-разному работают с peerDependencies, и здесь важно учесть несколько особенностей.

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

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

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

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

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

1. Импортируйте в проект файлы стилей Univer, языковые пакеты и необходимые плагины:

   TypeScript

   import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { UniverSheetsPlugin } from '@univerjs/sheets'import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US'import SheetsEnUS from '@univerjs/sheets/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/docs-ui/lib/index.css'import '@univerjs/sheets-ui/lib/index.css'import '@univerjs/sheets-formula-ui/lib/index.css'import '@univerjs/sheets-numfmt-ui/lib/index.css'

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

2. Если требуется Facade API, импортируйте соответствующие пакеты Facade. Это необязательно, но рекомендуется:

   TypeScript

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

3. Затем создайте экземпляр Univer и зарегистрируйте плагины:

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      SheetsEnUS,      SheetsUIEnUS,      SheetsFormulaUIEnUS,      SheetsNumfmtUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverSheetsPlugin)univer.registerPlugin(UniverSheetsUIPlugin)univer.registerPlugin(UniverSheetsFormulaPlugin)univer.registerPlugin(UniverSheetsFormulaUIPlugin)univer.registerPlugin(UniverSheetsNumfmtPlugin)univer.registerPlugin(UniverSheetsNumfmtUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})const univerAPI = FUniver.newAPI(univer)

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

Методы 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,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

Отложенная загрузка плагинов

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

// ...univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

В нашей официальной демонстрации используется этот способ оптимизации — при необходимости можно ориентироваться на нее.

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

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

Мобильная поддержка Sheets остаётся экспериментальной. Проверьте нужные приложению функции на целевых устройствах.

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

import { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

В Sheets сохраните UniverDocsUIPlugin. Он нужен UniverSheetsMobileUIPlugin для редактирования текста внутри ячеек. Отдельный редактор Docs использует 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>

Импорт из CDN

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

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

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

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

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

Установка

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

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

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

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

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

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

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

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

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,    ),  },  presets: [    UniverSheetsCorePreset({      container: 'app',    }),  ],})univerAPI.createWorkbook({})

Возвращаемый здесь объект univerAPI называется Univer Facade API. Через него можно обращаться ко многим функциям Univer.

Метод createUniver

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

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

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

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

Импорт из 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 и работе с данными.