사용자 지정 컴포넌트

Web SDK는 사용자 정의 컴포넌트를 통합하는 여러 방법을 제공하여 기능을 확장하고 맞춤 설정할 수 있도록 합니다. 이 가이드에서는 자주 사용하는 몇 가지 방법을 소개합니다.

Univer는 기능을 렌더링하는 인수로 구성품을 허용하지 않습니다. Facade API를 통해 구성품을 등록하고 Univer가 각 장착 지점에서 찾을 수 있습니다.

Facade API 인스턴스가 없으면 Facade API를 참조하십시오.

사용자 지정 컴포넌트 등록

TypeScript
univerAPI.registerComponent(componentKey, CustomComponent, options)

univerAPI.registerComponent는 3개의 모수를 받아들입니다:

  • componentKey : Univer 내부에 참조하는 데 사용되는 구성 요소의 고유 식별자.
  • CustomComponent : React 구성 요소, Vue 부품 또는 웹 구성 요소로 구성 요소 자체.
  • options: 구성 요소가 위에 달려있는 것과 같은 선택적인 조정.

React 컴포넌트

React 구성 요소는 추가 구성이 필요하지 않습니다. 유일한 요구 사항은 구성 요소가 유효한 React 부품입니다.

TSX
function ReactComponent(props: Record<string, any>) {  return <div>Hello Univer!</div>}univerAPI.registerComponent('MyReactComponent', ReactComponent)

Vue 컴포넌트

Vue 3.x

Vue 구성품을 등록하려면 UniverVue3AdapterPlugin를 @univerjs/ui-adapter-vue3 패키지에서 설치 및 등록하십시오.

Shell
pnpm add @univerjs/ui-adapter-vue3
TypeScript
import { UniverVue3AdapterPlugin } from '@univerjs/ui-adapter-vue3'univer.registerPlugin(UniverVue3AdapterPlugin)

Vue 구성품을 등록할 때 framework 옵션을 'vue3'로 설정하십시오.

TSX
const Vue3Component = defineComponent({  setup(props) {    return () => <div>Hello Univer!</div>  },})univerAPI.registerComponent('MyVue3Component', Vue3Component, {  framework: 'vue3',})

Vue 2.x

Vue 2.x는 EOL (생명의 끝)이고 더 이상 유지되지 않습니다, 그래서 Univer는 그것을 위한 UI 접합기 플러그인을 제공하지 않습니다. 당신은 주문 플러그인으로 1개를 실행할 수 있습니다. 아래 예는 Vue 2x 접합기를 건설합니다:

TypeScript
import { DependentOn, Inject, Injector, Plugin } from '@univerjs/core'import { ComponentManager, UniverUIPlugin } from '@univerjs/ui'import Vue from 'vue'/** * The plugin that allows Univer to use Vue 2 components as UI components. */@DependentOn(UniverUIPlugin)export class UniverVue2AdapterPlugin extends Plugin {  static override pluginName = 'UNIVER_UI_VUE2_ADAPTER_PLUGIN'  constructor(    private readonly _config = {},    @Inject(Injector) protected readonly _injector: Injector,    @Inject(ComponentManager) protected readonly _componentManager: ComponentManager,  ) {    super()  }  override onStarting(): void {    const { createElement, useEffect, useRef } = this._componentManager.reactUtils    this._componentManager.setHandler('vue2', (component: any) => {      return (props: Record<string, any>) =>        createElement(VueComponentWrapper, {          component,          props: Object.keys(props).reduce<Record<string, any>>((acc, key) => {            if (key !== 'key') {              acc[key] = props[key]            }            return acc          }, {}),          reactUtils: { createElement, useEffect, useRef },        })    })  }}export function VueComponentWrapper(options: {  component: any  props: Record<string, any>  reactUtils: typeof ComponentManager.prototype.reactUtils}) {  const { component, props, reactUtils } = options  const { createElement, useEffect, useRef } = reactUtils  const domRef = useRef<HTMLDivElement>(null)  useEffect(() => {    if (!domRef.current) return    const Constructor = Vue.extend(component)    const instance = new Constructor({      data: props,    })    instance.$mount()    domRef.current.appendChild(instance.$el)    return () => {      instance.$destroy()    }  }, [props])  return createElement('div', { ref: domRef })}

그런 다음 플러그인을 등록합니다.

TypeScript
import { UniverVue2AdapterPlugin } from './ui-adapter-vue2'univer.registerPlugin(UniverUIPlugin)univer.registerPlugin(UniverVue2AdapterPlugin)

Vue 2.x 구성 요소를 등록하면 framework 옵션이 'vue2'로 설정됩니다.

