Основные возможности

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

Возможности

К основным возможностям Univer Docs относятся:

• Рендеринг документов: отрисовка документов Univer Docs, включая курсор и выделение.
• Верстка документов: полная верстка текста, включая настройку абзацев, интервалы до и после абзаца, выравнивание, отступы и выступы. Также поддерживаются возможности верстки внутри абзацев: сжатие и вынос знаков препинания, межзнаковый интервал и перенос слов латиницей.
• Вычисление формул: добавление и вычисление формул Univer (в разработке).
• Работа с таблицами: вставка и редактирование простых таблиц, в том числе добавление и удаление строк, а также редактирование ячеек.
• Стили документов: Univer Docs поддерживает как традиционный стиль документов, аналогичный Microsoft Word (с разбивкой на страницы, верхними и нижними колонтитулами), так и современный стиль, аналогичный Notion. В современном стиле разбивка на страницы не требуется, содержимое может расширяться без ограничений, а в верстке можно сочетать различные официальные и сторонние блочные элементы, такие как текст, изображения и таблицы (запланировано).
• Верхние и нижние колонтитулы: вставка колонтитулов и редактирование их содержимого с возможностью различать первую, четные и нечетные страницы (поддерживается только в традиционных документах).
• Списки: вставка и редактирование нумерованных, маркированных списков и списков задач, а также изменение их отступов.
• Эмодзи и символы: вставка эмодзи и символов с ленты Docs.
• Система плагинов: поддержка пользовательских плагинов, например для формул, изображений и диаграмм. Это также одна из ключевых архитектурных возможностей Univer.

Режим плагинов

Установка

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

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

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

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

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

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/lib/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/docs/facade'import '@univerjs/docs-ui/facade'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'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({})

Плагины и конфигурация

@univerjs/core

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

import type { IUniverConfig } from '@univerjs/core'import { LocaleType, Univer } from '@univerjs/core'const config: IUniverConfig = {  locale: LocaleType.RU_RU,  darkMode: false,}const univer = new Univer(config)

Справочник: IUniverConfig

@univerjs/engine-render

Этот плагин представляет собой движок рендеринга Univer. Он отвечает за отрисовку содержимого, полос прокрутки, курсора и выделения и предоставляет UniverRenderEnginePlugin.

Справочник: @univerjs/engine-render

@univerjs/engine-formula

Этот плагин представляет собой движок формул Univer. Он отвечает за вычисление и обработку формул и предоставляет UniverFormulaEnginePlugin.

Справочник: @univerjs/engine-formula

@univerjs/design

Этот плагин представляет собой дизайн-систему Univer и предоставляет все базовые компоненты и стили.

См. также: раздел об UI

@univerjs/ui

Этот плагин служит основой пользовательского интерфейса Univer и предоставляет UniverUIPlugin.

UniverUIPlugin предоставляет параметры для базовой настройки макета.

interface IUniverUIConfig {  // Container element, can be a string or a DOM element  container?: string | HTMLElement  // Whether to show the header  header?: boolean  // Whether to show the header toolbar  toolbar?: boolean  // The type of the header toolbar. 'classic': default classic mode; 'grid': two-row grid mode; 'collapsed': compact mode; 'simple': ungrouped mode  ribbonType?: RibbonType  // Whether to show the context menu  contextMenu?: boolean  // Whether to disable auto focus  disableAutoFocus?: true  // Dependency injection override configuration  override?: DependencyOverride  // Menu configuration  menu?: MenuConfig}

Параметр конфигурации menu позволяет задавать, должны ли отображаться отдельные пункты меню:

univer.registerPlugin(UniverDocsUIPlugin, {  menu: {    'doc.command.set-inline-format-bold': {      hidden: true,    },    'doc.command.set-inline-format-italic': {      hidden: true,      disabled: true,    },  },})

Здесь 'doc.command.set-inline-format-bold' и 'doc.command.set-inline-format-italic' — имена команд, соответствующих этим пунктам меню.

Справочник: @univerjs/docs-ui

@univerjs/docs

Это основной плагин Univer Docs. Он предоставляет UniverDocsPlugin.

Справочник: @univerjs/docs

@univerjs/docs-ui

Это UI-плагин Univer Docs, который содержит компоненты интерфейса и средства взаимодействия с редактором документов. Он предоставляет UniverDocsUIPlugin.

Справочник: @univerjs/docs-ui

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

Установка

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

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

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()],})univerAPI.createDocument({})

Предустановки и конфигурация

@univerjs/presets

Эта предустановка предоставляет метод createUniver для создания приложения Univer и экспортирует все методы и объекты из @univerjs/core и @univerjs/design.

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

