Class: FUniver

get Enum(): FEnum

get Event(): FEventName

get Util(): FUtil

addEvent<T>(event, callback): IDisposable

// Add life cycle changed event listener
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
  const { stage } = params;
  console.log('life cycle changed', params);
});
 
// Remove the event listener, use `disposable.dispose()`

addFonts(fonts): void

univerAPI.addFonts([
  {
    value: 'CustomFont1',
    label: 'Custom Font 1',
    category: 'sans-serif',
  },
  {
    value: 'CustomFont2',
    label: 'Custom Font 2',
    category: 'serif',
  },
]);

addWatermark(type, config): FUniver

univerAPI.addWatermark('text', {
  content: 'Univer',
  fontSize: 20,
  repeat: true,
});

addWatermark(type, config): FUniver

univerAPI.addWatermark('image', {
  url: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',
  width: 100,
  height: 100,
});

addWatermark(type, config): FUniver

copy(): Promise<boolean>

// 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]]
});

createMenu(menuItem): FMenu

// Univer Icon can be viewed at https://docs.univer.ai/icons
import { SmileIcon } from '@univerjs/icons'
 
// Create a custom menu with an univer icon
univerAPI.registerComponent('custom-menu-icon', SmileIcon);
univerAPI.createMenu({
  id: 'custom-menu',
  icon: 'custom-menu-icon',
  title: 'Custom Menu',
  tooltip: 'Custom Menu Tooltip',
  action: () => {
    console.log('Custom Menu Clicked');
  },
}).appendTo('ribbon.start.others');
 
// Or
// Create a custom menu with an image icon
univerAPI.registerComponent('custom-menu-icon', () => {
  return <img src="https://avatars.githubusercontent.com/u/61444807?s=48&v=4" alt="" style={{ width: '16px', height: '16px' }} />;
});
univerAPI.createMenu({
  id: 'custom-menu',
  icon: 'custom-menu-icon',
  title: 'Custom Menu',
  tooltip: 'Custom Menu Tooltip',
  action: () => {
    console.log('Custom Menu Clicked');
  },
}).appendTo('ribbon.start.others');
 
// Or
// Create a custom menu without an icon
univerAPI.createMenu({
  id: 'custom-menu',
  title: 'Custom Menu',
  tooltip: 'Custom Menu Tooltip',
  action: () => {
    console.log('Custom Menu Clicked');
  },
}).appendTo('ribbon.start.others');

createSubmenu(submenuItem): FSubmenu

// Create two leaf menus.
const menu1 = univerAPI.createMenu({
  id: 'submenu-nested-1',
  title: 'Item 1',
  action: () => {
    console.log('Item 1 clicked');
  }
});
const menu2 = univerAPI.createMenu({
  id: 'submenu-nested-2',
  title: 'Item 2',
  action: () => {
    console.log('Item 2 clicked');
  }
});
 
// Add the leaf menus to a submenu.
const submenu = univerAPI.createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })
  .addSubmenu(menu1)
  .addSeparator()
  .addSubmenu(menu2);
 
// Create a root submenu append to the `contextMenu.others` section.
univerAPI.createSubmenu({ id: 'custom-submenu', title: 'Custom Submenu' })
  .addSubmenu(submenu)
  .appendTo('contextMenu.others');

createTextFinderAsync(text): Promise<FTextFinder>

// Assume the current sheet is empty sheet.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// Set some values to the range A1:D10.
const fRange = fWorksheet.getRange('A1:D10');
fRange.setValues([
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
  [6, 7, 8, 9],
  [7, 8, 9, 10],
  [8, 9, 10, 11],
  [9, 10, 11, 12],
  [10, 11, 12, 13]
]);
 
// Create a text-finder to find the text '5'.
const textFinder = await univerAPI.createTextFinderAsync('5');
 
// Find all cells that contain the text '5'.
const matchCells = textFinder.findAll();
matchCells.forEach((cell) => {
  console.log(cell.getA1Notation()); // D2, C3, B4, A5
});

createUniverDoc(data): FDocument

createUniverSheet(data): FWorkbook

createWorkbook(data, options?): FWorkbook

