Compartir a través de

Office.Context interface

  • Referencia
Paquete:
office

Representa el entorno en tiempo de ejecución del complemento y proporciona acceso a los objetos clave de la API. El contexto actual existe como una propiedad de Office. Se accede a él mediante Office.context.

Comentarios

Información sobre soporte técnico

Para obtener más información sobre los requisitos de servidor y aplicaciones de Office, vea Requisitos para ejecutar complementos de Office.

Aplicaciones admitidas, por plataforma

Office en la web Office en Windows Office en Mac Office en iPad Outlook en dispositivos móviles
Sobresalir Compatible Compatible Compatible Compatible No aplicable
Perspectiva Compatible Compatible Compatible Compatible Compatible
PowerPoint Compatible Compatible Compatible Compatible No aplicable
Proyecto No se admite Compatible Compatible No se admite No aplicable
Word Compatible Compatible Compatible Compatible No aplicable

Propiedades

auth

Ofrece información y acceso al usuario que inició sesión.
commerceAllowed

True, si la plataforma actual permite que el complemento muestre una interfaz de usuario para vender o actualizar; De lo contrario, devuelve False.
contentLanguage

Obtiene la configuración regional (de idioma) especificada por el usuario para editar el documento o el elemento.
diagnostics

Obtiene información sobre el entorno en el que se ejecuta el complemento.
displayLanguage

Obtiene la configuración regional (idioma) especificada por el usuario para la interfaz de usuario de la aplicación de Office.
document

Obtiene un objeto que representa el documento con el que está interactuando el complemento de panel de tareas o de contenido.
host

Contiene la aplicación de Office en la que se ejecuta el complemento.
license

Obtiene la información de licencia para la instalación de Office del usuario.
mailbox

Proporciona acceso al modelo de objetos del complemento de Microsoft Outlook.
officeTheme

Proporciona acceso a las propiedades de los colores del tema de Office.
partitionKey

Obtiene una clave de partición para el almacenamiento local. Los complementos deben usar esta clave de partición como parte de la clave de almacenamiento para almacenar datos de forma segura. La clave de partición está undefined en entornos sin particiones, como los controles del explorador para aplicaciones windows.
platform

Proporciona la plataforma en la que se ejecuta el complemento.
requirements

Proporciona un método para determinar qué conjuntos de requisitos se admiten en la aplicación y plataforma de Office actuales.
roamingSettings

Obtiene un objeto que representa la configuración o el estado personalizado de un complemento de correo que se guardó en el buzón de un usuario.

El RoamingSettings objeto permite almacenar y acceder a los datos de un complemento de correo que se almacena en el buzón de un usuario, por lo que está disponible para ese complemento cuando se ejecuta desde cualquier aplicación cliente que se use para acceder a ese buzón.
sensitivityLabelsCatalog

Obtiene el objeto para comprobar el estado del catálogo de etiquetas de confidencialidad en Outlook y recuperar todas las etiquetas de confidencialidad disponibles si el catálogo está habilitado.
touchEnabled

Especifica si la plataforma y el dispositivo permiten la interacción táctil. True si el complemento se ejecuta en un dispositivo táctil, como un iPad; false en caso contrario.
ui

Proporciona objetos y métodos que puede usar para crear y manipular componentes de la interfaz de usuario, como cuadros de diálogo.
urls

Obtiene el objeto para recuperar las direcciones URL en tiempo de ejecución de un complemento.

Detalles de las propiedades

auth

Nota

Esta API se ofrece a los desarrolladores como versión preliminar y puede cambiar en función de los comentarios que recibamos. No utilice esta API en un entorno de producción.

Ofrece información y acceso al usuario que inició sesión.

auth: Auth;

Valor de propiedad

Office.Auth

commerceAllowed

True, si la plataforma actual permite que el complemento muestre una interfaz de usuario para vender o actualizar; De lo contrario, devuelve False.

commerceAllowed: boolean;

