Office.CustomProperties interface

  • Referência
Pacote:
outlook

O CustomProperties objeto representa propriedades personalizadas específicas para um determinado item de email e específicas para um suplemento do Outlook. Por exemplo, pode haver a necessidade de um suplemento para salvar alguns dados específicos da mensagem atual que ativou o suplemento. Se o usuário revisitar a mesma mensagem no futuro e ativar o suplemento novamente, o suplemento poderá recuperar os dados salvos como propriedades personalizadas.

Para saber mais sobre CustomProperties, confira Obter e definir metadados de suplemento para um suplemento do Outlook.

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Ao usar propriedades personalizadas no suplemento, tenha em mente que:

  • As propriedades personalizadas salvas enquanto estiverem no modo de composição não são transmitidas aos destinatários do item de email. Quando uma mensagem ou compromisso com propriedades personalizadas é enviada, suas propriedades podem ser acessadas a partir do item na pasta Itens Enviados. Se você quiser tornar os dados personalizados acessíveis aos destinatários, considere usar InternetHeaders .

  • O comprimento máximo de um CustomProperties objeto JSON é de 2500 caracteres.

  • O Outlook no Mac não armazena em cache propriedades personalizadas. Se a rede do usuário diminuir, os suplementos de email não poderão acessar suas propriedades personalizadas.

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

Métodos

get(name)

Retorna o valor da propriedade personalizada especificada.
getAll()

Retorna um objeto com todas as propriedades personalizadas em uma coleção de pares de nome/valor. Os seguintes são equivalentes.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Você pode iterar por meio do objeto dicionário para descobrir todos names e values.
remove(name)

Remove a propriedade especificada do conjunto de propriedades personalizadas.

Para tornar a remoção da propriedade permanente, você precisa chamar o método saveAsync do objeto CustomProperties
saveAsync(callback, asyncContext)

Salva propriedades personalizadas em uma mensagem ou compromisso.

Você precisa chamar o método saveAsync para manter as alterações feitas com o método set ou o método remove do objeto CustomProperties. A ação de salvar é assíncrona.

É uma boa prática fazer com que sua função de retorno de chamada verifique e manuseie erros de saveAsync. Em particular, um suplemento de leitura pode ser ativado enquanto o usuário estiver em um estado conectado em um formulário de leitura e, posteriormente, o usuário for desconectado. Se o suplemento chamar saveAsync enquanto estiver no estado desconectado, saveAsync retornará um erro. Sua função de retorno de chamada deve lidar com esse erro de acordo.
saveAsync(asyncContext)

Salva propriedades personalizadas em uma mensagem ou compromisso.

Você precisa chamar o método saveAsync para manter as alterações feitas com o método set ou o método remove do objeto CustomProperties. A ação de salvar é assíncrona.

É uma boa prática fazer com que sua função de retorno de chamada verifique e manuseie erros de saveAsync. Em particular, um suplemento de leitura pode ser ativado enquanto o usuário estiver em um estado conectado em um formulário de leitura e, posteriormente, o usuário for desconectado. Se o suplemento chamar saveAsync enquanto estiver no estado desconectado, saveAsync retornará um erro. Sua função de retorno de chamada deve lidar com esse erro de acordo.
set(name, value)

Define a propriedade especificada com o valor especificado.

O método set define a propriedade especificada com o valor especificado. Para garantir que a propriedade e o valor definidos persistam no item de email, você deve chamar o saveAsync método.

O método set cria uma nova propriedade se a propriedade especificada não existir; caso contrário, o valor existente será substituído pelo novo valor. O parâmetro value pode ser de qualquer tipo; no entanto, sempre é passado ao servidor como uma cadeia de caracteres.

Detalhes do método

get(name)

Retorna o valor da propriedade personalizada especificada.

get(name: string): any;

Parâmetros

name

string

O nome da propriedade personalizada a ser retornado.

Retornos

any

O valor da propriedade personalizada especificada.

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
const propertyValue = customProps.get(propertyName);
$("#propertyValue").val(propertyValue);
console.log(`The value of custom property "${propertyName}" is "${propertyValue}".`);

getAll()