const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' });
console.log(fWorkbook);

const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false });
console.log(fWorkbook);

customizeColumnHeader(cfg): void

customizeRowHeader(cfg): void

deleteWatermark(): FUniver

univerAPI.deleteWatermark();

disposeUnit(unitId): boolean

const fWorkbook = univerAPI.getActiveWorkbook();
const unitId = fWorkbook?.getId();
 
if (unitId) {
  univerAPI.disposeUnit(unitId);
}

executeCommand<P, R>(
   id, 
   params?, 
options?): Promise<R>

univerAPI.executeCommand('sheet.command.set-range-values', {
  value: { v: "Hello, Univer!" },
  range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }
});

exportDOCXBySnapshotAsync(snapshot): Promise<File>

const snapshot = univerAPI.getActiveDocument().save();
const file = await univerAPI.exportDOCXBySnapshotAsync(snapshot);
downloadFile(file, 'univer', 'docx');

exportDOCXByUnitIdAsync(unitId): Promise<File>

const unitId = univerAPI.getActiveWorkbook().getId();
const file = await univerAPI.exportDOCXByUnitIdAsync(unitId);
downloadFile(file, 'univer', 'docx');

exportXLSXBySnapshot(snapshot): Promise<File>

exportXLSXBySnapshotAsync(snapshot): Promise<File>

import { downloadFile } from '@univerjs-pro/exchange-client';
 
const fWorkbook = univerAPI.getActiveWorkbook();
const snapshot = fWorkbook.save();
const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot);
// or with server-side calculation enabled
// const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot, { enableServerCalculation: true });
 
// Download the file
downloadFile(file, 'univer', 'xlsx');

exportXLSXByUnitId(unitId): Promise<File>

exportXLSXByUnitIdAsync(unitId): Promise<File>

import { downloadFile } from '@univerjs-pro/exchange-client';
 
const fWorkbook = univerAPI.getActiveWorkbook();
const unitId = fWorkbook.getId();
const file = await univerAPI.exportXLSXByUnitIdAsync(unitId);
// or with server-side calculation enabled
// const file = await univerAPI.exportXLSXByUnitIdAsync(unitId, { enableServerCalculation: true });
 
// Download the file
downloadFile(file, 'univer', 'xlsx');

fireEvent<T>(event, params): boolean

this.fireEvent(univerAPI.Event.LifeCycleChanged, params);

generatePivotTable<T>(data, CustomDataFieldManager?): FGenericPivotTable

const sourceData = [
 ["区域", "省份", "城市", "类别", "商品", "数量", "销售日期"],
 ["西部", "河南", "洛阳", "fruit", "葡萄", 38, "2021-06-30"],
 ["北部", "辽宁", "沈阳", "fruit", "葡萄", 45, "2023-08-31"]
]
const pivot = univerAPI.generatePivotTable(sourceData);
pivot.addFieldWithName('数量', 3);
const res = pivot.getResultByCalculate();
console.log('debugger', pivot, res);

getActiveDocument(): FDocument

getActiveSheet(): Nullable<{
  workbook: ...;
  worksheet: ...;
}>

const target = univerAPI.getActiveSheet();
if (!target) return;
const { workbook, worksheet } = target;
console.log(workbook, worksheet);

getActiveUniverSheet(): FWorkbook

getActiveWorkbook(): FWorkbook

const fWorkbook = univerAPI.getActiveWorkbook();
console.log(fWorkbook);

getCollaboration(): FCollaboration

const collaboration = univerAPI.getCollaboration();

getCommandSheetTarget(commandInfo): Nullable<{
  workbook: ...;
  worksheet: ...;
}>

univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
  const { options, ...commandInfo } = event;
  const target = univerAPI.getCommandSheetTarget(commandInfo);
  if (!target) return;
  const { workbook, worksheet } = target;
  console.log(workbook, worksheet);
});

getComponentManager(): ComponentManager

const componentManager = univerAPI.getComponentManager();
console.log(componentManager);

getCrosshairHighlightColor(): string

console.log(univerAPI.getCrosshairHighlightColor());

getCrosshairHighlightEnabled(): boolean