Valor de propiedad

boolean

Comentarios

Aplicaciones: Excel, Word

commerceAllowed solo se admite en Office en iPad.

El App Store de iOS no admite las aplicaciones con complementos que incluyan vínculos a sistemas de pago adicionales. Sin embargo, los complementos de Office que se ejecutan en Office en el escritorio de Windows o en el explorador permiten dichos vínculos. Si quieres que la interfaz de usuario del complemento proporcione un vínculo a un sistema de pago externo en plataformas distintas de iOS, puedes usar la propiedad commerceAllowed para controlar cuándo se muestra ese vínculo.

Ejemplos

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

contentLanguage

Obtiene la configuración regional (de idioma) especificada por el usuario para editar el documento o el elemento.

contentLanguage: string;

Valor de propiedad

string

Comentarios

El contentLanguage valor refleja la configuración de idioma de edición especificada conEl lenguajede opciones>de archivo> en la aplicación de Office.

Información sobre soporte técnico

Para obtener más información sobre los requisitos de servidor y aplicaciones de Office, vea Requisitos para ejecutar complementos de Office.

Aplicaciones admitidas, por plataforma

Office en la web Office en Windows Office en Mac Office en iPad Outlook en dispositivos móviles
Sobresalir Compatible Compatible No se admite Compatible No aplicable
Perspectiva Compatible Compatible Compatible Compatible Compatible
PowerPoint Compatible Compatible No se admite Compatible No aplicable
Proyecto No compatible Compatible No se admite No se admite No aplicable
Word Compatible Compatible No se admite Compatible No aplicable

Ejemplos

function sayHelloWithContentLanguage() {
    const myContentLanguage = Office.context.contentLanguage;
    switch (myContentLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

Obtiene información sobre el entorno en el que se ejecuta el complemento.

diagnostics: ContextInformation;

Valor de propiedad

Office.ContextInformation

Comentarios

Importante: En Outlook, esta propiedad está disponible en el conjunto de requisitos de buzón 1.5. Para todos los conjuntos de requisitos de buzón, puede usar la propiedad Office.context.mailbox.diagnostics para obtener información similar.

Ejemplos

const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

displayLanguage

Obtiene la configuración regional (idioma) especificada por el usuario para la interfaz de usuario de la aplicación de Office.

displayLanguage: string;

Valor de propiedad

string

Comentarios

El valor devuelto es una cadena en el formato de etiqueta de lenguaje RFC 1766, como en-US.

El displayLanguage valor refleja la configuración de idioma de presentación actual especificada conEl lenguajede opciones>de archivo> en la aplicación de Office.

Cuando se usa en Outlook, los modos aplicables se Compose o Leer.

Información sobre soporte técnico

Para obtener más información sobre los requisitos de servidor y aplicaciones de Office, vea Requisitos para ejecutar complementos de Office.

Aplicaciones admitidas, por plataforma

Office en la web Office en Windows Office en Mac Office en iPad Outlook en dispositivos móviles
Sobresalir Compatible Compatible Compatible Compatible No aplicable
Perspectiva Compatible Compatible Compatible Compatible Compatible
PowerPoint Compatible Compatible Compatible Compatible No aplicable
Proyecto No se admite Compatible Compatible No se admite No aplicable
Word No compatible Compatible Compatible Compatible No aplicable

Ejemplos

function sayHelloWithDisplayLanguage() {
    const myDisplayLanguage = Office.context.displayLanguage;
    switch (myDisplayLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

document

Obtiene un objeto que representa el documento con el que está interactuando el complemento de panel de tareas o de contenido.

document: Office.Document;

Valor de propiedad

Office.Document

Ejemplos

// Extension initialization code.
let _document;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Initialize instance variables to access API objects.
    _document = Office.context.document;
    });
}

host

Contiene la aplicación de Office en la que se ejecuta el complemento.

host: HostType;

Valor de propiedad

Office.HostType

Comentarios

Importante: En Outlook, esta propiedad está disponible en el conjunto de requisitos de buzón 1.5. También puede usar la Office.context.diagnostics propiedad para obtener la aplicación a partir del conjunto de requisitos 1.5. Para todos los conjuntos de requisitos de buzón, puede usar la propiedad Office.context.mailbox.diagnostics para obtener información similar.

Ejemplos

const host = Office.context.host;
if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
    // Do something.
} else if (host === Office.HostType.Outlook) {
    // Do something.
}

