Compartilhar via

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.
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 = $("#get-property-name").val();
const propertyValue = customProps.get(propertyName);
console.log(`The value of custom property "${propertyName}" is "${propertyValue}".`);

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

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 = $("#remove-property-name").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

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

customProps.saveAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`saveAsync failed with message ${result.error.message}`);
    return;
  }

  console.log(`Custom properties saved with status: ${result.status}`);
});

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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);