Compartilhar via

Office.CustomProperties interface

  • Referência
Pacote:
outlook

O CustomProperties objeto representa propriedades personalizadas específicas de um item de correio específico e específicas de um suplemento do Outlook. Por exemplo, pode ser necessário um suplemento para guardar alguns dados específicos da mensagem atual que ativou o suplemento. Se o utilizador revisitar a mesma mensagem no futuro e ativar novamente o suplemento, o suplemento poderá obter os dados que foram guardados como propriedades personalizadas.

Para saber mais sobre CustomPropertieso , consulte Obter e definir metadados de suplementos para um suplemento do Outlook.

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Ao utilizar propriedades personalizadas no seu suplemento, tenha em atenção que:

  • As propriedades personalizadas guardadas no modo de composição não são transmitidas aos destinatários do item de correio. Quando é enviada uma mensagem ou compromisso com propriedades personalizadas, as respetivas propriedades podem ser acedidas a partir do item na pasta Itens Enviados. Se quiser tornar os dados personalizados acessíveis aos destinatários, considere antes utilizar InternetHeaders .

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

  • O Outlook para Mac não coloca em cache propriedades personalizadas. Se a rede do utilizador ficar inativa, os suplementos de correio não poderão aceder às respetivas propriedades personalizadas.

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

Modo Outlook aplicável: Compor ou Ler

Métodos

get(name)

Retorna o valor da propriedade personalizada especificada.
getAll()

Devolve um objeto com todas as propriedades personalizadas numa coleção de pares nome/valor. Seguem-se equivalentes.

customProps.get("name")

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

Pode iterar através do objeto do dicionário para detetar 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)

Guarda propriedades personalizadas numa 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 a função de chamada de retorno verifique e processe 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. A função de chamada de retorno deve processar este erro em conformidade.
saveAsync(asyncContext)

Guarda propriedades personalizadas numa 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 a função de chamada de retorno verifique e processe 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. A função de chamada de retorno deve processar este erro em conformidade.
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 persistem no item de correio, tem de 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: ler item

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}".`);

getAll()

Devolve um objeto com todas as propriedades personalizadas numa coleção de pares nome/valor. Seguem-se equivalentes.

customProps.get("name")

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

Pode iterar através do objeto do dicionário para detetar todos names e values.

getAll(): any;

Retornos

any

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

Comentários

[ Conjunto de API: Caixa de Correio 1.9 ]

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

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

let allCustomProps;
if (Office.context.requirements.isSetSupported("Mailbox", "1.9")) {
  allCustomProps = customProps.getAll();
} else {
  allCustomProps = customProps["rawData"];
}

console.log(allCustomProps);

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

O name da propriedade a ser removida.

Retornos

void

Comentários

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

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)

Guarda propriedades personalizadas numa 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 a função de chamada de retorno verifique e processe 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. A função de chamada de retorno deve processar este erro em conformidade.

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

Parâmetros

callback

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

Quando o método for concluído, a função transmitida 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 transmitidos para a função de chamada de retorno.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Importante: no Outlook no Windows, as propriedades personalizadas guardadas no modo de composição só persistem depois de o item ser composto ser fechado ou depois Office.context.mailbox.item.saveAsync de ser chamado.

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

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)

Guarda propriedades personalizadas numa 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 a função de chamada de retorno verifique e processe 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. A função de chamada de retorno deve processar este erro em conformidade.

saveAsync(asyncContext?: any): void;

Parâmetros

asyncContext

any

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

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

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

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 persistem no item de correio, tem de 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: ler item

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}".`);