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

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

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

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

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

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

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

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

Установка

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/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui

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

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

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

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

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

   TypeScript

   import { UniverBoardsPlugin } from '@univerjs-pro/boards'import { UniverBoardsUIPlugin } from '@univerjs-pro/boards-ui'import BoardsUIEnUS from '@univerjs-pro/boards-ui/locale/en-US'import { UniverInkUIPlugin } from '@univerjs-pro/ink-ui'import InkUIEnUS from '@univerjs-pro/ink-ui/locale/en-US'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'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 { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIEnUS from '@univerjs/drawing-ui/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/docs-ui/lib/index.css'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs-pro/ink-ui/lib/index.css'import '@univerjs-pro/boards-ui/lib/index.css'

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

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

   TypeScript

   import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/boards/facade'

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

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      DrawingUIEnUS,      InkUIEnUS,      BoardsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverInkUIPlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBoardsPlugin)univer.registerPlugin(UniverBoardsUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BOARD, {})const univerAPI = FUniver.newAPI(univer)

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

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

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  [UniverUIPlugin, { container: 'app' }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverDrawingPlugin,  UniverDrawingUIPlugin,  UniverInkUIPlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBoardsPlugin,  UniverBoardsUIPlugin,])

Объект univerAPI, возвращаемый методом FUniver.newAPI(univer), представляет собой Facade API Univer. Используйте его для создания досок и работы с их элементами.

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

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

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

import { UniverBoardsMobileUIPlugin } from '@univerjs-pro/boards-ui'import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverDrawingMobileUIPlugin } from '@univerjs/drawing-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)univer.registerPlugin(UniverDrawingMobileUIPlugin)univer.registerPlugin(UniverBoardsMobileUIPlugin)

Соответствие плагинов

Регистрируйте только нужные функции, сохраняя плагины моделей и зависимости. Наличие мобильного 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>

Пакеты дополнительных возможностей

Добавляйте пакеты возможностей, когда редактору досок требуется соответствующий тип элемента:

pnpm add @univerjs-pro/boards-table @univerjs-pro/boards-table-uipnpm add @univerjs-pro/boards-mind @univerjs-pro/boards-mind-ui

Примеры регистрации возможностей приведены в разделах «Таблицы», «Интеллект-карты» и «Импорт и экспорт».

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

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

Выпуски Alpha / Beta

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

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

npm install @univerjs-pro/boards@alpha # Alpha version
npm install @univerjs-pro/boards@beta # Beta version

yarn add @univerjs-pro/boards@alpha # Alpha version
yarn add @univerjs-pro/boards@beta # Beta version

bun add @univerjs-pro/boards@alpha # Alpha version
bun add @univerjs-pro/boards@beta # Beta version

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

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

Что дальше

• Быстрый старт
• Facade API
• Настройка лицензии
• Интеграция Server SDK