🎉 v0.5.0 版本已发布。查看详情 →
指南Univer Sheets功能核心功能集成自定义组件

在 Univer 中使用自定义组件

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

前置知识：Univer 中的自定义组件

  • 在 Univer 中，我们使用 ComponentManager 来管理自定义DOM组件。
  • 在使用下列的方法时，你需要提前将组件注册好。

注册一个React组件

 
const ReactComponent = (props: any) => {
  console.log('ReactComponent', props);
  return <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容</div>
}
univerAPI.getComponentManager().register(
  'myComponentKey',
  ReactComponent,
);

注册一个Vue3组件

const Vue3Component = defineComponent({
  setup(props) {
    console.log('Vue3Component', props);
    return () => <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容</div>
  }
});
 
univerAPI.getComponentManager().register(
  'myComponentKey',
  Vue3Component,
  {
    framework: 'vue3',
  }
);

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

openSiderbar 方法 0.3.0+

  • 使用 workbook.openSiderbar(params:ISidebarMethodOptions) 方法可以在Univer界面中打开一个包含自定义组件的侧边栏。
  • ISidebarMethodOptions: 完整的参数定义
// 你应该在合适的时机（比如univer加载完成）注册组件
// 这是一个React组件, 如果是vue3组件请查看当前章节最上方的前置知识
univerAPI.getComponentManager().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: 完整的参数定义
// 你应该在合适的时机（比如univer加载完成）注册组件
// 这是一个React组件, 如果是vue3组件请查看当前章节最上方的前置知识
univerAPI.getComponentManager().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 会吸附在单元的四边，如果被遮挡，会自动调整位置和方向。
const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = sheet.getRange(0, 0, 10, 10); // A1:J10
 
 
// 你应该在合适的时机（比如univer加载完成）注册组件
// 这是一个React组件, 如果是vue3组件请查看当前章节最上方的前置知识
univerAPI.getComponentManager().register(
  'myPopup',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>弹出内容</div>
);
 
// 将弹出窗口附加到范围的第一个单元格
// 如果 disposeable 为 null，则表示 popup 添加失败
const disposeable = range.attachPopup({
  // componentKey 必须是一个组件或已注册组件的键
  componentKey: 'myPopup',
});
 
// 移除弹出框
disposable.dispose();

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

addFloatDomToPosition 方法

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

demo

const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// 你应该在合适的时机（比如univer加载完成）注册组件
// 这是一个React组件, 如果是vue3组件请查看当前章节最上方的前置知识
univerAPI.getComponentManager().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',
  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();

注意事项

  1. 在使用这些方法时，请确保Univer已经完成渲染。
  2. 对于需要注册的组件，请确保在使用前已正确注册。
  3. 使用 dispose() 方法来清理和移除添加的组件，以避免内存泄漏。

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

复制粘贴默认样式