Componentes personalizados

Univer no pasa componentes directamente como parámetros a ninguna función de renderizado. Debe registrar los componentes con Univer a través de la API de Facade antes de poder usarlos en varios puntos de montaje.

Si no está familiarizado con cómo obtener una instancia de la API de Facade, puede consultar API de Facade.

Registro de componentes personalizados

univerAPI.registerComponent(componentKey, CustomComponent, options)

Utilice el método univerAPI.registerComponent para registrar componentes personalizados. Este método acepta tres parámetros:

• componentKey: un identificador único para el componente, usado para hacer referencia a él dentro de Univer.
• CustomComponent: la implementación del componente, que puede ser un componente React, Vue o Web.
• options: opciones de configuración opcionales que se pueden usar para especificar el marco del que depende el componente u otros relacionados settings.

Componentes de React

Para registrar un componente de React, no se requiere configuración adicional; solo asegúrese de que el componente sea un componente de React válido. Aquí hay un ejemplo simple:

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

Componentes de Vue

Vue 3.x

Si desea registrar componentes de Vue, asegúrese de instalar y registrar UniverVue3AdapterPlugin del paquete @univerjs/ui-adapter-vue3:

pnpm add @univerjs/ui-adapter-vue3

npm install @univerjs/ui-adapter-vue3

yarn add @univerjs/ui-adapter-vue3

bun add @univerjs/ui-adapter-vue3

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

Al registrar componentes de Vue, debe especificar la opción framework como 'vue3':

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

Vue 2.x

Dado que Vue 2.x está en EOL (fin de vida útil) y ya no se mantiene, Univer actualmente no proporciona un complemento de adaptador de interfaz de usuario para Vue 2.x. Sin embargo, puede implementar un adaptador Vue 2.x creando un complemento personalizado. A continuación se muestra un ejemplo de cómo crear un complemento de adaptador Vue 2.x:

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 })}

Luego regístrelo:

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

Al registrar componentes Vue 2.x, debe especificar la opción framework como 'vue2':

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

Componentes web

Si desea registrar componentes web, asegúrese de que el componente se adhiera a los componentes web estándar e instale y registre UniverWebComponentAdapterPlugin del paquete @univerjs/ui-adapter-web-component:

pnpm add @univerjs/ui-adapter-web-component

npm install @univerjs/ui-adapter-web-component

yarn add @univerjs/ui-adapter-web-component

bun add @univerjs/ui-adapter-web-component

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

Al registrar componentes web, debe especificar la opción framework como 'web-component':

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',})

Angular

Convierte un componente Angular en un elemento personalizado con createCustomElement de @angular/elements y regístralo con el adaptador Web Component de Univer. Así podrás usarlo en una barra lateral o un diálogo.

Añade @angular/elements con la misma versión que @angular/core, y @univerjs/ui-adapter-web-component con la misma versión que los demás paquetes Univer.

Llama a esta función después de inicializar Univer. En el componente anfitrión, obtén el inyector con private readonly injector = inject(Injector) y llama a registerAngularPanel(univer, univerAPI, this.injector). Importa inject e Injector desde @angular/core en ese componente.

import type { Injector } from '@angular/core'import type { FUniver, Univer } from '@univerjs/presets'import { Component } from '@angular/core'import { createCustomElement } from '@angular/elements'import { UniverWebComponentAdapterPlugin } from '@univerjs/ui-adapter-web-component'@Component({  selector: 'app-angular-panel',  standalone: true,  template: '<p>Hello from Angular!</p>',})export class AngularPanelComponent {}export function registerAngularPanel(univer: Univer, univerAPI: FUniver, injector: Injector) {  const element = createCustomElement(AngularPanelComponent, { injector })  univer.registerPlugin(UniverWebComponentAdapterPlugin)  return univerAPI.registerComponent('univer-angular-panel', element, {    framework: 'web-component',  })}

Cuando el editor se haya renderizado, usa la clave registrada como contenido de la barra lateral:

const sidebar = univerAPI.openSidebar({  header: { title: 'Angular' },  children: { label: 'univer-angular-panel' },  width: 360,})

Conserva los identificadores de registro y de la barra lateral, y llama a sus métodos dispose() cuando ya no los necesites. Registra el elemento una sola vez por aplicación. Su nombre debe contener un guion y ser distinto del selector Angular.

Angular Elements convierte las entradas en propiedades y las salidas en eventos DOM CustomEvent. El adaptador de Univer transmite propiedades, pero no se suscribe automáticamente a las salidas Angular; conecta explícitamente los eventos necesarios.

Usar componentes personalizados

Los siguientes métodos le permiten integrar de manera flexible varios componentes personalizados en Univer, mejorando y personalizando su funcionalidad.

Agregar elementos de menú personalizados

La barra de menú superior (cinta) y el menú contextual (menú contextual) pueden incluir componentes personalizados. Para agregarlos a los elementos del menú, cree un complemento personalizado.

Reemplazo de componentes integrados

univerAPI.registerComponent registra una sustitución de forma predeterminada (override: true). Tiene prioridad independientemente de cuándo registre el plugin su componente predeterminado. Solo puede haber una sustitución activa por componentKey; libere el registro anterior antes de añadir otra. El método dispose() del objeto devuelto restaura el componente predeterminado, si está registrado. Use { override: false } para registrar un componente predeterminado.

Registre la sustitución antes de abrir la vista por primera vez. Cambiar el registro no vuelve a renderizar automáticamente las vistas ya montadas.

Por ejemplo, para simplemente reemplazar el componente ColorPicker integrado:

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

Usar como componentes de contenido

En el Barra lateral

Usando el método univerAPI.openSidebar, puede abrir una barra lateral en la interfaz de Univer que contiene un componente personalizado.

// 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()

Referencia: univerAPI.openSidebar

En un cuadro de diálogo

Usando el método univerAPI.openDialog, puede abrir un cuadro de diálogo que contiene un componente personalizado.

// 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()

Referencia: univerAPI.openDialog