Общий API

Доступный в Univer Facade API зависит от типа документа. В этом разделе представлен общий Facade API, применимый ко всем типам документов.

Импорт

import { FUniver } from '@univerjs/core/facade'const univerAPI = FUniver.newAPI(univer)

Основные понятия

Команды

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

Команды

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

Прослушивание команд

Univer позволяет прослушивать команды до и после их выполнения:

• Event.BeforeCommandExecute: выполняет пользовательскую логику перед выполнением команды.
• Event.CommandExecuted: выполняет пользовательскую логику после выполнения команды.

Прослушивание команд до выполнения

До выполнения передайте Event.BeforeCommandExecute в FUniver.addEvent, чтобы зарегистрировать обработчик предварительной обработки.

При запуске команды будет выполнена логика обработчика предварительной обработки.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, type, params }) => {  // Custom logic executed before the command is executed})

Чтобы предотвратить выполнение команды, установите event.cancel в true в обработчике.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {  event.cancel = true})

Прослушивание команд после выполнения

После выполнения передайте Event.CommandExecuted в FUniver.addEvent, чтобы зарегистрировать обработчик постобработки.

После выполнения команды будет запущена логика обработчика постобработки.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, type, params }) => {  // Custom logic executed after the command is executed})

Отмена прослушивания

Метод регистрации обработчика команды возвращает объект IDisposable, который можно уничтожить вызовом IDisposable.dispose.

Рекомендуется удалять обработчики, которые больше не используются: это повышает надёжность приложения.

const univerAPI = FUniver.newAPI(univer)// Register a listenerconst disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, () => {  // custom preprocessing logic before the command is executed})// Example: Destroy the listener after 1 secondsetTimeout(() => {  // Destroy the listener  disposable.dispose()}, 1000)

Выполнение команд

Если известны идентификатор команды и необходимые параметры, команду можно выполнить методом FUniver.executeCommand.

Например, задать значение ячейки A1 можно командой sheet.command.set-range-values:

const univerAPI = FUniver.newAPI(univer)// Execute the commanduniverAPI.executeCommand('sheet.command.set-range-values', {  value: { v: 'Hello, Univer!' },  range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 },})

API событий

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

Категории событий

Полный список событий: /reference/facade/events

1. События буфера обмена

   • BeforeClipboardChange: срабатывает перед изменением содержимого буфера; изменение можно отменить, задав params.cancel = true
   • BeforeClipboardPaste: срабатывает перед вставкой; её можно отменить, задав params.cancel = true
   • ClipboardChanged: срабатывает после изменения буфера и предоставляет его новое содержимое
   • ClipboardPasted: срабатывает после вставки и предоставляет вставленное содержимое

2. События выделения

   • SelectionChanged: срабатывает при изменении выделения и предоставляет сведения о новом диапазоне
   • SelectionMoveStart: срабатывает в начале перемещения выделения и полезно для пользовательских эффектов
   • SelectionMoveEnd: срабатывает в конце перемещения и предоставляет итоговый диапазон
   • SelectionMoving: срабатывает во время перемещения и полезно для обновления интерфейса в реальном времени
   • DragOver: срабатывает при перетаскивании над ячейками
   • Drop: срабатывает при отпускании перетаскиваемого содержимого

3. События ячеек

   • CellClicked: срабатывает при щелчке по ячейке и предоставляет сведения о её положении и содержимом
   • CellHover: срабатывает при наведении на ячейку и полезно для показа подсказок
   • CellPointerDown: срабатывает при нажатии указателя на ячейке и используется для начала перетаскивания или выделения
   • CellPointerUp: срабатывает при отпускании указателя и используется для завершения операций
   • CellPointerMove: срабатывает при перемещении указателя над ячейками

4. События листа

   • SheetValueChanged: срабатывает при изменении значений и предоставляет изменённый диапазон и новые значения
   • SheetZoomChanged: срабатывает при изменении масштаба и предоставляет его новое значение
   • SheetSkeletonChanged: срабатывает при изменении структуры листа, например при вставке или удалении строк и столбцов
   • BeforeSheetEditStart: срабатывает перед началом редактирования ячейки и позволяет запретить редактирование
   • SheetEditStarted: срабатывает в начале редактирования и полезно для настройки редактора
   • BeforeSheetEditEnd: срабатывает перед завершением редактирования и может использоваться для проверки содержимого
   • SheetEditEnded: срабатывает после завершения редактирования и предоставляет изменённое значение
   • SheetEditChanging: срабатывает во время редактирования и полезно для проверки или форматирования в реальном времени
   • Scroll: срабатывает при прокрутке листа и предоставляет сведения о положении прокрутки
   • CrosshairHighlightColorChanged: срабатывает при изменении цвета перекрёстной подсветки
   • CrosshairHighlightEnabledChanged: срабатывает при включении или отключении перекрёстной подсветки

5. События заголовков

   • RowHeaderClick: срабатывает при щелчке по заголовку строки
   • RowHeaderHover: срабатывает при наведении на заголовок строки
   • ColumnHeaderClick: срабатывает при щелчке по заголовку столбца
   • ColumnHeaderHover: срабатывает при наведении на заголовок столбца

6. События проверки данных

   • BeforeSheetDataValidationAdd: срабатывает перед добавлением правила проверки данных
   • SheetDataValidationChanged: срабатывает при изменении правил проверки данных
   • SheetDataValidatorStatusChanged: срабатывает при изменении статуса проверки данных

7. События комментариев

   • BeforeCommentAdd: срабатывает перед добавлением комментария
   • CommentAdded: срабатывает после добавления комментария
   • BeforeCommentUpdate: срабатывает перед обновлением комментария
   • CommentUpdated: срабатывает после обновления комментария
   • BeforeCommentDeleted: срабатывает перед удалением комментария
   • CommentDeleted: срабатывает после удаления комментария

8. События обработки данных

   • SheetBeforeRangeSort: срабатывает перед сортировкой диапазона
   • SheetRangeSorted: срабатывает после сортировки диапазона
   • SheetBeforeRangeFilter: срабатывает перед фильтрацией диапазона
   • SheetRangeFiltered: срабатывает после фильтрации диапазона
   • BeforePivotTableAdd: срабатывает перед добавлением сводной таблицы
   • PivotTableAdded: срабатывает после добавления сводной таблицы

Использование событий

Подписываться на события можно методом addEvent объекта univerAPI. Базовый шаблон выглядит так:

univerAPI.addEvent(univerAPI.Event.EventName, (params) => {  // Handle event parameters})

Пример: отслеживание щелчков по ячейкам

univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {  const { worksheet, workbook, row, column } = params  console.log(`Cell clicked at row ${row}, column ${column}`)})

Пример: отслеживание операций с буфером обмена

univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {  const { text, html } = params  // If you want to cancel the clipboard paste  params.cancel = true})

Пример: отслеживание изменения выделения

univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params) => {  const { worksheet, workbook, selections } = params  console.log('Selection changed:', selections)})

Отмена подписки на события

Обработчики событий возвращают объект IDisposable, с помощью которого можно удалить обработчик, когда он больше не нужен:

const disposable = univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {  // Handle value changes})// Later, when you want to remove the listener:disposable.dispose()

Рекомендации

1. Всегда удаляйте ненужные обработчики событий, чтобы избежать утечек памяти
2. Выбирайте событие под конкретную задачу: специализированные события предпочтительнее общих
3. Не перегружайте обработчики событий, чтобы сохранить производительность
4. Если нужно отменить стандартное действие, используйте BeforeClipboardChange и аналогичные предварительные события

Отмена и повтор действий

Отмена

await univerAPI.undo()

Повтор

await univerAPI.redo()

Системный буфер обмена

Методы FUniver.copy() и FUniver.paste() позволяют читать данные из системного буфера обмена и записывать их туда.

Пример: копирование и вставка диапазона листа

// Prevent failure due to loss of focus when executing copy and paste code in the console,// this example listens for the cell click event and executes the copy and paste code.univerAPI.addEvent(univerAPI.Event.CellClicked, async (params) => {  const fWorkbook = univerAPI.getActiveWorkbook()  const fWorksheet = fWorkbook.getActiveSheet()  // Copy the range A1:B2 to the clipboard  const fRange = fWorksheet.getRange('A1:B2')  fRange.activate().setValues([    [1, 2],    [3, 4],  ])  await univerAPI.copy()  // Paste the copied content to the range C1:D2  const fRange2 = fWorksheet.getRange('C1')  fRange2.activate()  await univerAPI.paste()  // Check the pasted content  console.log(fWorksheet.getRange('C1:D2').getValues()) // [[1, 2], [3, 4]]})

Функции буфера обмена также можно вызывать через систему команд:

import { CopyCommand, PasteCommand } from '@univerjs/ui'// CopyuniverAPI.executeCommand(CopyCommand.id)// PasteuniverAPI.executeCommand(PasteCommand.id)

UI

Сведения о расширении интерфейса Univer см. в следующем разделе:

• Расширение холста

WebSocket

Facade API предоставляет удобный метод createSocket, который создаёт WebSocket по переданному URL. После этого можно прослушивать события открытия, получения сообщения, закрытия и ошибки, отправлять сообщения методом send и закрывать соединение методом close.

При установке через предустановки можно напрямую использовать univerAPI.createSocket(url). При установке отдельных пакетов необходимо установить зависимость @univerjs/network и зарегистрировать плагин UniverNetworkPlugin.

// ... Omits other plugin importsimport { UniverNetworkPlugin } from '@univerjs/network'// ... Omits other facade importsimport '@univerjs/network/facade'// ... Omits other plugin registrationsuniver.registerPlugin(UniverNetworkPlugin)

Простой пример:

// Replace the URL with the address of your own WebSocket serviceconst ws = univerAPI.createSocket('ws://47.100.177.253:8449/ws')ws.open$.subscribe(() => {  console.log('websocket opened')  ws.send('hello')})ws.message$.subscribe((message) => {  console.log('websocket message', message)  const content = JSON.parse(message.data).content  if (!content.includes('command')) {    return  }  const commandInfo = JSON.parse(content)  const { command, options } = commandInfo  const { id, params } = command  // Upon receiving collaborative data, it is locally saved  univerAPI.executeCommand(id, params, options)})ws.close$.subscribe(() => {  console.log('websocket closed')})ws.error$.subscribe((error) => {  console.log('websocket error', error)})univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, type, params, options }) => {  // Only synchronize local mutations  if (    type !== univerAPI.Enum.CommandType.MUTATION ||    options?.fromCollab ||    options?.onlyLocal ||    id === 'doc.mutation.rich-text-editing'  ) {    return  }  const commandInfo = JSON.stringify({ command: { id, type, params }, options: { fromCollab: true } })  ws.send(commandInfo)})

Примечание: при запуске Univer обязательно укажите unitID. Без unitID совместная работа не будет работать.

Регистрация формулы

Facade API позволяет быстро регистрировать пользовательские формулы в текущем экземпляре Univer.

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

// Registered formulas support lambda functionsconst formulaEngine = univerAPI.getFormula()formulaEngine.registerFunction(  'CUSTOMSUM',  (...variants) => {    let sum = 0    const last = variants[variants.length - 1]    if (last.isLambda && last.isLambda()) {      variants.pop()      const variantsList = variants.map((variant) => (Array.isArray(variant) ? variant[0][0] : variant))      sum += last.executeCustom(...variantsList).getValue()    }    for (const variant of variants) {      sum += Number(variant) || 0    }    return sum  },  'Adds its arguments',)// Use the function in a cellconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const cellA1 = fWorksheet.getRange('A1')cellA1.setValue(1)const cellA2 = fWorksheet.getRange('A2')cellA2.setValue(2)const cellA3 = fWorksheet.getRange('A3')cellA3.setValue({ f: '=CUSTOMSUM(A1,A2,LAMBDA(x,y,x*y))' })// A3 will display: 5formulaEngine.calculationEnd((functionsExecutedState) => {  if (functionsExecutedState === 3) {    console.log(cellA3.getValue()) // 5  }})

Чтобы отменить регистрацию формулы, вызовите метод dispose.

const functionDisposable = formulaEngine.registerFunction({  // calculate})// Unregister the functionfunctionDisposable.dispose()

Чтобы добавить полноценные локализованные тексты и описание, настройте поля locales и description, как показано ниже.

formulaEngine.registerFunction(  'CUSTOMSUM',  (...variants) => {    let sum = 0    const last = variants[variants.length - 1]    if (last.isLambda && last.isLambda()) {      variants.pop()      const variantsList = variants.map((variant) => (Array.isArray(variant) ? variant[0][0] : variant))      sum += last.executeCustom(...variantsList).getValue()    }    for (const variant of variants) {      sum += Number(variant) || 0    }    return sum  },  {    description: {      functionName: 'CUSTOMSUM',      description: 'formulaCustom.CUSTOMSUM.description',      abstract: 'formulaCustom.CUSTOMSUM.abstract',      functionParameter: [        {          name: 'formulaCustom.CUSTOMSUM.functionParameter.number1.name',          detail: 'formulaCustom.CUSTOMSUM.functionParameter.number1.detail',          example: 'A1:A20',          require: 1,          repeat: 0,        },        {          name: 'formulaCustom.CUSTOMSUM.functionParameter.number2.name',          detail: 'formulaCustom.CUSTOMSUM.functionParameter.number2.detail',          example: 'B2:B10',          require: 0,          repeat: 1,        },      ],    },    locales: {      zhCN: {        formulaCustom: {          CUSTOMSUM: {            description: '将单个值、单元格引用或是区域相加，或者将三者的组合相加。',            abstract: '求参数的和',            functionParameter: {              number1: {                name: '数值1',                detail:                  '要相加的第一个数字。 该数字可以是 4 之类的数字，B6 之类的单元格引用或 B2:B8 之类的单元格范围。',              },              number2: {                name: '数值2',                detail: '这是要相加的第二个数字。 可以按照这种方式最多指定 255 个数字。',              },            },          },        },      },      enUS: {        formulaCustom: {          CUSTOMSUM: {            description: `You can add individual values, cell references or ranges or a mix of all three.`,            abstract: `Adds its arguments`,            functionParameter: {              number1: {                name: 'number1',                detail:                  'The first number you want to add. The number can be like 4, a cell reference like B6, or a cell range like B2:B8.',              },              number2: {                name: 'number2',                detail: 'This is the second number you want to add. You can specify up to 255 numbers in this way.',              },            },          },        },      },    },  },)

Примечание

• func задаёт алгоритм вычисления формулы и сопоставление имени. Входной параметр содержит введённые пользователем данные: число, строку, логическое значение или массив.
• description задаёт описание пользовательской формулы.
• В locales можно настроить несколько языков. Правила именования см. в LocaleType. Переводы нескольких формул можно добавить в functionList. Подробное описание полей приведено в разделе Добавление формул в Formula Engine.

API перечислений

Facade API предоставляет часто используемые типы перечислений. Например:

console.log(univerAPI.Enum)console.log(univerAPI.Enum.UniverInstanceType.UNIVER_SHEET)console.log(univerAPI.Enum.LifecycleStages.Rendered)

API вспомогательных методов

Facade API предоставляет часто используемые вспомогательные методы. Например:

console.log(univerAPI.Util)console.log(univerAPI.Util.tools.chatAtABC(10))console.log(univerAPI.Util.tools.ABCatNum('K'))