Freigeben über


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

[ API-Satz: Postfach 1.1 ]

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 CustomProperties JSON-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: Verfassen oder Lesen

Methoden

get(name)

Gibt den Wert der angegebenen benutzerdefinierten Eigenschaft zurück.

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.

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.

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(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.

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.

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

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Verfassen 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

[ API-Satz: Postfach 1.9 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Verfassen 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

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Verfassen 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 = $("#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

[ API-Satz: Postfach 1.1 ]

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: Verfassen 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

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Verfassen 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

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Verfassen 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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);