TSX
const Vue2Component = Vue.component('MyVue2Component', {  template: '<div>Hello, Univer!</div>',})univerAPI.registerComponent('MyVue2Component', Vue2Component, {  framework: 'vue2',})

Web Components

웹 구성 요소는 웹 구성 요소 표준을 준수해야합니다. @univerjs/ui-adapter-web-component 패키지에서 UniverWebComponentAdapterPlugin 설치 및 등록 :

Shell
pnpm add @univerjs/ui-adapter-web-component
TypeScript
import { UniverWebComponentAdapterPlugin } from '@univerjs/ui-adapter-web-component'univer.registerPlugin(UniverWebComponentAdapterPlugin)

웹 구성 요소를 등록할 때 framework 옵션을 'web-component'로 설정하십시오.

TSX
class WebComponent extends HTMLElement {  constructor() {    super()    const shadow = this.attachShadow({ mode: 'open' })    const div = document.createElement('div')    div.textContent = 'Hello Univer!'    shadow.appendChild(div)  }}univerAPI.registerComponent('my-web-component', WebComponent, {  framework: 'web-component',})

사용자 지정 컴포넌트 사용

아래 방법은 Univer의 자체 UI 내에서 사용자 정의 구성 요소를 마운트합니다.

주의

  1. Univer는 이러한 방법 중 하나를 호출하기 전에 렌더링을 완료해야합니다. 2. 그것을 사용하기 전에 구성 요소를 등록하십시오. 3. dispose()를 사용하여 정리하고 추가 구성 요소를 제거하십시오. 그렇지 않으면 메모리 누출이 발생합니다.

사용자 지정 메뉴 항목 추가

상단 메뉴 바 (Ribbon) 및 오른쪽 클릭 메뉴 (Context Menu)는 사용자 정의 구성 요소를 모두 포함 할 수 있습니다. 자신의 플러그인에서이 메뉴 항목을 제공, 사용 전에 구성 요소를 등록하고 플러그인과 함께 등록을 해제.

기본 제공 컴포넌트 교체

- 기타

내장 구성 요소를 대체 할 수 있습니다 일부 기능을 제대로 작동 중지 할 수 있습니다. 소스 코드를 읽고 구성 요소의 문서가 교체하고주의로 진행합니다.

univerAPI.registerComponent는 기본 (override: true)에 의해 과속을 등록합니다. 과속은 플러그인이 통화 전 또는 후에 기본을 등록하는지 여부에 관계없이 내장 구성 요소에 대해 우선적으로 수행됩니다. 하나의 과속은 각 componentKey에서만 활성화 될 수 있으므로 다른 등록을 등록하기 전에 이전 등록을 해제하십시오. 반환된 등록에 dispose()를 호출하면 내장 기본을 복원합니다. 대신 { override: false }에 등록하면 ZXQXQ4Z를 등록합니다.

해당 뷰가 처음 열리기 전에 오버라이드를 등록하십시오. 등록을 변경하면 이미 장착 된 레이아웃을 렌더링하지 않습니다.

예를 들어, 다음과 같은 코드는 내장 ColorPicker 구성 요소를 대체합니다.

TSX
// Following code only replaces the UI of the built-in ColorPicker component, not its functionalityuniverAPI.registerComponent('UI_COLOR_PICKER_COMPONENT', () => <input type="color" />)

콘텐츠 컴포넌트로 사용

사이드바에서 사용

univerAPI.openSidebar는 Univer 인터페이스의 사이드바를 열고 사용자 정의 구성 요소를 렌더링합니다.

TSX
// You should register the component at an appropriate time (e.g., after Univer has loaded)univerAPI.registerComponent('MyCustomSidebarComponent', () => <div>Hello Univer!</div>)const sidebar = univerAPI.openSidebar({  header: { title: 'My Sidebar' },  children: { label: 'MyCustomSidebarComponent' },  onClose: () => {    console.log('close')  },  width: 360,})// Later close the sidebarsidebar.dispose()

참조: univerAPI.openSidebar

대화 상자에서 사용

univerAPI.openDialog는 사용자 정의 구성 요소를 렌더링하는 대화 상자를 엽니다.

TSX
// You should register the component at an appropriate time (e.g., after Univer has loaded)univerAPI.registerComponent('MyCustomDialogComponent', () => <div>Hello Univer!</div>)const dialog = univerAPI.openDialog({  id: 'unique-dialog-id', // The unique identifier for the dialog  draggable: true,  width: 300,  title: { title: 'My Dialog' },  children: {    label: 'MyCustomDialogComponent',  },  destroyOnClose: true,  preservePositionOnDestroy: true,  onClose: () => {},})// Later close the dialogdialog.dispose()

참조: univerAPI.openDialog

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.