Office.CustomProperties interface
Das CustomProperties Objekt stellt benutzerdefinierte Eigenschaften dar, die für ein bestimmtes E-Mail-Element und ein Outlook-Add-In spezifisch sind. Es kann z. B. erforderlich sein, dass ein Add-In einige Daten speichert, die spezifisch für die aktuelle Nachricht sind, die das Add-In aktiviert hat. Wenn der Benutzer dieselbe Nachricht in Zukunft erneut aufruft und das Add-In erneut aktiviert, kann das Add-In die Daten abrufen, die als benutzerdefinierte Eigenschaften gespeichert wurden.
Weitere Informationen CustomPropertieshierzu finden Sie unter Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In.
Hinweise
Beachten Sie bei der Verwendung benutzerdefinierter Eigenschaften in Ihrem Add-In Folgendes:
Benutzerdefinierte Eigenschaften, die im Verfassen-Modus gespeichert werden, werden nicht an die 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 für Mac speichert keine benutzerdefinierten Eigenschaften zwischen. Wenn das Netzwerk des Benutzers ausfällt, können Mail-Add-Ins nicht auf ihre benutzerdefinierten Eigenschaften zugreifen.
Mindestberechtigungsstufe: Element lesen
Anwendbarer Outlook-Modus: Compose oder Lesen
Verwendet von
- Office.AppointmentCompose: loadCustomPropertiesAsync
- Office.AppointmentRead: loadCustomPropertiesAsync
- Office.LoadedMessageCompose: loadCustomPropertiesAsync
- Office.LoadedMessageRead: loadCustomPropertiesAsync
- Office.MessageCompose: loadCustomPropertiesAsync
- Office.MessageRead: loadCustomPropertiesAsync
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 Äquivalente sind gleichwertig.
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, dass Ihre Rückruffunktion nach Fehlern von |
| save |
Speichert benutzerdefinierte Eigenschaften in einer Nachricht oder einem Termin. Sie müssen die Es empfiehlt sich, dass Ihre Rückruffunktion nach Fehlern von |
| 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
Wichtig: Im klassischen Outlook unter Windows können benutzerdefinierte Eigenschaften, die im Lesemodus in einem E-Mail-Element gespeichert wurden, weiterhin aufgerufen werden, während das Element weitergeleitet wird.
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 = (document.getElementById("get-property-name") as HTMLInputElement).value;
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 Äquivalente sind gleichwertig.
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
Wichtig: Im klassischen Outlook unter Windows können benutzerdefinierte Eigenschaften, die im Lesemodus in einem E-Mail-Element gespeichert wurden, weiterhin aufgerufen werden, während das Element weitergeleitet wird.
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
Die 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 = (document.getElementById("remove-property-name") as HTMLInputElement).value;
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, dass Ihre Rückruffunktion nach Fehlern von saveAsync Insbesondere kann ein Lese-Add-In aktiviert werden, während sich der Benutzer in einem Leseformular in einem verbundenen Zustand befindet und anschließend die Verbindung des Benutzers getrennt wird. Wenn das Add-In aufruft saveAsync , während die Verbindung getrennt ist, saveAsync würde dies 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 bleiben benutzerdefinierte Eigenschaften, die im Kompositionsmodus gespeichert werden, nur erhalten, nachdem das zu verfassende Element geschlossen oder aufgerufen Office.context.mailbox.item.saveAsync 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, dass Ihre Rückruffunktion nach Fehlern von saveAsync Insbesondere kann ein Lese-Add-In aktiviert werden, während sich der Benutzer in einem Leseformular in einem verbundenen Zustand befindet und anschließend die Verbindung des Benutzers getrennt wird. Wenn das Add-In aufruft saveAsync , während die Verbindung getrennt ist, saveAsync würde dies 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 auf dem 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, 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 = (document.getElementById("set-property-name") as HTMLInputElement).value;
const propertyValue = (document.getElementById("property-value") as HTMLInputElement).value;
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);