Instalación y uso básico

Univer adopta una filosofía de diseño basada en complementos, con el objetivo de proporcionar a los desarrolladores un marco flexible y extensible para aplicaciones de documentos electrónicos. A través de este diseño basado en complementos, Univer puede integrar fácilmente varios módulos funcionales para satisfacer las necesidades de diferentes usuarios. Sin embargo, el diseño basado en complementos aumenta la complejidad de la aplicación, especialmente para los desarrolladores que son nuevos en Univer.

Por esta razón, Univer ofrece dos formas de ayudarlo a integrar y usar Univer rápidamente: modo complemento y modo preestablecido. El llamado preajuste es en realidad una combinación de complementos preconfigurados, por lo que las capacidades proporcionadas por ambos modos son las mismas sin extensiones complejas.

Diferencias entre el modo preestablecido y el modo complemento:

Univer ofrece dos modos de integración: el modo preestablecido y el modo plugin. El modo preestablecido simplifica la configuración mediante conjuntos de plugins preconfigurados. Si necesita personalizaciones o extensiones avanzadas, recomendamos el modo plugin para combinar y configurar los plugins de forma individual.

Configuración a través del modo complemento

Univer proporciona una serie de funciones en forma de complementos. Además de algunos complementos principales que son esenciales para el producto, puede introducir selectivamente otros complementos según sea necesario. Aquí, tomaremos la aplicación Univer Docs más básica como ejemplo para presentarle cómo combinar e instalar complementos manualmente.

A diferencia del modo preestablecido, el modo complemento no incluye Facade API¹ de forma predeterminada. Los siguientes ejemplos utilizan la API de Facade, así que importe los paquetes de fachada correspondientes antes de crear la instancia de API.

Uso del Administrador de paquetes

Instalación

Univer utiliza React para la interfaz y RxJS para los flujos de datos; también puede integrarse en Vue o Angular. Comprueba que las peer dependencies² react, react-dom y rxjs estén instaladas. El comando de Yarn siguiente las incluye explícitamente.