interface ICreateUniverParameter {  // Univer instance theme, default is `defaultTheme`  theme: IStyleSheet  // Whether to use dark mode, default is false  darkMode?: boolean  // The locale of the Univer instance  locale: LocaleType  region?: LocaleType  // The locale objects to use, with keys as locale types and values as corresponding locale objects  locales: ILocales  // The log level of the Univer instance  logLevel?: LogLevel  // The list of presets to use.  presets: IPresets[]  // The list of plugins to use.  plugins: IPlugins[]}

Справочник: createUniver

@univerjs/preset-docs-core

Это основная предустановка Univer Docs. Она содержит необходимые для электронных документов базовые возможности, включая редактор документов, движок формул и движок рендеринга.

interface IUniverDocsCorePresetConfig {  // Container element, can be a string or a DOM element  container?: string | HTMLElement  // Whether to show the header  header?: boolean  // Whether to show the header toolbar  toolbar?: boolean  // The type of the header toolbar. 'classic': default classic mode; 'grid': two-row grid mode; 'collapsed': compact mode; 'simple': ungrouped mode  ribbonType?: RibbonType  // Whether to show the footer  footer?: boolean  // Whether to show the context menu  contextMenu?: boolean  // Whether to disable auto focus  disableAutoFocus?: true  // Menu configuration  menu?: MenuConfig  // ... More configuration options}

Параметр конфигурации menu позволяет задавать, должны ли отображаться отдельные пункты меню:

UniverDocsCorePreset({  menu: {    'doc.command.set-inline-format-bold': {      hidden: true,    },    'doc.command.set-inline-format-italic': {      hidden: true,      disabled: true,    },  },})

Здесь 'doc.command.set-inline-format-bold' и 'doc.command.set-inline-format-italic' — имена команд, соответствующих этим пунктам меню.

Справочник: @univerjs/preset-docs-core

Управление просмотром

На вкладке просмотра находятся параметры страницы, масштаб и полноэкранный режим. Селектор масштаба и нижняя панель отображают один масштаб документа; его изменение не меняет форматирование текста.

Порядок меню и размещение в сетке

Определите общий MenuConfig с идентификаторами меню Docs, затем примените его в выбранном режиме:

import type { MenuConfig } from '@univerjs/ui'const menu: MenuConfig = {  'ribbon.start.format': { order: -1 },  'doc.command.set-inline-format-bold': {    order: 0,    gridLayout: { row: 2, column: 2 },  },  'doc.command.set-inline-format-italic': {    gridLayout: { row: 2, column: 1 },  },}

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

import { UniverUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverUIPlugin, {  ribbonType: 'grid',  menu,})

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import { createUniver } from '@univerjs/presets'const { univerAPI } = createUniver({  presets: [    UniverDocsCorePreset({      ribbonType: 'grid',      menu,    }),  ],})

После инициализации обновляйте существующий экземпляр через updateMenuConfig():

import '@univerjs/ui/facade'univerAPI.updateMenuConfig(menu)

order сортирует элементы одного уровня по возрастанию. gridLayout действует только для сетки Ribbon; координаты начинаются с 1 внутри каждой группы из двух строк. Обновления сохраняют неуказанные свойства и сразу обновляют интерфейс. В режиме плагинов передайте menu в UniverUIPlugin и импортируйте @univerjs/ui/facade перед использованием Facade. Поля и примеры пользовательских кнопок приведены в руководстве по размещению меню.

Параметры вставки

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

В настольном Ribbon меню Вставить находится рядом с отменой и повтором и скрывается при редактировании текста фигуры. Подменю Специальная вставка находится в группе форматирования контекстного меню как на компьютере, так и на мобильном устройстве.

Поля колонтитулов

В традиционных документах редактирование колонтитула открывает контекстный Ribbon для вставки, навигации, настройки первой, чётных и нечётных страниц и положения. Можно вставить текущий номер страницы, число страниц или локализованные дату и время. Поля страниц отображают значение для каждой страницы. Автоматическое обновление даты/времени создаёт поле; без него вставляется фиксированный текст. Поля даты/времени обновляются при открытии документа или командой Обновить поля, а не непрерывно как часы. Современные документы не используют страничные колонтитулы.

Структура документа

Панель слева служит для перехода к заголовкам, а не для вставки оглавления в текст. Без toc она включена в документах Modern и выключена в Traditional. Значение true или false переопределяет этот выбор. При нехватке места или пересечении с таблицей панель сворачивается и возвращается, когда место освобождается.

Добавьте параметр в существующую инициализацию, не регистрируя плагин повторно.

import { UniverDocsUIPlugin } from '@univerjs/docs-ui'univer.registerPlugin(UniverDocsUIPlugin, { toc: true })

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import { createUniver } from '@univerjs/presets'const { univerAPI } = createUniver({  presets: [UniverDocsCorePreset({ container: 'app', toc: true })],})

Сворачивание разделов

В документах Modern (documentStyle.documentFlavor: DocumentFlavor.MODERN) рядом с заголовками уровней 1–5, имеющими содержимое раздела, показан треугольник. При сворачивании заголовок остаётся, а содержимое до следующего заголовка того же или более высокого уровня скрывается, включая вложенные заголовки, таблицы и изображения. У каждой ячейки таблицы и колонки Modern своя иерархия.

Эта функция не зависит от toc. В документах Traditional и встроенных текстовых редакторах таких элементов нет. При раскрытии родителя вложенные заголовки сохраняют своё состояние.

IParagraph.headingCollapsed сохраняется в снимке Univer. Только true сворачивает раздел. Содержимое остаётся в снимке; состояние поддерживает отмену, повтор и совместное редактирование и общее для всех редакторов. Выделение в скрытом тексте переходит к видимому заголовку. Сохранение при импорте и экспорте Office не гарантируется.

Для изменения из кода выполните зарегистрированную команду с ID документа и стабильным paragraphId из снимка. Для раскрытия задайте collapsed: false.

import { SetHeadingCollapsedCommand } from '@univerjs/docs'const changed = await univerAPI.executeCommand(SetHeadingCollapsedCommand.id, {  unitId: documentId,  paragraphId: headingParagraphId,  collapsed: true,})

Команда возвращает false, если состояние не изменилось или цель недопустима: документ Traditional, заголовок скрыт предком, раздел пуст при сворачивании или нет права редактирования. См. контракт команды.