Web SDK

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

В этой главе описаны установка и основные способы использования Univer Bases. Bases распространяется как продукт Univer Office SDK и в настоящее время работает в режиме плагинов.

Если вы ещё не знакомы с основными концепциями Univer, сначала прочитайте раздел «Быстрый старт».

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

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

В браузерном приложении Bases обычно регистрируют общую среду выполнения Univer, движок рендеринга, оболочку интерфейса, движок формул и лицензию , а затем — плагины модели и интерфейса Bases.

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

Используйте сборщик с поддержкой 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/engine-render @univerjs/ui @univerjs-pro/bases @univerjs-pro/bases-ui @univerjs-pro/engine-formula @univerjs-pro/license

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

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

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

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

Внимание

  • Регистрируйте UniverLicensePlugin до плагинов Bases.
  • Импортируйте CSS общего интерфейса до CSS интерфейса продукта.
  • Для Bases, включая фигуры на дашбордах, используйте UniverProFormulaEnginePlugin из @univerjs-pro/engine-formula. При объединении нескольких продуктов в одном экземпляре Univer замените существующие импорт и регистрацию UniverFormulaEnginePlugin; не регистрируйте оба движка формул.

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

    TypeScript
    import { UniverBasesPlugin } from '@univerjs-pro/bases'import { UniverBasesUIPlugin } from '@univerjs-pro/bases-ui'import BasesUIEnUS from '@univerjs-pro/bases-ui/locale/en-US'import BasesEnUS from '@univerjs-pro/bases/locale/en-US'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignEnUS from '@univerjs/design/locale/en-US'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-pro/bases-ui/lib/index.css'

  2. Если вы хотите использовать Facade API2, импортируйте соответствующие точки входа:

    TypeScript
    import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/bases/facade'import '@univerjs-pro/bases-ui/facade'

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

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      BasesEnUS,      BasesUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBasesPlugin)univer.registerPlugin(UniverBasesUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BASE, {})const univerAPI = FUniver.newAPI(univer)

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

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

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

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

TypeScript
univer.registerPlugins([  UniverRenderEnginePlugin,  [UniverUIPlugin, { container: 'app' }],  UniverProFormulaEnginePlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBasesPlugin,  UniverBasesUIPlugin,])

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

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

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

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

Выпуски Alpha / Beta

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

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

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

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

Что дальше

Footnotes

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

  2. Facade — прикладной API зарегистрированных плагинов. Импорт точки входа Facade добавляет методы API, но не регистрирует сам функциональный плагин. ↩

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

© 2026 DreamNum Co., Ltd.