在Univer中使用自定义组件

📊 Univer Sheet

Univer提供了多种方式来集成自定义组件，使您能够扩展和定制Univer的功能。本指南将介绍几种常用的方法。

1. 在侧边栏中使用自定义组件

openSiderbar 方法 0.3.0+

使用 workbook.openSiderbar(params:ISidebarMethodOptions) 方法可以在Univer界面中打开一个包含自定义组件的侧边栏。
ISidebarMethodOptions (opens in a new tab): 完整的参数定义

import { ComponentManager } from '@univerjs/ui';
 
const injector = univer.__getInjector();
const componentManager = injector.get(ComponentManager);
 
// 你应该在合适的时机（比如univer加载完成）注册组件
componentManager.register(
  'mySidebarComponentKey',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容</div>
);
 
const sidebar = workbook.openSiderbar({
  header: { title: '我的侧边栏' },
  children: { label: 'mySidebarComponentKey' },
  onClose: () => {
      console.log('close');
  },
  width: 360,
});
 
// 稍后关闭侧边栏
sidebar.dispose();

2. 在对话框中使用自定义组件

openDialog 方法 0.3.0+

使用 workbook.openDialog(params: IDialogPartMethodOptions) 方法可以打开一个包含自定义组件的对话框。
IDialogPartMethodOptions (opens in a new tab): 完整的参数定义

import { ComponentManager } from '@univerjs/ui';
 
const injector = univer.__getInjector();
const componentManager = injector.get(ComponentManager);
 
// 你应该在合适的时机（比如univer加载完成）注册组件
componentManager.register(
  'myDialogComponentKey',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容</div>
);
 
const dialog = workbook.openDialog({
  // unique id
  id: 'myDialog',
  draggable: true,
  width: 300,
  title: { title: 'Dialog title' },
  children: { 
    label: 'myDialogComponentKey'
  },
  destroyOnClose: true,
  preservePositionOnDestroy: true,
  onClose: () => {},
});
 
// 稍后关闭对话框
dialog.dispose();

3. 将弹出框附加到单元格 0.2.10+

attachPopup 方法

Popup 是一个cell上面依附的临时dom，一般用于显示一些临时的状态信息，不支持持久化存储。
使用 range.attachPopup() 方法可以将自定义弹出框附加到特定的单元格范围。
Popup 会吸附在单元的四边，如果被遮挡，会自动调整位置和方向。

import { ComponentManager } from '@univerjs/ui';
const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = sheet.getRange(0, 0, 10, 10); // A1:J10
 
const injector = univer.__getInjector();
const componentManager = injector.get(ComponentManager);
 
// 你应该在合适的时机（比如univer加载完成）注册组件，组件只需注册一次
componentManager.register(
  'myPopup',
  ({ popup }) => <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容 {popup.extraProps.label}</div>,
  // 如果组件是React组件，需要设置框架为'react'
  // 如果组件是Vue3组件，需要设置框架为'vue3'
  { framework: 'react' }
);
 
// 将弹出窗口附加到范围的第一个单元格
// 如果 disposeable 为 null，则表示 popup 添加失败
const disposeable = range.attachPopup({
  // componentKey 必须是一个组件或已注册组件的键
    componentKey: 'myPopup',
    // 这是组件的数据, 可以传递给组件
    extraProps: {
      label: 'hahah',
    },
});
 
// 移除弹出框
disposable.dispose();

Vue3 Example

import { ComponentManager } from '@univerjs/ui';
const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = sheet.getRange(0, 0, 10, 10); // A1:J10
 
const injector = univer.__getInjector();
const componentManager = injector.get(ComponentManager);
 
const vue3Component = defineComponent({
  setup(props) {
    return () => <div style={{ width: 100, height: 100, background: '#fff' }}>Popup content {props.popup.extraProps.label}</div>;
  },
});
 
// 你应该在合适的时机（比如univer加载完成）注册组件，组件只需注册一次
componentManager.register(
  'myPopup',
  vue3Component,
  // 如果组件是React组件，需要设置框架为'react'
  // 如果组件是Vue3组件，需要设置框架为'vue3'
  { framework: 'vue3' }
);
 
// 将弹出窗口附加到范围的第一个单元格
// 如果 disposeable 为 null，则表示 popup 添加失败
const disposable = range.attachPopup({
  // componentKey 必须是一个组件或已注册组件的键
    componentKey: 'myPopup',
    // 这是组件的数据, 可以传递给组件
    extraProps: {
      label: 'hahah',
    },
});
 
// Remove the popup
disposable.dispose();

4. 添加浮动DOM到工作表 0.2.10+

addFloatDomToPosition 方法

使用该方法前需要安装 @univerjs/sheets-drawing-ui 插件。
浮动DOM是悬浮在sheet上的可拖动组件，同时支持持久化存储。
需要在 univer 渲染完成之后调用。
componentKey 必须传已注册的组件id 或者react/vue3组件如果是 vue3组件必须标明isVue3。
完整的参数定义 (opens in a new tab)

demo (opens in a new tab)

import { ComponentManager } from '@univerjs/ui';
const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// 你应该在合适的时机（比如univer加载完成）注册组件
componentManager.register(
  'myFloatDom',
  ({ data }) => (
        <div style={{ width: '100%', height: '100%', background: '#fff' }}>
            popup content
            {data?.label}
        </div>
    ),
);
 
// 添加一个浮动dom
// 如果 disposeable 为 null，则表示浮动 DOM 添加失败
const disposeable = worksheet.addFloatDomToPosition({
    // componentKey 必须是一个组件或已注册组件的键
    componentKey: myFloatDom,
    // 如果 componentKey 是一个 Vue3 组件，必须将 isVue3 设置为 true
    // isVue3: true,
    initPosition: {
        startX: 100,
        endX: 200,
        startY: 100,
        endY: 200,
    },
 
    // 这是组件的数据
    data: {
        label: 'hahah',
    },
});
 
// 移除浮动dom
disposeable.dispose();

5. 附加警告弹出框 0.3.0+

attachAlertPopup 方法

使用 range.attachAlertPopup() 方法可以在指定范围的起始单元格附加一个警告弹出框。

const range = sheet.getRange("A1:B2");
const alertDisposable = range.attachAlertPopup({
  key: "myAlert",
  title: "这是一个警告！",
  message: "这是一个警告！",
  width: 300,
  height: 200,
  // 0: 信息
  // 1: 警告
  // 2: 错误
  type: 0
});
 
// 稍后移除警告
alertDisposable.dispose();

注意事项

在使用这些方法时，请确保Univer已经完成渲染。
对于需要注册的组件，请确保在使用前已正确注册。
使用 dispose() 方法来清理和移除添加的组件，以避免内存泄漏。
对于Vue3组件，需要在选项中设置 isVue3: true。

通过这些方法，您可以灵活地在Univer中集成各种自定义组件，从而增强和定制Univer的功能。

冻结默认样式