Mantén todos los paquetes @univerjs/* y @univerjs-pro/* en la misma versión.

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

Uso

Crea el contenedor antes de inicializar Univer y asígnale una altura explícita:

<div id="app" style="height: 600px"></div>

Importa las entradas facade utilizadas a continuación antes de llamar a FUniver.newAPI(univer). Importa el CSS en este orden: @univerjs/design, @univerjs/ui y, por último, el CSS del producto.

1. Debe importar los archivos de estilo de Univer, los paquetes de idioma y algunos complementos necesarios en su proyecto:

   TypeScript

   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'

2. Importe los paquetes de fachada utilizados en el ejemplo:

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. Luego cree una instancia de Univer y registre estos complementos:

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

   Expandir código

Métodos univer.registerPlugin y univer.registerPlugins

El método univer.registerPlugin se utiliza para registrar un complemento en la instancia de Univer. Puede llamar a este método después de crear la instancia de Univer para registrar complementos.

Puede registrar un complemento utilizando el método univer.registerPlugin(Plugin, options), donde Plugin es el complemento que se registrará y options son elementos de configuración opcionales, ya que cada complemento puede tener diferentes elementos de configuración.

También puede usar univer.registerPlugins para pasar una matriz y registrar varios complementos a la vez. Esto es útil para escenarios en los que necesita administrar complementos de forma centralizada.

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

Complementos de carga diferida

Una ventaja común del modo complemento es que puede controlar el tiempo de carga de los complementos de manera más flexible. Un enfoque común es cargar solo los complementos esenciales durante la inicialización de la aplicación, mientras se difiere la carga de algunos complementos hasta que se complete el primer procesamiento.

// ...const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

Importar desde CDN

Si no desea utilizar un administrador de paquetes o simplemente desea probar rápidamente las funciones de Univer, puede importar los recursos relevantes de Universidad a través de CDN. Para obtener más información, consulte Uso de Univer a través de CDN.

Compatibilidad móvil

Utilice plugins de UI móvil para los controles táctiles de Univer Docs.³ Elija el modo antes de crear el editor.

En el ejemplo de modo plugin anterior, sustituya las siguientes importaciones y registros de UI antes de createUnit(). No los añada a un editor de escritorio ya inicializado. Conserve modelos, motores, traducciones, CSS e importaciones Facade. Las clases son exportaciones con nombre del mismo punto de entrada del paquete.

import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)

Actualmente, UniverSheetsCorePreset y UniverDocsCorePreset registran UI de escritorio y no tienen la opción mobile: true. Configure explícitamente los plugins móviles. Añadirlos después de un preset de escritorio no sustituye su UI.

Correspondencia de plugins

Registre solo las funciones necesarias, con sus modelos y dependencias. Disponer de una UI móvil no implica que ambas interfaces ofrezcan los mismos controles. Las funciones Pro siguen necesitando la licencia correspondiente. Para las funciones que necesitan un backend, integra los módulos correspondientes de Univer Server SDK en tu aplicación.

Contenedor e interacción táctil

Defina una altura explícita y el viewport de la página. 100dvh sigue la altura dinámica del viewport. Compruebe el desplazamiento, el zoom con dos dedos, la selección de texto, el portapapeles y el teclado virtual en los navegadores móviles de destino. Reducir el ancho no selecciona los plugins móviles.

UniverMobileUIPlugin usa disableAutoFocus: true de forma predeterminada para evitar que el editor tome el foco automáticamente al inicializarse.

<meta name="viewport" content="width=device-width, initial-scale=1" /><div id="app" style="height: 100dvh"></div>

Configuración mediante el modo preestablecido

Aquí presentaremos brevemente cómo crear rápidamente una aplicación Univer Docs con menos de veinte líneas de código.

Uso del Administrador de paquetes

Si su proyecto ya utiliza herramientas modernas de desarrollo front-end, integrar Univer será muy sencillo. Recomendamos utilizar herramientas de compilación como Vite, esbuild o Webpack 5 que tienen un buen soporte para módulos ES para crear aplicaciones Univer. Si está utilizando otras herramientas de compilación (como Webpack 4), es posible que necesite alguna configuración adicional.

Instalación

Elija su administrador de paquetes para instalar @univerjs/presets:

pnpm add @univerjs/presets @univerjs/preset-docs-core

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

Uso

Con el siguiente código, puede iniciar una aplicación Univer Docs:

<div id="app" style="height: 600px"></div>

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetDocsCoreEnUS,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

El objeto univerAPI devuelto aquí se llama Univer Facade API, a través del cual puede llamar a muchas funciones proporcionadas por Univer.

Método createUniver

El método createUniver acepta un objeto de configuración que contiene la información de configuración de Univer, como el idioma, el tema y los complementos. Este método devuelve un objeto que contiene la instancia de Univer y la instancia de API de Univer Facade.

Algunas propiedades del objeto de configuración son las siguientes:

• locale: entorno de lenguaje, puede ser un valor de enumeración LocaleType.
• locales: configuraciones regionales, un objeto, la clave es el entorno del idioma y el valor es el objeto del paquete de idioma.
• theme: un objeto de tema, que es opcional.
• presets: una matriz de ajustes preestablecidos que contiene los ajustes preestablecidos que se registrarán, como UniverDocsCorePreset.
• plugins: una matriz de complementos que contiene los complementos que deben registrarse adicionalmente.

Cuando usa un complemento que no está incluido en ningún paquete preestablecido o implementa su propio complemento, puede registrar estos complementos a través de la propiedad plugins. También puede optar por registrar complementos utilizando el método univer.registerPlugin después de obtener la instancia de Univer.

Importar desde CDN

Si no desea utilizar un administrador de paquetes o simplemente desea probarlo rápidamente Las funciones de Univer le permiten importar los recursos relevantes de Univer a través de CDN. Para obtener más información, consulte Uso de Univer a través de CDN.

Otras versiones

Además de las versiones estables, Univer ofrece canales alfa/beta y nocturnos. Estas versiones le permiten obtener acceso anticipado a las funciones más nuevas que aún no se han lanzado oficialmente. Sin embargo, tenga en cuenta que más funciones también significan más riesgos. Estas versiones pueden contener errores, funciones incompletas o características inestables. Evite el uso de estas versiones en entornos de producción siempre que sea posible.

Lanzamiento alfa/beta

Cuando el equipo de desarrollo de Univer completa una nueva función o un cambio significativo, es posible que lo publique previamente en el canal alfa o beta. Puede instalar la versión alfa/beta de un paquete de Univer usando el siguiente comando:

pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

npm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta version

yarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta version

bun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@beta # Beta version

Si encuentra algún problema o tiene algún comentario mientras usa las versiones alfa/beta, infórmelo al equipo de desarrollo de Univer a través de Problemas de GitHub.

Agradecemos sus comentarios sobre estas primeras versiones.

Próximos pasos

• Básico Conceptos - Aprenda sobre los conceptos básicos de Univer.
• Features - Aprenda sobre las características de Univer y cómo manipular datos.