Office.CustomProperties interface
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. |
get |
Retourne un objet avec toutes les propriétés personnalisées dans une collection de paires nom/valeur. Les éléments suivants sont équivalents.
Vous pouvez itérer au sein de l’objet dictionnaire pour découvrir tous les |
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 |
save |
Enregistre les propriétés personnalisées dans un message ou un rendez-vous. Vous devez appeler la méthode Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de |
save |
Enregistre les propriétés personnalisées dans un message ou un rendez-vous. Vous devez appeler la méthode Il est recommandé de demander à votre fonction de rappel de vérifier et de gérer les erreurs à partir de |
set(name, value) | Affecte la valeur spécifiée à la propriété spécifiée. La méthode La méthode |
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 = $("#get-property-name").val();
const propertyValue = customProps.get(propertyName);
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
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
let allCustomProps;
if (Office.context.requirements.isSetSupported("Mailbox", "1.9")) {
allCustomProps = customProps.getAll();
} else {
allCustomProps = customProps["rawData"];
}
console.log(allCustomProps);
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 = $("#remove-property-name").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
Optional. 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
// 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)
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
Optional. 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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);