license

Obtiene la información de licencia para la instalación de Office del usuario.

license: object;

Valor de propiedad

object

Ejemplos

const license = Office.context.license;
console.log(`Office license: ${license}`);

mailbox

Proporciona acceso al modelo de objetos del complemento de Microsoft Outlook.

mailbox: Office.Mailbox;

Valor de propiedad

Office.Mailbox

Comentarios

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Propiedades clave:

  • diagnostics : proporciona información de diagnóstico a un complemento de Outlook.

  • item : proporciona métodos y propiedades para acceder a un mensaje o una cita en un complemento de Outlook.

  • userProfile : proporciona información sobre el usuario en un complemento de Outlook.

Ejemplos

// The following line of code access the item object of the JavaScript API for Office.
const item = Office.context.mailbox.item;

officeTheme

Proporciona acceso a las propiedades de los colores del tema de Office.

officeTheme: OfficeTheme;

Valor de propiedad

Office.OfficeTheme

Ejemplos

function applyOfficeTheme() {
    // Identify the current Office theme in use.
    const currentOfficeTheme = Office.context.officeTheme.themeId;

    if (currentOfficeTheme === Office.ThemeId.Colorful || currentOfficeTheme === Office.ThemeId.White) {
        console.log("No changes required.");
    }

    // Get the colors of the current Office theme.
    const bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
    const bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
    const controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor;
    const controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

    // Apply theme colors to a CSS class.
    $("body").css("background-color", bodyBackgroundColor);

    if (Office.context.officeTheme.isDarkTheme()) {
        $("h1").css("color", controlForegroundColor);
    }
}

partitionKey

Obtiene una clave de partición para el almacenamiento local. Los complementos deben usar esta clave de partición como parte de la clave de almacenamiento para almacenar datos de forma segura. La clave de partición está undefined en entornos sin particiones, como los controles del explorador para aplicaciones windows.

partitionKey: string;

Valor de propiedad

string

Comentarios

Consulte el artículo Persist add-in state and settings (Conservar el estado y la configuración del complemento ) para obtener más información.

Ejemplos

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned. 
    // If so, use the partition to ensure the data is only accessible by your add-in.
    if (myPartitionKey) {
        localStorage.setItem(myPartitionKey + key, value);
    } else {
        localStorage.setItem(key, value);
    }
}

function getFromLocalStorage(key: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned.
    if (myPartitionKey) {
        return localStorage.getItem(myPartitionKey + key);
    } else {
        return localStorage.getItem(key);
    }
}

platform

Proporciona la plataforma en la que se ejecuta el complemento.

platform: PlatformType;

Valor de propiedad

Office.PlatformType

Comentarios

Importante:

  • En Outlook, esta propiedad está disponible en el conjunto de requisitos de buzón 1.5. También puede usar la Office.context.diagnostics propiedad para obtener la plataforma a partir del conjunto de requisitos 1.5. Para todos los conjuntos de requisitos de buzón, puede usar la propiedad Office.context.mailbox.diagnostics para obtener información similar.

  • En Outlook, OfficeOnline se devuelve si un complemento se ejecuta en Outlook en la Web o en el nuevo Outlook en Windows.

Ejemplos

// Request permission from a user to access their devices from Office on the web.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                // Do something with device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);
        });
}

requirements

Proporciona un método para determinar qué conjuntos de requisitos se admiten en la aplicación y plataforma de Office actuales.

requirements: RequirementSetSupport;