Retorna um objeto com todas as propriedades personalizadas em uma coleção de pares de nome/valor. Os seguintes são equivalentes.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Você pode iterar por meio do objeto dicionário para descobrir todos names e values.

getAll(): any;

Retornos

any

Um objeto com todas as propriedades personalizadas em uma coleção de pares de nome/valor.

Comentários

[ Conjunto de API: Caixa de correio 1.9 ]

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

remove(name)

Remove a propriedade especificada do conjunto de propriedades personalizadas.

Para tornar a remoção da propriedade permanente, você precisa chamar o método saveAsync do objeto CustomProperties

remove(name: string): void;

Parâmetros

name

string

A name da propriedade a ser removida.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);

saveAsync(callback, asyncContext)

Salva propriedades personalizadas em uma mensagem ou compromisso.

Você precisa chamar o método saveAsync para manter as alterações feitas com o método set ou o método remove do objeto CustomProperties. A ação de salvar é assíncrona.

É uma boa prática fazer com que sua função de retorno de chamada verifique e manuseie erros de saveAsync. Em particular, um suplemento de leitura pode ser ativado enquanto o usuário estiver em um estado conectado em um formulário de leitura e, posteriormente, o usuário for desconectado. Se o suplemento chamar saveAsync enquanto estiver no estado desconectado, saveAsync retornará um erro. Sua função de retorno de chamada deve lidar com esse erro de acordo.

saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;

Parâmetros

callback

(asyncResult: Office.AsyncResult<void>) => void

Quando o método é concluído, a função passada no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

asyncContext

any

Opcional. Todos os dados de estado que são passados para a função de retorno de chamada.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Importante: no Outlook no Windows, as propriedades personalizadas salvas enquanto estiverem no modo de composição só persistem depois que o item que está sendo composto for fechado ou depois Office.context.mailbox.item.saveAsync for chamado.

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

Exemplos

// The following JavaScript code sample shows how to asynchronously use
// the loadCustomPropertiesAsync method to load custom properties that
// are specific to the current item, and the saveAsync method to save
// these to the mail item. After loading the custom properties,
// the code sample uses the get method to read the custom property myProp,
// the set method to write the custom property myProp, and then finally
// calls the saveAsync method to save the custom properties.

// 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, add-in-specific code can run.
        const item = Office.context.mailbox.item;
        item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");
    console.log("myProp: " + myProp); // First run on current item will return `undefined`.

    // Set myProp custom property.
    customProps.set("myProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);
    }
    else {
        // Async call to save custom properties completed.
        // Proceed to do the appropriate for your add-in.
    }
}

saveAsync(asyncContext)

Salva propriedades personalizadas em uma mensagem ou compromisso.

Você precisa chamar o método saveAsync para manter as alterações feitas com o método set ou o método remove do objeto CustomProperties. A ação de salvar é assíncrona.

É uma boa prática fazer com que sua função de retorno de chamada verifique e manuseie erros de saveAsync. Em particular, um suplemento de leitura pode ser ativado enquanto o usuário estiver em um estado conectado em um formulário de leitura e, posteriormente, o usuário for desconectado. Se o suplemento chamar saveAsync enquanto estiver no estado desconectado, saveAsync retornará um erro. Sua função de retorno de chamada deve lidar com esse erro de acordo.

saveAsync(asyncContext?: any): void;

Parâmetros

asyncContext

any

Opcional. Todos os dados de estado que são passados para a função de retorno de chamada.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

set(name, value)

Define a propriedade especificada com o valor especificado.

O método set define a propriedade especificada com o valor especificado. Para garantir que a propriedade e o valor definidos persistam no item de email, você deve chamar o saveAsync método.

O método set cria uma nova propriedade se a propriedade especificada não existir; caso contrário, o valor existente será substituído pelo novo valor. O parâmetro value pode ser de qualquer tipo; no entanto, sempre é passado ao servidor como uma cadeia de caracteres.

set(name: string, value: string): void;

Parâmetros

name

string

O nome da propriedade a ser definido.

value

string

O valor da propriedade a ser definido.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: item de leitura

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
const propertyValue = $("#propertyValue").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);