Información sobre las API de JavaScript de Office
En esta unidad, obtendrás información sobre el modelo de programación de los Complementos de Office, las herramientas para desarrolladores y las capacidades de las API de JavaScript de Office para Excel, Outlook y Word.
Comprender el modelo de programación de Complementos de Office
El modelo de programación del complemento de Office se basa en dos modelos de objeto de JavaScript:
- API de JavaScript específica de host: las API para Excel y Word específicas del host proporcionan objetos tipo que se pueden usar para acceder a elementos específicos de la aplicación del host. Por ejemplo, la API de Excel contiene objetos que representan hojas de cálculo, rangos, tablas, gráficos y mucho más.
- API común: La API común introducida con Office 2013 que le permite acceder a características como:
- Interfaz de usuario
- Diálogos
- Configuraciones del cliente que son comunes en varios tipos de aplicaciones de Office
Las funciones personalizadas usan un modelo de programación ligeramente distinto y serán tratadas en otra unidad.
Conjuntos de requisitos de la API de JavaScript de Office
Puede que no siempre tenga control sobre la versión de Office que hayan instalado los usuarios. Según la versión de Office y la plataforma en la que se ejecute, habrá diferentes API y características compatibles para el complemento. Por ejemplo, Office 2016 admite más funciones que Office 2013. Para manejar esta situación, proporcionamos un conjunto de requisitos para ayudarle a determinar si un host de Office es compatible con las funciones que necesita en su complemento de Office.
Los conjuntos de requisitos pueden ser específicos para los hosts de Office, como un conjunto de ExcelApi 1.7, o comunes para varios hosts, como la API de Dialog. La compatibilidad del conjunto de requisitos varía de acuerdo con el host de Office y la versión del host.
Es posible comprobar por programación si los conjuntos de requisitos son compatibles con el host de Office del complemento, mediante isSetSupported. Si el conjunto de requisitos es compatible, isSetSupported devuelve true y el complemento puede ejecutar el código adicional que usa a las API miembros de ese conjunto de requisitos. Si el host de Office no admite el conjunto de requisitos, isSetSupported devuelve false y no se ejecuta el código adicional. El siguiente código muestra la sintaxis que se usa con isSetSupported.
if (Office.context.requirements.isSetSupported(RequirementSetName, MinimumVersion)) {
// Code that uses API members from RequirementSetName.
}
Nota:
Programa de Office Insider
Puede unirse al programa Office Insider para obtener los primeros cambios o los cambios mensuales de cualquiera de los hosts de Office. Este programa es solo para PC Windows y requiere una suscripción a Microsoft 365. En cualquier aplicación de Office, seleccione Archivo>Cuenta>Office Insider para unirse rápidamente al programa.
Cómo usar las API de JavaScript de Office
Para usar estas API, haga referencia a ellas en la red de entrega de contenido (CDN) de Office.js, normalmente agregando una de las siguientes instrucciones de código a la etiqueta <head> de la página.
<!-- Reference the production APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
<!-- Reference the beta/preview APIs on the CDN -->
<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js" type="text/javascript"></script>
Además de agregar el vínculo de CDN preferido, todos los Complementos de Office requieren una llamada de Office.onReady(). Al poner el código del complemento en este método, se llamará una vez que se haya inicializado la biblioteca de Office.js. Dentro del método onReady() puede determinar en qué host se ejecuta el complemento al comprobar el valor de enumeración Office.HostType (por ejemplo, Excel o Word). Puede comprobar en qué plataforma se ejecuta el complemento con un valor de enumeración Office.PlatformType (por ejemplo, PC o Mac).
Si usa otros marcos de JavaScript que incluyen su propio controlador de inicialización o pruebas, deben colocarse dentro de la respuesta a Office.onReady(). Por ejemplo, puede hacer referencia a la función $(document).ready() de jQuery, como se muestra en el siguiente ejemplo de código.
Office.onReady(function() {
// Office is ready.
$(document).ready(function () {
// The document is ready.
});
});
Realizar llamadas asincrónicas con objetos proxy
Al trabajar con un documento, las acciones de lectura o escritura solicitadas se procesan por lotes mediante un objeto proxy. Las llamadas de la API no leen o actualizan realmente el documento subyacente hasta que no llame al método sync().
Para una mayor seguridad, el complemento se ejecuta en un entorno de JavaScript de espacio aislado que no puede acceder directamente al documento ni a otros complementos. La plataforma Complementos de Office proporciona un objeto RequestContext que ofrece, a su vez, objetos proxy para representar el documento (como hojas de cálculo, rangos y tablas). Normalmente, el RequestContext se pasa al código como un parámetro denominado context. Puede usar el objeto context para obtener los objetos proxy que necesite para trabajar con el documento.
Para poder leer las propiedades de un objeto proxy, debe cargar las propiedades para rellenar el objeto proxy con datos del documento de Office. Para hacerlo, debe llamar al método load() del objeto proxy para obtener las propiedades que necesite. Luego, llame al método context.sync(), el cual cargará todas las propiedades solicitadas. Por ejemplo, si crea un objeto de rango de proxy para trabajar con un rango seleccionado por el usuario en una hoja de cálculo de Excel y después quiere leer la propiedad address del rango seleccionado, deberá cargar la propiedad address antes de poder leerla. Para solicitar que se carguen las propiedades de un objeto proxy, llame al método load() en el objeto y especifique las propiedades que se van a cargar.
En el ejemplo siguiente se muestra una función que define un objeto de proxy local (selectedRange), carga la propiedad address de ese objeto y luego, llama a context.sync(). Cuando se resuelve la promesa desde context.sync(), el código puede leer la propiedad address. Se necesita Excel.run para este host específico, para cargar las propiedades que afectan al comportamiento de la plataforma cuando se ejecuta la función. No todos los hosts contienen una llamada de ejecución.
Excel.run(function (context) {
var selectedRange = context.workbook.getSelectedRange();
selectedRange.load('address');
return context.sync()
.then(function () {
console.log('The selected range is: ' + selectedRange.address);
});
}).catch(function (error) {
console.log('error: ' + error);
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Comprender las herramientas de desarrollador de Complementos de Office
Puede usar las herramientas de desarrollador de Complementos de Office para crear un complemento de Office, explorar las API de JavaScript de Office y validar un archivo de manifiesto del complemento de Office. En esta unidad, aprenderá de las siguientes herramientas:
- Generador Yeoman para Complementos de Office
- Visual Studio
- Script Lab
- Validador de manifiesto
Creación de un complemento de Office
Puede crear un complemento de Office con el generador de Yeoman para complementos de Office o Visual Studio.
Sugerencia
Instale y obtenga más información sobre el generador de Yeoman para Complementos de Office en github.com/OfficeDev/generator-office.
Generador Yeoman para Complementos de Office
Puede usar el generador de Yeoman para complementos de Office con el fin de crear un proyecto de complemento de Node.js de Office que pueda administrar con Visual Studio Code u otro editor. El generador puede crear complementos de Office para:
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Funciones personalizadas de Excel
Puede elegir crear el proyecto con HTML, CSS y JavaScript o bien, usar Angular o React. TypeScript también es una opción.
Para crear un proyecto de complemento de Office con el generador Yeoman, siga estos pasos.
Para instalar globalmente Yeoman y el generador de Yeoman para Complementos de Office con npm, el administrador de paquetes de nodos, ejecute el siguiente comando.
npm install -g yo generator-officeEjecute el siguiente comando para crear un proyecto de complemento con el generador Yeoman:
yo office
Visual Studio
Visual Studio se puede usar para crear complementos de Office para Excel, Word, PowerPoint o Outlook. Se crea un proyecto de complemento de Office como parte de una solución de Visual Studio, lo que significa que puede usar características de Visual Studio como seleccionar Inicio o elegir F5 para ejecutar automáticamente y de forma local el complemento en IIS. Los proyectos del complemento de Office que cree con Visual Studio usan HTML, CSS y JavaScript.
Para crear un complemento de Office con Visual Studio, cree un proyecto nuevo de C# o de Visual Basic y elija uno los siguientes tipos de proyecto:
- Complemento web de Excel
- Complemento web de Outlook
- Complemento web de PowerPoint
- Complemento web de Word
Explorar las API con Script Lab
Script Lab es un complemento que le permite ejecutar fragmentos de código de JavaScript para Office mientras trabaja en un programa de Office, como Excel o Word. Está disponible de forma gratuita a través de AppSource y es conveniente incluirlo en el kit de herramientas de desarrollo a medida que prueba y comprueba la funcionalidad que desea en su complemento. En Script Lab puede tener acceso a una biblioteca de ejemplos integrados para probar rápidamente las API o incluso usar un ejemplo como punto de partida para su propio código.
El siguiente vídeo muestra el Script Lab en acción.
Validación del archivo de manifiesto de un complemento de Office
El validador del manifiesto de Complementos de Office examina el archivo de manifiesto del complemento para determinar si es correcto y está completo. Si creó su proyecto de complemento con el generador Yeoman para Complementos de Office (versión 1.1.17 o posterior), puede validar el manifiesto ejecutando el siguiente comando en el directorio raíz del proyecto.
npm run validate
Si no usó el generador de Yeoman para crear el proyecto de complemento, puede validar el manifiesto del complemento siguiendo estos pasos.
Instale Node.js.
Ejecute el siguiente comando en el directorio raíz del proyecto.
Importante
Reemplace
{{MANIFEST_FILE}}con el nombre del archivo de manifiesto.npx office-addin-manifest validate {{MANIFEST_FILE}}
Comprender las funciones de la API de JavaScript de Excel
Las API de JavaScript de Excel les dan a sus complementos acceso a los documentos de Excel. Un complemento de Excel puede administrar el contenido, el formato y la estructura de un libro o de una hoja de cálculo.
Comprender las funciones de la API de JavaScript de Outlook
Las API de JavaScript de Outlook les permiten a los complementos acceder al buzón, los mensajes y las citas en Outlook del usuario. Un complemento de Outlook puede obtener el contenido y las propiedades de un mensaje o de una cita. Este complemento también puede administrar el contenido, el formato y la estructura de un mensaje o de una cita que esté redactándose.
Modelo de objetos
Para comprender las API de Outlook, primero vea cómo se relacionan entre sí los componentes principales de un buzón.
- El objeto Buzón le permite controlar la autenticación, administrar un elemento seleccionado y ver los detalles del perfil de usuario.
- El objeto Elemento representa el mensaje o la cita seleccionados que el usuario está leyendo o redactando.
Con las API de Outlook, puede administrar muchas de las propiedades de una cita o de un correo electrónico. Muchas de las API están organizadas de acuerdo con el modo en que se encuentre el usuario. La siguiente tabla asigna los tipos y modos del elemento.
| Tipo de elemento | Modos |
|---|---|
| Mensaje | Leer Redacción |
| Cita o reunión | Asistente (leer) Organizador (redactar) |
Características clave
Además de los complementos del panel de tareas, puede crear complementos contextuales y de módulo. En esta sección, aprenderá algunas características clave de las API de Outlook.
- Opciones de autenticación
- Complementos contextuales
- Complementos de módulo
Autenticación
El complemento de Outlook puede acceder a la información desde cualquier parte de Internet. Algunos ejemplos incluyen al servidor que hospeda el complemento, la red interna o cualquier otro lugar de la nube. Si esa información está protegida, el complemento necesitará una forma de autenticar al usuario. Los complementos de Outlook ofrecen una serie de métodos de autenticación diferentes de acuerdo con su situación específica.
Token de identidad de usuario de Exchange
Los token de identidad de usuario de Exchange proporcionan un método para que el complemento establezca la identidad del usuario. Al comprobar la identidad del usuario, puede autenticarlo en el sistema una vez y luego, aceptar el token de identidad del usuario como autorización para solicitudes futuras. Considere la posibilidad de usar tokens de identidad del usuario si su complemento es usado principalmente por usuarios locales de Exchange o si necesita acceder a un servicio que controle que no sea de Microsoft. Su complemento puede llamar a getUserIdentityTokenAsync() para obtener el token de identidad del usuario de Exchange.
Obtención de tokens de acceso con flujos de OAuth2
Los complementos también pueden acceder a los servicios de terceros que admitan autorización OAuth2. Considere la posibilidad de usar tokens de OAuth2 si su complemento necesita acceso a un servicio de terceros fuera de su control. Con este método, el complemento le pide al usuario que inicie sesión en el servicio mediante el método displayDialogAsync() para inicializar el flujo de OAuth2, por ejemplo.
Tokens de devolución de llamada
Los tokens de devolución de llamada proporcionan acceso al buzón del usuario desde su servidor, ya sea mediante los servicios Web Exchange (EWS) o bien, mediante la API de REST Outlook. Los complementos obtienen los tokens de devolución de llamada con uno de los métodos getCallbackTokenAsync(). El nivel de acceso se controla con los permisos especificados en el manifiesto del complemento.
Resumen de autenticación
La siguiente tabla resume cuándo usar cada tipo de token de acceso.
| Token de acceso | Use si el complemento... |
|---|---|
| Token de identidad del usuario de Exchange | Usado principalmente por los usuarios locales de Exchange. Requiere acceso a un servicio que usted controle que no sea Microsoft. |
| Tokens de acceso de OAuth2 | Requiere acceso a un servicio de terceros fuera de su control. |
| Tokens de devolución de llamada | Requiere acceso al buzón del usuario desde su servidor. |
Complementos contextuales
Los complementos contextuales son complementos de Outlook que se activan de acuerdo con el texto en un mensaje o una cita. Es posible que haya visto los complementos contextuales predeterminados en Outlook, como los Mapas de Bing o las Reuniones sugeridas. Al usar los complementos contextuales, el usuario puede iniciar tareas relacionadas con un mensaje sin salir del mensaje, lo que da como resultado una experiencia de usuario más sencilla y completa.
En la siguiente tabla se enumeran algunas tareas de ejemplo basadas en la selección de un usuario.
| El usuario elige... | Acción contextual del complemento |
|---|---|
| Dirección | Abra un mapa de la ubicación. |
| Cadena | Abra un complemento de sugerencia de reunión. |
| Número de teléfono | Agregue un número a sus contactos. |
Nota:
Los complementos contextuales no están disponibles actualmente en Outlook para Android o iOS.
La siguiente imagen muestra un complemento contextual que se muestra en Outlook.
Complemento contextual que se muestra en Outlook
El manifiesto de un complemento contextual debe incluir un elemento ExtensionPoint con un atributo xsi:type establecido en DetectedEntity. Dentro del elemento ExtensionPoint, el complemento especifica las entidades o la expresión regular que puede activarlo. Si se especifica una entidad, esta puede ser cualquiera de las propiedades en el objeto Entities.
Por lo tanto, el manifiesto del complemento debe contener una regla de tipo ItemHasKnownEntity o ItemHasRegularExpressionMatch. En el ejemplo siguiente, se muestra cómo especificar que un complemento se active en los mensajes al detectar un número de teléfono.
<ExtensionPoint xsi:type="DetectedEntity">
<Label resid="contextLabel" />
<SourceLocation resid="detectedEntityURL" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="PhoneNumber" Highlight="all" />
</Rule>
</ExtensionPoint>
Cuando un complemento contextual se asocia a una cuenta, se iniciará automáticamente cuando el usuario seleccione alguna expresión regular o entidad resaltada.
Un usuario inicia un complemento contextual a través del texto, ya sea una entidad conocida o una expresión regular del desarrollador. Normalmente, un usuario identifica un complemento contextual porque la entidad está resaltada.
Complementos de módulo
Los complementos del módulo se muestran en la barra de navegación de Outlook junto al correo, las tareas y los calendarios. Puede usar todas las características de la API de JavaScript para Outlook en el complemento, así como crear botones de comando en la cinta de Outlook para que el usuario interactúe con el contenido del complemento.
Nota:
Los complementos de módulo solo se admiten en Outlook 2016 o versiones posteriores en Windows.
La siguiente imagen muestra un ejemplo de un complemento de extensión de módulo.
Ejemplo de complemento del Módulo en Outlook en Windows
Para crear un complemento de módulo, incluya el punto de extensión del módulo en el archivo de manifiesto del complemento. El siguiente ejemplo muestra un fragmento de un archivo de manifiesto ajustado para definir una extensión de módulo.
...
<!-- Add Outlook module extension point. -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides"
xsi:type="VersionOverridesV1_0">
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
xsi:type="VersionOverridesV1_1">
<!-- Begin override of existing elements. -->
<Description resid="residVersionOverrideDesc" />
<Requirements>
<bt:Sets DefaultMinVersion="1.3">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<!-- End override of existing elements. -->
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!-- Set the URL of the file that contains the
JavaScript function that controls the extension. -->
<FunctionFile resid="residFunctionFileUrl" />
<!-- Module extension point for a ModuleApp -->
<ExtensionPoint xsi:type="Module">
<SourceLocation resid="residExtensionPointUrl" />
<Label resid="residExtensionPointLabel" />
<CommandSurface>
<CustomTab id="idTab">
<Group id="idGroup">
<Label resid="residGroupLabel" />
<Control xsi:type="Button" id="group.changeToAssociate">
<Label resid="residChangeToAssociateLabel" />
<Supertip>
<Title resid="residChangeToAssociateLabel" />
<Description resid="residChangeToAssociateDesc" />
</Supertip>
<Icon>
<bt:Image size="16" resid="residAssociateIcon16" />
<bt:Image size="32" resid="residAssociateIcon32" />
<bt:Image size="80" resid="residAssociateIcon80" />
</Icon>
<Action xsi:type="ExecuteFunction">
<FunctionName>changeToAssociateRate</FunctionName>
</Action>
</Control>
</Group>
<Label resid="residCustomTabLabel" />
</CustomTab>
</CommandSurface>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
</Hosts>
<Resources>
...
</Resources>
</VersionOverrides>
</VersionOverrides>
Introducción al desarrollo de complementos de Outlook
Para desarrollar un complemento de Outlook, use:
- El generador Yeoman para complementos de Office
- Visual Studio
Puede usar una plantilla como base para después agregar las funcionalidades.
Comprender las funciones de la API de JavaScript de Word
Las API de JavaScript de Word le dan a los complementos acceso a los documentos de Word. Un complemento de Word puede administrar el contenido, el formato y la estructura de un documento.
Modelo de objetos
Para comprender las API de Word, necesita ver cómo se relacionan entre sí los componentes principales de un documento.
- Un Documento contiene un Cuerpo y al menos una Sección.
- Un Cuerpo puede contener:
- Párrafos (uno o más)
- Tablas (una o más)
- Listas (una o más)
- Texto
- Objetos como imágenes y listas
- Una Sección proporciona acceso a su cuerpo, sus encabezados y sus pies de página.
Escenarios clave
En esta sección, aprenderá un par de escenarios clave para las API de Word.
- Trabajar con el texto del documento
- Búsqueda
Nota:
Puede aplicar un formato simple a todo un documento existente con las API de Office.js. Sin embargo, si quiere aplicar un formato complejo o usar objetos de contenido enriquecido, puede usar Office Open XML (OOXML) para crear estos efectos. Algunos ejemplos de las funcionalidades de OOXML incluyen aplicar sombras paralelas al texto o a las imágenes, convertir cuadros de texto en formas e insertar gráficos de Excel como gráficos en directo en documentos de Word. Como se trata de una aptitud más avanzada, no trataremos este tema en su totalidad, aunque lo mencionamo para los desarrolladores que estén familiarizados con OOXML.
Trabajar con texto del documento
Los complementos de Word usan el controlador de eventos Office.onReady() para iniciar. Si el complemento tiene como destino Word 2016 o versiones posteriores, llamará al método Word.run() para ejecutar las API de JavaScript de Word. El complemento debe pasar una función a Word.run() que espera que un objeto de contexto pase como parámetro. El objeto contextual permite que el complemento interactúe con el documento de Word. Puede usar el objeto contextual para crear los objetos de proxy necesarios para el documento de Word y cargar los proxy con las propiedades que desee usar. También puede programar acciones para que se ejecuten con esas propiedades. Como siempre, un comando context.sync() sincroniza el estado entre los objetos del proxy y los objetos del documento de Word.
En el ejemplo siguiente se muestra el código que inserta texto después del texto de cuerpo de un documento de Word. Por motivos de simplicidad, esta muestra omite el código Office.onReady() y se centra en el código dentro del bloque de código Word.run().
// Run a batch operation against the Word JavaScript API.
Word.run(function (context) {
// Create a proxy object for the document body.
var body = context.document.body;
// Queue a command to load the text property of the proxy body object.
body.load("text");
// Queue a command to insert text into the end of the Word document body.
body.insertText('This is text inserted after loading the body.text property',
Word.InsertLocation.end);
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log("Body contents: " + body.text);
});
})
Búsqueda
Puede usar las API para buscar en el documento el texto que cumpla los criterios. También puede definir el ámbito de la búsqueda para determinados tipos de contenido, por ejemplo, párrafos o tablas.
El siguiente código de muestra busca el texto "vídeo you" y pasa por alto la puntuación. Si se encuentra el texto, las coincidencias se marcan en negrita, se resaltan en amarillo y el color de la fuente se establece en púrpura.
// Run a batch operation against the Word object model.
Word.run(function (context) {
// Queue a command to search the document and ignore punctuation.
var searchResults = context.document.body.search('video you', {ignorePunct: true});
// Queue a command to load the search results and get the font property values.
context.load(searchResults, 'font');
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync().then(function () {
console.log('Found count: ' + searchResults.items.length);
// Queue a set of commands to change the font for each found item.
for (var i = 0; i < searchResults.items.length; i++) {
searchResults.items[i].font.color = 'purple';
searchResults.items[i].font.highlightColor = '#FFFF00'; // Yellow
searchResults.items[i].font.bold = true;
}
// Synchronize the document state by executing the queued commands,
// and return a promise to indicate task completion.
return context.sync();
});
})
.catch(function (error) {
console.log('Error: ' + JSON.stringify(error));
if (error instanceof OfficeExtension.Error) {
console.log('Debug info: ' + JSON.stringify(error.debugInfo));
}
});
Introducción al desarrollo de complementos de Word
Para desarrollar un complemento de Word, use:
- El generador Yeoman para complementos de Office
- Visual Studio
Si quiere explorar más las API, le recomendamos el complemento de Script Lab. Allí encontrará muchos fragmentos de TypeScript y JavaScript, y podrá experimentar con documentos de Word sin tener que crear todo el complemento.
Comprender las capacidades de las funciones personalizadas
Las funciones personalizadas tienen varias capacidades y restricciones únicas, ya que se ejecutan en un runtime independiente de las demás interacciones del complemento, como los paneles de tareas.
Capacidades de las funciones personalizadas
Puede crear funciones personalizadas de JavaScript o TypeScript a las que se puede acceder como funciones integradas de Excel, como SUM(). También puede crear funciones personalizadas de streaming que devuelven un valor basado en un temporizador. Por ejemplo, puede actualizar el valor de hora actual en una celda cada segundo. También puede realizar llamadas de red desde las funciones personalizadas.
Ejemplo de JavaScript de función personalizada
El siguiente ejemplo de código define la función personalizada add() que acepta dos números y después devuelve su suma.
/**
* Adds two numbers.
* @customfunction
* @param first First number.
* @param second Second number.
* @returns The sum of the two numbers.
*/
function add(first, second){
return first + second;
}
Descripciones del comentario del código JSDoc
Las etiquetas de JSDoc en los comentarios de código se usan para generar un archivo de metadatos JSON que describe la función personalizada en Excel. El archivo de metadatos JSON permite a Excel presentar información precisa a un usuario y pasar los parámetros esperados a la función personalizada.
@customfunction: Se declara primero e indica que es una función personalizada. Obligatorio.@param: Describe el parámetro. Incluir para cada parámetro definido por la función.@returns: Describe el resultado de la función.
Nota:
La descripción del comentario es "Suma dos números". también se agrega al archivo de metadatos de JSON para que Excel lo muestre cuando el usuario esté viendo su función personalizada.
Restricciones de runtime de la función personalizada
El runtime de la función personalizada solo ejecuta JavaScript. No hay ningún Document Object Model (DOM) ni almacenamiento local como el que encontraría en un entorno de runtime de JavaScript basado en explorador. Esto significa que no puede cargar ninguna biblioteca que use el DOM, como jQuery. Además, no puede acceder a la API de Office.js para interactuar con el documento como podría hacerlo desde un panel de tareas. En su lugar, el runtime de las funciones personalizadas está optimizado para tareas como realizar cálculos rápidos y, por lo general, no necesita usar algunas de las API de Office.js, como las herramientas de formato en Excel.
Las funciones personalizadas tienen una página web que carga el runtime de las funciones personalizadas. Como el tiempo de ejecución de las funciones personalizadas no tiene una interfaz de usuario, la página web no tiene nada que mostrar. Encontrará la siguiente etiqueta de script en la página web que carga la biblioteca para el runtime de las funciones personalizadas.
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/custom-functions-runtime.js" type="text/javascript"></script>
Normalmente, las funciones personalizadas se combinan con un panel de tareas en el mismo complemento. Si crea su proyecto de complemento con el generador Yeoman para Complementos de Office, el proyecto tendrá una página web para las funciones personalizadas y una página web con interfaz de usuario para el panel de tareas.
Cómo usar la API de almacenamiento para comunicarse con el panel de tareas
El código de función personalizada y el código del panel de tareas (que usa Office.js) no pueden llamarse ni comunicarse directamente entre sí. Pero puede usar una API de almacenamiento que les permita compartir datos. Un escenario común para usar la API de almacenamiento es cuando el complemento necesita compartir un token de seguridad para acceder a un recurso de red segura. El usuario puede llamar primero a una función personalizada que requiera que haya iniciado sesión. Después de la autenticación, recibirá el token de seguridad. Luego compartirá el token de seguridad con la API de almacenamiento para que, más adelante, cuando el usuario abra el panel de tareas, no necesite volver a iniciar sesión.
En su lugar, es posible que el usuario abra primero el panel de tareas. En este caso, el panel de tareas iniciará la sesión del usuario y compartirá el token de seguridad a través de la API de almacenamiento. Cuando se usa una función personalizada posteriormente, la función personalizada puede obtener el token de seguridad a través de la API de almacenamiento.
Ejemplo de API de almacenamiento
En el siguiente ejemplo de código se muestra cómo almacenar y recuperar cualquier valor creado por el usuario.
/**
* @customfunction
* @description Stores a value in OfficeRuntime.storage.
* @param {any} key Key in the key-value pair you will store.
* @param {any} value Value in the key-value pair you will store.
*/
function storeValue(key, value) {
return OfficeRuntime.storage.setItem(key, value).then(function (result) {
return "Success: Item with key '" + key + "' saved to storage.";
}, function (error) {
return "Error: Unable to save item with key '" + key + "' to storage. " + error;
});
}
/**
* @customfunction
* @description Gets value from OfficeRuntime.storage.
* @param {any} key Key of item you intend to get.
*/
function getValue(key) {
return OfficeRuntime.storage.getItem(key);
}
API de diálogo
Las funciones personalizadas tienen su propia API de diálogo, ya que no pueden acceder a la API de Office.js. Sin embargo, las funciones son similares. El escenario más común es iniciar un diálogo para que un usuario inicie sesión y reciba un token de seguridad.
En el siguiente ejemplo de código se muestra cómo mostrar un diálogo web desde una función personalizada.
OfficeRuntime.displayWebDialog('https://myDomain/myDialog.html', {height: 30, width: 20});
Crear un proyecto de funciones personalizadas
Puede crear un proyecto de funciones personalizadas usando el generador Yeoman para los Complementos de Office. Ejecute yo office para iniciar el generador. Después, elija la opción del Proyecto de complemento de funciones personalizadas de Excel. Una vez creado, el proyecto contendrá una carpeta /src/taskpane/ para los archivos de origen del panel de tareas y una carpeta /src/functions para los archivos de origen de las funciones personalizadas.
Nota:
No puede crear ningún proyecto de funciones personalizadas en Visual Studio.
Resumen
En esta unidad, se exploró el modelo de programación de los Complementos de Office, las herramientas para desarrolladores y las funcionalidades de las API de JavaScript de Office para Excel, Outlook y Word.