Office.CustomProperties interface

  • Référence
Paquet:
outlook

L’objet CustomProperties représente des propriétés personnalisées spécifiques à un élément de courrier particulier et spécifiques à un complément Outlook. Par exemple, un complément peut être nécessaire pour enregistrer des données spécifiques au message actuel qui a activé le complément. Si l’utilisateur réexamine le même message à l’avenir et réactive le complément, le complément peut récupérer les données qui avaient été enregistrées en tant que propriétés personnalisées.

Pour en savoir plus sur CustomProperties, consultez Obtenir et définir des métadonnées de complément pour un complément Outlook.

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Lorsque vous utilisez des propriétés personnalisées dans votre complément, gardez à l’esprit que :

  • Les propriétés personnalisées enregistrées en mode composition ne sont pas transmises aux destinataires de l’élément de courrier. Lorsqu’un message ou un rendez-vous avec des propriétés personnalisées est envoyé, ses propriétés sont accessibles à partir de l’élément dans le dossier Éléments envoyés. Si vous souhaitez rendre les données personnalisées accessibles aux destinataires, envisagez d’utiliser InternetHeaders à la place.

  • La longueur maximale d’un CustomProperties objet JSON est de 2 500 caractères.

  • Outlook sur Mac ne met pas en cache les propriétés personnalisées. Si le réseau de l’utilisateur tombe en panne, les compléments de messagerie ne peuvent pas accéder à leurs propriétés personnalisées.

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Méthodes

get(name)

Retourne la valeur de la propriété personnalisée spécifiée.
getAll()

Retourne un objet avec toutes les propriétés personnalisées dans une collection de paires nom/valeur. Les éléments suivants sont équivalents.

customProps.get("name")

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

Vous pouvez itérer au sein de l’objet dictionnaire pour découvrir tous les names et values.
remove(name)

Supprime la propriété spécifiée de la collection de propriétés personnalisées.

Pour rendre la suppression de la propriété permanente, vous devez appeler la méthode saveAsync de l’objet CustomProperties.
saveAsync(callback, asyncContext)

Enregistre les propriétés personnalisées dans un message ou un rendez-vous.

Vous devez appeler la méthode saveAsync pour conserver les modifications effectuées avec la méthode set ou la méthode remove de l’objet CustomProperties. L’enregistrement est une action asynchrone.

Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de saveAsync. Plus particulièrement, un complément de lecture peut être activé lorsque l’utilisateur est connecté dans un formulaire de lecture, puis l’utilisateur peut se déconnecter. Si le complément appelle saveAsync lorsqu’il est déconnecté, saveAsync renvoie une erreur. Votre fonction de rappel doit gérer cette erreur en conséquence.
saveAsync(asyncContext)

Enregistre les propriétés personnalisées dans un message ou un rendez-vous.

Vous devez appeler la méthode saveAsync pour conserver les modifications effectuées avec la méthode set ou la méthode remove de l’objet CustomProperties. L’enregistrement est une action asynchrone.

Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de saveAsync. Plus particulièrement, un complément de lecture peut être activé lorsque l’utilisateur est connecté dans un formulaire de lecture, puis l’utilisateur peut se déconnecter. Si le complément appelle saveAsync lorsqu’il est déconnecté, saveAsync renvoie une erreur. Votre fonction de rappel doit gérer cette erreur en conséquence.
set(name, value)

Affecte la valeur spécifiée à la propriété spécifiée.

La méthode set affecte la valeur spécifiée à la propriété spécifiée. Pour vous assurer que la propriété set et la valeur sont conservées sur l’élément de courrier, vous devez appeler la saveAsync méthode .

La méthode set crée une propriété si la propriété spécifiée n’existe pas déjà ; sinon, la valeur existante est remplacée par la nouvelle valeur. Le paramètre value peut être de n’importe quel type ; toutefois, il est toujours transmis au serveur sous forme de chaîne.

Détails de la méthode

get(name)

Retourne la valeur de la propriété personnalisée spécifiée.

get(name: string): any;

Paramètres

name

string

Nom de la propriété personnalisée à retourner.

Retours

any

Valeur de la propriété personnalisée spécifiée.

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// 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()

Retourne un objet avec toutes les propriétés personnalisées dans une collection de paires nom/valeur. Les éléments suivants sont équivalents.

customProps.get("name")

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

Vous pouvez itérer au sein de l’objet dictionnaire pour découvrir tous les names et values.

getAll(): any;

Retours

any

Objet avec toutes les propriétés personnalisées dans une collection de paires nom/valeur.

Remarques

[ Ensemble d’API : Boîte aux lettres 1.9 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

remove(name)

Supprime la propriété spécifiée de la collection de propriétés personnalisées.

Pour rendre la suppression de la propriété permanente, vous devez appeler la méthode saveAsync de l’objet CustomProperties.

remove(name: string): void;

Paramètres

name

string

name de la propriété à supprimer.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// 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)

Enregistre les propriétés personnalisées dans un message ou un rendez-vous.

Vous devez appeler la méthode saveAsync pour conserver les modifications effectuées avec la méthode set ou la méthode remove de l’objet CustomProperties. L’enregistrement est une action asynchrone.

Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de saveAsync. Plus particulièrement, un complément de lecture peut être activé lorsque l’utilisateur est connecté dans un formulaire de lecture, puis l’utilisateur peut se déconnecter. Si le complément appelle saveAsync lorsqu’il est déconnecté, saveAsync renvoie une erreur. Votre fonction de rappel doit gérer cette erreur en conséquence.

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

Paramètres

callback

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

Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

asyncContext

any

Facultatif. Toutes les données d’état passées à la fonction de rappel.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Important : Dans Outlook sur Windows, les propriétés personnalisées enregistrées en mode composition ne sont conservées qu’après la fermeture de l’élément en cours de composition ou après Office.context.mailbox.item.saveAsync l’appel.

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// 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)

Enregistre les propriétés personnalisées dans un message ou un rendez-vous.

Vous devez appeler la méthode saveAsync pour conserver les modifications effectuées avec la méthode set ou la méthode remove de l’objet CustomProperties. L’enregistrement est une action asynchrone.

Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de saveAsync. Plus particulièrement, un complément de lecture peut être activé lorsque l’utilisateur est connecté dans un formulaire de lecture, puis l’utilisateur peut se déconnecter. Si le complément appelle saveAsync lorsqu’il est déconnecté, saveAsync renvoie une erreur. Votre fonction de rappel doit gérer cette erreur en conséquence.

saveAsync(asyncContext?: any): void;

Paramètres

asyncContext

any

Facultatif. Toutes les données d’état passées à la fonction de rappel.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

set(name, value)

Affecte la valeur spécifiée à la propriété spécifiée.

La méthode set affecte la valeur spécifiée à la propriété spécifiée. Pour vous assurer que la propriété set et la valeur sont conservées sur l’élément de courrier, vous devez appeler la saveAsync méthode .

La méthode set crée une propriété si la propriété spécifiée n’existe pas déjà ; sinon, la valeur existante est remplacée par la nouvelle valeur. Le paramètre value peut être de n’importe quel type ; toutefois, il est toujours transmis au serveur sous forme de chaîne.

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

Paramètres

name

string

Nom de la propriété à définir.

value

string

Valeur de la propriété à définir.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

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