Office.CustomProperties interface
Das CustomProperties -Objekt stellt benutzerdefinierte Eigenschaften dar, die für ein bestimmtes E-Mail-Element und für ein Outlook-Add-In spezifisch sind. Beispielsweise kann ein Add-In erforderlich sein, um einige Daten zu speichern, die für die aktuelle Nachricht spezifisch sind, die das Add-In aktiviert hat. Wenn der Benutzer die gleiche Nachricht in Zukunft erneut abruft und das Add-In erneut aktiviert, kann das Add-In die Daten abrufen, die als benutzerdefinierte Eigenschaften gespeichert wurden.
Weitere Informationen zu CustomPropertiesfinden Sie unter Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In.
Hinweise
Beachten Sie folgendes, wenn Sie benutzerdefinierte Eigenschaften in Ihrem Add-In verwenden:
Benutzerdefinierte Eigenschaften, die im Verfassenmodus gespeichert werden, werden nicht an Empfänger des E-Mail-Elements übertragen. Wenn eine Nachricht oder ein Termin mit benutzerdefinierten Eigenschaften gesendet wird, kann über das Element im Ordner Gesendete Elemente auf ihre Eigenschaften zugegriffen werden. Wenn Sie benutzerdefinierte Daten für Empfänger zugänglich machen möchten, sollten Sie stattdessen InternetHeaders verwenden.
Die maximale Länge eines
CustomPropertiesJSON-Objekts beträgt 2500 Zeichen.Outlook auf Mac speichert keine benutzerdefinierten Eigenschaften zwischen. Wenn das Netzwerk des Benutzers ausfällt, können E-Mail-Add-Ins nicht auf ihre benutzerdefinierten Eigenschaften zugreifen.
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Methoden
| get(name) | Gibt den Wert der angegebenen benutzerdefinierten Eigenschaft zurück. |
| get |
Gibt ein Objekt mit allen benutzerdefinierten Eigenschaften in einer Auflistung von Name-Wert-Paaren zurück. Die folgenden Werte sind äquivalent.
Sie können das Wörterbuchobjekt durchlaufen, um alle |
| remove(name) | Entfernt die angegebene Eigenschaft aus der Auflistung benutzerdefinierter Eigenschaften. Damit die Eigenschaft dauerhaft entfernt wird, müssen Sie die |
| save |
Speichert benutzerdefinierte Eigenschaften in einer Nachricht oder einem Termin. Sie müssen die Es empfiehlt sich, die Rückruffunktion auf Fehler von zu überprüfen und zu |
| save |
Speichert benutzerdefinierte Eigenschaften in einer Nachricht oder einem Termin. Sie müssen die Es empfiehlt sich, die Rückruffunktion auf Fehler von zu überprüfen und zu |
| set(name, value) | Legt die angegebene Eigenschaft auf den angegebenen Wert fest. Die Die |
Details zur Methode
get(name)
Gibt den Wert der angegebenen benutzerdefinierten Eigenschaft zurück.
get(name: string): any;Parameter
- name
-
string
Der Name der benutzerdefinierten Eigenschaft, die zurückgegeben werden soll.
Gibt zurück
any
Der Wert der angegebenen benutzerdefinierten Eigenschaft.
Hinweise
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Beispiele
// 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()
Gibt ein Objekt mit allen benutzerdefinierten Eigenschaften in einer Auflistung von Name-Wert-Paaren zurück. Die folgenden Werte sind äquivalent.
customProps.get("name")
var dictionary = customProps.getAll(); dictionary["name"]
Sie können das Wörterbuchobjekt durchlaufen, um alle names und valueszu ermitteln.
getAll(): any;Gibt zurück
any
Ein Objekt mit allen benutzerdefinierten Eigenschaften in einer Auflistung von Name-Wert-Paaren.
Hinweise
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Beispiele
// 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)
Entfernt die angegebene Eigenschaft aus der Auflistung benutzerdefinierter Eigenschaften.
Damit die Eigenschaft dauerhaft entfernt wird, müssen Sie die saveAsync-Methode des CustomProperties-Objekts aufrufen.
remove(name: string): void;Parameter
- name
-
string
Der name der zu entfernenden Eigenschaft.
Gibt zurück
void
Hinweise
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Wichtig: Die remove -Methode wird für eine Nachricht, die derzeit mit der loadItemByIdAsync -Methode geladen wird, nicht unterstützt. Weitere Informationen finden Sie unter Aktivieren Ihres Outlook-Add-Ins für mehrere Nachrichten.
Beispiele
// 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)
Speichert benutzerdefinierte Eigenschaften in einer Nachricht oder einem Termin.
Sie müssen die saveAsync-Methode aufrufen, um alle mit der set-Methode oder der remove-Methode des CustomProperties-Objekts vorgenommenen Änderungen beizubehalten. Die Speichernaktion ist asynchron.
Es empfiehlt sich, die Rückruffunktion auf Fehler von zu überprüfen und zu saveAsyncbehandeln. Insbesondere kann ein Lese-Add-In aktiviert werden, während sich der Benutzer in einem Leseformular in einem verbundenen Zustand befindet und der Benutzer anschließend getrennt wird. Wenn das Add-In im getrennten Zustand aufruft saveAsync , saveAsync würde einen Fehler zurückgeben. Ihre Rückruffunktion sollte diesen Fehler entsprechend behandeln.
saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;Parameter
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.
- asyncContext
-
any
Optional. Alle Zustandsdaten, die an die Rückruffunktion übergeben werden.
Gibt zurück
void
Hinweise
Wichtig: In Outlook unter Windows werden benutzerdefinierte Eigenschaften, die während des Verfassenmodus gespeichert wurden, nur beibehalten, nachdem das zusammengestellte Element geschlossen wurde oder nach Office.context.mailbox.item.saveAsync dem Aufruf aufgerufen wurde.
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Beispiele
// 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)
Speichert benutzerdefinierte Eigenschaften in einer Nachricht oder einem Termin.
Sie müssen die saveAsync-Methode aufrufen, um alle mit der set-Methode oder der remove-Methode des CustomProperties-Objekts vorgenommenen Änderungen beizubehalten. Die Speichernaktion ist asynchron.
Es empfiehlt sich, die Rückruffunktion auf Fehler von zu überprüfen und zu saveAsyncbehandeln. Insbesondere kann ein Lese-Add-In aktiviert werden, während sich der Benutzer in einem Leseformular in einem verbundenen Zustand befindet und der Benutzer anschließend getrennt wird. Wenn das Add-In im getrennten Zustand aufruft saveAsync , saveAsync würde einen Fehler zurückgeben. Ihre Rückruffunktion sollte diesen Fehler entsprechend behandeln.
saveAsync(asyncContext?: any): void;Parameter
- asyncContext
-
any
Optional. Alle Zustandsdaten, die an die Rückruffunktion übergeben werden.
Gibt zurück
void
Hinweise
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
set(name, value)
Legt die angegebene Eigenschaft auf den angegebenen Wert fest.
Die set-Methode legt die angegebene Eigenschaft auf den angegebenen Wert fest. Um sicherzustellen, dass die set-Eigenschaft und der -Wert für das E-Mail-Element beibehalten werden, müssen Sie die saveAsync -Methode aufrufen.
Die set -Methode erstellt eine neue Eigenschaft, wenn die angegebene Eigenschaft noch nicht vorhanden ist. Andernfalls wird der vorhandene Wert durch den neuen Wert ersetzt. Der value Parameter kann einen beliebigen Typ aufweisen. Er wird jedoch immer als Zeichenfolge an den Server übergeben.
set(name: string, value: string): void;Parameter
- name
-
string
Der Name der festzulegenden Eigenschaft.
- value
-
string
Der Wert der festzulegenden Eigenschaft.
Gibt zurück
void
Hinweise
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Wichtig: Die set -Methode wird für eine Nachricht, die derzeit mit der loadItemByIdAsync -Methode geladen wird, nicht unterstützt. Weitere Informationen finden Sie unter Aktivieren Ihres Outlook-Add-Ins für mehrere Nachrichten.
Beispiele
// 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}".`);
Office Add-ins