console.log(univerAPI.getCrosshairHighlightEnabled());

getCurrentLifecycleStage(): LifecycleStages

const stage = univerAPI.getCurrentLifecycleStage();
console.log(stage);

getFormula(): FFormula

getHooks(): FHooks

getPermission(): FPermission

getProtectedRangeShadowStrategy(): "always" | "non-editable" | "non-viewable" | "none"

const currentStrategy = univerAPI.getProtectedRangeShadowStrategy();
console.log(currentStrategy); // 'none', 'always', 'non-editable', or 'non-viewable'

getProtectedRangeShadowStrategy$(): Observable<... | ... | ... | ...>

const subscription = univerAPI.getProtectedRangeShadowStrategy$().subscribe((strategy) => {
    console.log('Global strategy changed to:', strategy);
    // Update UI or perform other actions
});
 
// Later, unsubscribe to clean up
subscription.unsubscribe();

getSheetHooks(): FSheetHooks

getSheetTarget(unitId, subUnitId): Nullable<{
  workbook: ...;
  worksheet: ...;
}>

const unitId = 'workbook-01';
const subUnitId = 'sheet-0001';
const target = univerAPI.getSheetTarget(unitId, subUnitId);
if (!target) return;
const { workbook, worksheet } = target;
console.log(workbook, worksheet);

getShortcut(): FShortcut

const fShortcut = univerAPI.getShortcut();
 
// Disable shortcuts of Univer
fShortcut.disableShortcut();
 
// Enable shortcuts of Univer
fShortcut.enableShortcut();
 
// Trigger a shortcut
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1');
fRange.activate();
fRange.setValue('Hello Univer');
console.log(fRange.getCellStyle().bold); // false
const pseudoEvent = new KeyboardEvent('keydown', {
  key: 'b',
  ctrlKey: true,
  keyCode: univerAPI.Enum.KeyCode.B
});
const ifShortcutItem = fShortcut.triggerShortcut(pseudoEvent);
if (ifShortcutItem) {
  const commandId = ifShortcutItem.id;
  console.log(fRange.getCellStyle().bold); // true
}

getUniverDoc(id): FDocument

getUniverSheet(id): FWorkbook

const fWorkbook = univerAPI.getUniverSheet('Sheet1');
console.log(fWorkbook);
 
const fWorkbook = univerAPI.getWorkbook('Sheet1');
console.log(fWorkbook);

getURL(): URL

console.log(univerAPI.getURL());

getUserManager(): FUserManager

getWorkbook(id): FWorkbook

importDOCXToSnapshot(file): Promise<IDocumentData>

importDOCXToSnapshotAsync(file): Promise<IDocumentData>

// Accepts a File object
const snapshot = await univerAPI.importDOCXToSnapshotAsync(file);
// Or accepts a URL to a remote file
// const snapshot = await univerAPI.importDOCXToSnapshotAsync('https://example.com/filename.docx');
console.log('Snapshot created:', snapshot);

importDOCXToUnitId(file): Promise<string>

importDOCXToUnitIdAsync(file): Promise<string>

// Accepts a File object
const unitId = await univerAPI.importDOCXToUnitIdAsync(file);
// Or accepts a URL to a remote file
// const unitId = await univerAPI.importDOCXToUnitIdAsync('https://example.com/filename.docx');
 
const url = new URL(window.location.href);
const unit = url.searchParams.get('unit');
url.searchParams.set('unit', unitId);
url.searchParams.set('type', "1"); // The meaning of "1" is String(UniverInstanceType.UNIVER_DOC)
 
// Open the unit in the new window
window.open(url.toString(), '_blank');

importXLSXToSnapshot(file): Promise<IWorkbookData>

importXLSXToSnapshotAsync(file): Promise<IWorkbookData>

// Accepts a File object
const snapshot = await univerAPI.importXLSXToSnapshotAsync(file);
// Or accepts a URL to a remote file
// const snapshot = await univerAPI.importXLSXToSnapshotAsync('https://example.com/filename.xlsx');
console.log('Snapshot created:', snapshot); // see more: https://docs.univer.ai/en-US/guides/sheets/getting-started/workbook-data
 
