Trabajar con hojas de cálculo de Excel y comandos de complementos de Excel

13 minutos

En esta unidad, aprenderá a trabajar con hojas de cálculo en libros de Excel. También aprenderá a crear y usar comandos de complemento para sus soluciones personalizadas.

Hojas de cálculo y un libro

Un libro es el objeto raíz al trabajar con las API de Excel.

Diagrama que muestra la jerarquía de objetos de Excel.

Un libro es una propiedad del contexto del complemento de Excel, context.workbook, y contiene una colección de hojas de cálculo.

Una hoja de cálculo contiene colecciones para charts, tables y pivotTables entre otras propiedades.

Operaciones básicas de hojas de cálculo

Interactuar con hojas de cálculo es una operación fundamental para crear un complemento de Excel.

La API de Office.js puede iterar hojas de cálculo en un objeto de libro o puede seleccionar hojas de cálculo específicas según el nombre, el identificador o el estado activo de la hoja de cálculo.

Los desarrolladores pueden crear hojas de cálculo mediante el método workbook.worksheets.add().

Operaciones avanzadas de hojas de cálculo

Hay muchas operaciones avanzadas de hoja de cálculo, incluidos los eventos de hoja de cálculo para onActivated, onAdded, onDeactivated y onDeleted.

Los desarrolladores también pueden inmovilizar paneles de hojas de cálculo y proteger o desproteger hojas de cálculo.

En los ejemplos de código siguientes se muestran las operaciones comunes que los desarrolladores pueden realizar desde complementos de Excel personalizados mediante la API de Office.js:

Obtener la hoja de cálculo activa

const worksheet = context.workbook.worksheets.getActiveWorksheet();

Obtener el rango por nombre

const worksheet = context.workbook.worksheets.getItem("MyNewWorksheet");

Configurar la hoja de cálculo activa
```
someWorksheet.activate();
```

Crear una hoja de cálculo

const worksheet = context.workbook.worksheets.add("MyNewWorksheet");

Eliminar una hoja de cálculo
```
someWorksheet.delete();
```

Conexión al onDeactivated evento

currWorksheet.onDeactivated.add((args) => {
  console.log("Worksheet " + args.worksheetId + " deactivated");
});

Inmovilizar la primera fila de la hoja de cálculo
```
currWorksheet.freezePanes.freezeRows(1);
```

Activar o desactivar la protección de hoja de cálculo

currWorksheet.load("protection/protected");
return context.sync().then(() => {
  if (currWorksheet.protection.protected)
    currWorksheet.protection.unprotect();
  else
    currWorksheet.protection.protect();
}).then(context.sync);

Comandos de complemento

Los comandos de complemento permiten personalizar fácilmente la interfaz de usuario (UI) predeterminada de Office con elementos de la IU especificados que realizan diversas acciones.

Los comandos de complemento se configuran en el elemento VersionOverrides de un manifiesto de complemento.

Los comandos de complemento pueden extender los menús contextuales, las pestañas y los grupos de la cinta de opciones existentes, o crear nuevas pestañas y grupos personalizados de la cinta de opciones.

Elemento ExtensionPoint

El elemento ExtensionPoint define dónde deben aparecer los comandos de complemento en la interfaz de usuario de Office. Esto incluye una pestaña de cinta existente (OfficeTab), una pestaña personalizada (CustomTab) o un menú contextual que aparece si se hace clic con el botón derecho en la interfaz de usuario de Office (OfficeMenu).

Los comandos de complemento admiten controles de menú y botón. Los botones realizan una sola acción y los menús proporcionan un submenú de acciones.

Acciones de comandos

La acción ShowTaskpane() es la más común para un comando de complemento. Se usa para iniciar el complemento en un panel de tareas. El uso de un comando de complemento para iniciar un complemento se considera un procedimiento recomendado y se incorpora en la mayoría de las plantillas y generadores de complementos de Office.

La acción ExecuteFunction permite que un comando de complemento ejecute algún script en segundo plano sin mostrar ninguna interfaz de usuario. Este tipo de comando requiere que se defina un FunctionFile en el manifiesto.

Comando de complemento en el manifiesto

Vamos a explorar cómo se asignan los distintos elementos del manifiesto del complemento a los elementos representados en la experiencia del usuario de Excel.

La siguiente imagen contiene una captura de pantalla de una aplicación cliente de Office a la izquierda y una versión comprimida de un archivo de manifiesto de complemento a la derecha:

Captura de pantalla de una aplicación Office junto a un extracto del manifiesto de complemento.

El manifiesto comienza con el elemento ExtensionPoint que contiene todas las personalizaciones definidas para la cinta de Opciones de Office:

Captura de pantalla de una aplicación Office junto a un extracto del manifiesto del complemento con el punto de extensión resaltado.

Todo el contenido del elemento ExtensionPoint define la pestaña personalizada en la cinta de opciones y todos los botones de la pestaña:

Captura de pantalla de una aplicación Office junto a un extracto del manifiesto del complemento con la pestaña personalizada resaltada en ambos.

Cada botón de la cinta de opciones se define con un elemento Control. Un control puede ser de tipos diferentes, definidos en la propiedad xsi:type. Todos los controles de esta cinta son botones:

Captura de pantalla de una aplicación Office junto a un extracto del manifiesto del complemento con las pestañas personalizadas resaltadas y numeradas en ambos.

Dentro de un control, los desarrolladores pueden definir acciones o elementos. Un elemento Action se usa para realizar una acción, como mostrar un panel de tareas o ejecutar una función personalizada.

La colección Items permite a los desarrolladores agregar más elementos de menú al botón de la cinta de opciones, como se muestra en la siguiente imagen. Observe que cada elemento de submenú también tiene un elemento Action:

Captura de pantalla de una aplicación de Office junto a un manifiesto del complemento con los elementos Objeto resaltados y numerados en ambos.

Comando de complemento ExecuteFunction

La acción de comando de complemento ExecuteFunction permite a los desarrolladores crear funciones personalizadas, definidas en JavaScript, para que se ejecuten cuando se selecciona un botón en la cinta de opciones.

En primer lugar, defina la función en un archivo de script. Por ejemplo, agregue el código siguiente a un nuevo archivo en el complemento denominado fnFile.html:

<script>
(function () {
  // must call Office.initialize
  Office.initialize => (reason) {
    // Initialize add-in
  };
})();
// function must be global
function doStuff(event) {
  // do stuff with Office.js
}
</script>

Para llamar a la función, use el tipo de acción ExecuteFunction en el manifiesto del complemento para llamar a la función cuando se seleccione el botón personalizado:

<FunctionFile resid="Contoso.FnFile.Url" />
...
<Control xsi:type="Button" id="Contoso.FnBtn">
  <Label resid="Contoso.FnBtn.Label" />
  <Icon>
    <bt:Image size="16" resid="Contoso.FnBtn.Icon" />
    <bt:Image size="32" resid="Contoso.FnBtn.Icon" />
    <bt:Image size="80" resid="Contoso.FnBtn.Icon" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>doStuff</FunctionName>
  </Action>
  </Control>
...
<Resources>
  <bt:Urls>
    <bt:Url id="Contoso.FnFile.Url"
            DefaultValue="https://REPLACE_ADD-IN_APP_URL/FnFile.html" />
      ...

Resumen

En esta unidad, aprendió a trabajar con hojas de cálculo en libros de Excel. También aprendió a crear y usar comandos de complemento para sus soluciones personalizadas.

Continuar