Valor de propiedad

Office.RequirementSetSupport

Ejemplos

// To use the setCellProperties API, check if ExcelApi 1.9 is supported.
if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
    const cellProperties: Excel.SettableCellProperties[][] =
    colors2D.map(row =>
        row.map(color =>
            ({
                format: {
                    fill: {
                        color: color
                    }
                }
            })
        )
    );
    sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
}
...

roamingSettings

Obtiene un objeto que representa la configuración o el estado personalizado de un complemento de correo que se guardó en el buzón de un usuario.

El RoamingSettings objeto permite almacenar y acceder a los datos de un complemento de correo que se almacena en el buzón de un usuario, por lo que está disponible para ese complemento cuando se ejecuta desde cualquier aplicación cliente que se use para acceder a ese buzón.

roamingSettings: Office.RoamingSettings;

Valor de propiedad

Office.RoamingSettings

Comentarios

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Get the current value of the 'myKey' setting.
const value = Office.context.roamingSettings.get('myKey');
// Update the value of the 'myKey' setting.
Office.context.roamingSettings.set('myKey', 'Hello World!');
// Persist the change.
Office.context.roamingSettings.saveAsync();

sensitivityLabelsCatalog

Obtiene el objeto para comprobar el estado del catálogo de etiquetas de confidencialidad en Outlook y recuperar todas las etiquetas de confidencialidad disponibles si el catálogo está habilitado.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Valor de propiedad

Office.SensitivityLabelsCatalog

Comentarios

[ Conjunto de API: Buzón 1.13 ]

Nivel mínimo de permiso: elemento de lectura y escritura

Modo de Outlook aplicable: Compose

Ejemplos

// Check if the catalog of sensitivity labels is enabled on the current mailbox.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    // If the catalog is enabled, get all available sensitivity labels.
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                console.log(JSON.stringify(catalog));
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

touchEnabled

Especifica si la plataforma y el dispositivo permiten la interacción táctil. True si el complemento se ejecuta en un dispositivo táctil, como un iPad; false en caso contrario.

touchEnabled: boolean;

Valor de propiedad

boolean

Comentarios

Aplicaciones: Excel, PowerPoint, Word

touchEnabled solo se admite en Office en iPad.

Use la propiedad touchEnabled para determinar cuándo se ejecuta el complemento en un dispositivo táctil y, si es necesario, ajuste el tipo de controles y el tamaño y el espaciado de los elementos en la interfaz de usuario del complemento para dar cabida a las interacciones táctiles.

Ejemplos

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

ui

Proporciona objetos y métodos que puede usar para crear y manipular componentes de la interfaz de usuario, como cuadros de diálogo.

ui: UI;

Valor de propiedad

Office.UI

Ejemplos

// Open a dialog and register an event handler.
Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/myDialog.html",
    { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

urls

Obtiene el objeto para recuperar las direcciones URL en tiempo de ejecución de un complemento.

urls: Urls;

Valor de propiedad

Office.Urls

Comentarios

Aplicaciones: Outlook en la Web y en Windows (clientes nuevos y clásicos)

[ Conjunto de API: Buzón 1.14 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Importante:

  • En Outlook en la Web y nueva Outlook en Windows, esta API no se admite en complementos que implementan un panel de tareas. En estos clientes, la API solo se admite en complementos que implementan la activación basada en eventos o informes de correo no deseado integrados.

  • En Outlook clásico en Windows, esta API se admite en complementos que implementan un panel de tareas, activación basada en eventos o informes de correo no deseado integrados.

Ejemplos

// Get the value of the first parameter of the JavaScript runtime URL.
// For example, if the URL is https://wwww.contoso.com/training?key1=value1&key2=value2,
// the following function logs "First parameter value: value1" to the console.
const url = Office.context.urls.javascriptRuntimeUrl;
const regex = /=([^&]+)/;
console.log(`First parameter value: ${url.match(regex)[1]}`);