// Create a new workbook with the snapshot
univerAPI.createWorkbook(snapshot);

importXLSXToUnitId(file): Promise<string>

importXLSXToUnitIdAsync(file): Promise<string>

// Accepts a File object
const unitId = await univerAPI.importXLSXToUnitIdAsync(file);
// Or accepts a URL to a remote file
// const unitId = await univerAPI.importXLSXToUnitIdAsync('https://example.com/filename.xlsx');
 
// Utilize automatic data loading in conjunction with collaborative editing. https://docs.univer.ai/en-US/guides/sheets/features/collaboration#loading-collaborative-documents
const url = new URL(window.location.href);
const unit = url.searchParams.get('unit');
url.searchParams.set('unit', unitId);
url.searchParams.set('type', "2"); // The meaning of "2" is String(UniverInstanceType.UNIVER_SHEET)
console.log('Unit URL:', url.toString());
 
// Open the unit in the new window
window.open(url.toString(), '_blank');

isUIVisible(key): boolean

// Hide header
univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, false);
console.log(univerAPI.isUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER)); // false

loadLocales(locale, locales): void

univerAPI.loadLocales('esES', {
  'Hello World': 'Hola Mundo',
});

loadServerUnit(
   unitId, 
   unitType, 
subUnitId?): Promise<any>

const unitModel = await univerAPI.loadServerUnit('unitId', univerAPI.Enum.UniverInstanceType.UNIVER_SHEET);
console.log(unitModel, unitModel?.getSnapshot());

loadServerUnitOfRevision(
   unitId, 
   unitType, 
rev): Promise<any>

const unitModel = await univerAPI.loadServerUnitOfRevision('unitId', univerAPI.Enum.UniverInstanceType.UNIVER_SHEET, 1);
console.log(unitModel, unitModel?.getSnapshot());

newBlob(): FBlob

const blob = univerAPI.newBlob();

newColor(): ColorBuilder

const color = univerAPI.newColor();

newDataValidation(): FDataValidationBuilder

const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
 
// Create a new data validation rule that requires a number between 1 and 10 fot the range A1:B10
const fRange = fWorksheet.getRange('A1:B10');
const rule = univerAPI.newDataValidation()
  .requireNumberBetween(1, 10)
  .setOptions({
    allowBlank: true,
    showErrorMessage: true,
    error: 'Please enter a number between 1 and 10'
  })
  .build();
fRange.setDataValidation(rule);

newDefinedName(): FDefinedNameBuilder

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setRef('Sheet1!$A$1')
  .setName('MyDefinedName')
  .setComment('This is a comment');
console.log(definedNameBuilder);
fWorkbook.insertDefinedNameBuilder(definedNameBuilder.build());

newParagraphStyle(style?): ParagraphStyleBuilder

const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
const paragraphStyle = univerAPI.newParagraphStyle({ textStyle: { ff: 'Arial', fs: 12, it: univerAPI.Enum.BooleanNumber.TRUE, bl: univerAPI.Enum.BooleanNumber.TRUE } });
richText.insertParagraph(paragraphStyle);
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
range.setRichTextValueForCell(richText);

newParagraphStyleValue(style?): ParagraphStyleValue

const paragraphStyleValue = univerAPI.newParagraphStyleValue();

newRichText(data?): RichTextBuilder

const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
range.setRichTextValueForCell(richText);

newRichTextValue(data): RichTextValue

const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello World\r\n' } });
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
range.setRichTextValueForCell(richTextValue);

newTextDecoration(decoration?): TextDecorationBuilder

const decoration = univerAPI.newTextDecoration();

newTextStyle(style?): TextStyleBuilder

const textStyle = univerAPI.newTextStyle();

newTextStyleValue(style?): TextStyleValue

const textStyleValue = univerAPI.newTextStyleValue();

newTheadComment(): FTheadCommentBuilder

// Create a new comment
const richText = univerAPI.newRichText().insertText('hello univer');
const commentBuilder = univerAPI.newTheadComment()
  .setContent(richText)
  .setPersonId('mock-user-id')
  .setDateTime(new Date('2025-02-21 14:22:22'))
  .setId('mock-comment-id')
  .setThreadId('mock-thread-id');
 
// Add the comment to the cell A1
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const cell = fWorksheet.getRange('A1');
const result = await cell.addCommentAsync(commentBuilder);
console.log(result);

onBeforeCommandExecute(callback): IDisposable

onCommandExecuted(callback): IDisposable

onCommentAdded(callback): IDisposable

onCommentDeleted(callback): IDisposable

onCommentResolved(callback): IDisposable

onCommentUpdated(callback): IDisposable

onUniverSheetCreated(callback): IDisposable

openDialog(dialog): IDisposable

import { Button } from '@univerjs/design';
 
univerAPI.openDialog({
  id: 'mock-dialog-id',
  width: 500,
  title: {
    label: 'Dialog Title',
  },
  children: {
    label: 'Dialog Content',
  },
  footer: {
    title: (
      <>
        <Button onClick={() => { console.log('Cancel clicked') }}>Cancel</Button>
        <Button variant="primary" onClick={() => { console.log('Confirm clicked') }} style={{marginLeft: '10px'}}>Confirm</Button>
      </>
    )
  },
  draggable: true,
  mask: true,
  maskClosable: true,
});

openSidebar(params): IDisposable

univerAPI.openSidebar({
  id: 'mock-sidebar-id',
  width: 300,
  header: {
    label: 'Sidebar Header',
  },
  children: {
    label: 'Sidebar Content',
  },
  footer: {
    label: 'Sidebar Footer',
  },
  onClose: () => {
    console.log('Sidebar closed')
  },
});

openSiderbar(params): IDisposable

paste(): Promise<boolean>

// 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]]
});

pasteIntoSheet(
   htmlContent?, 
   textContent?, 
files?): Promise<boolean>

// Listen for the paste event and call the pasteIntoSheet method
document.addEventListener('paste', async (event) => {
  const htmlContent = event.clipboardData.getData('text/html');
  const textContent = event.clipboardData.getData('text/plain');
  const files = Array.from(event.clipboardData.items)
    .map((item) => item.kind === 'file' ? item.getAsFile() : undefined)
    .filter(Boolean);
  await univerAPI.pasteIntoSheet(htmlContent, textContent, files);
});
 
// Or paste custom data
univerAPI.pasteIntoSheet('<b>Bold Text</b>', 'Bold Text');

redo(): Promise<boolean>

await univerAPI.redo();

registerComponent(
   name, 
   component, 
   options?): IDisposable

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// Register a range loading component
const RangeLoading = () => {
  const divStyle = {
    width: '100%',
    height: '100%',
    backgroundColor: '#fff',
    border: '1px solid #ccc',
    boxSizing: 'border-box' as const,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    textAlign: 'center' as const,
    transformOrigin: 'top left',
  };
 
  return (
    <div style={divStyle}>
      Loading...
    </div>
  );
};
univerAPI.registerComponent('RangeLoading', RangeLoading);
 
// Add the range loading component covering the range A1:C3
const range = fWorksheet.getRange('A1:C3');
const disposeable = fWorksheet.addFloatDomToRange(range, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading');
 
setTimeout(() => {
  disposeable?.dispose();
}, 2000);

registerFunction(config): IDisposable

registerSheetColumnHeaderExtension(unitId, ...extensions): IDisposable

registerSheetMainExtension(unitId, ...extensions): IDisposable

registerSheetRowHeaderExtension(unitId, ...extensions): IDisposable

registerUIPart(key, component): IDisposable

univerAPI.registerUIPart(univerAPI.Enum.BuiltInUIPart.CUSTOM_HEADER, () => React.createElement('h1', null, 'Custom Header'));

runOnServer(
   scriptNameOrId, 
   func, ...
params): Promise<string>

setCrosshairHighlightColor(color): FUniver

univerAPI.setCrosshairHighlightColor('#FF0000');
// or
univerAPI.setCrosshairHighlightColor('rgba(232, 11, 11, 0.2)');

setCrosshairHighlightEnabled(enabled): FUniver

univerAPI.setCrosshairHighlightEnabled(true);