Office.RoamingSettings interface

  • Referenz
Paket:
outlook

Die Einstellungen, die mit den Methoden des RoamingSettings-Objekts erstellt werden, werden pro Add-In und pro Benutzer gespeichert. Das heißt, sie sind nur für das Add-In verfügbar, das sie erstellt hat, und nur aus dem Postfach des Benutzers, in dem sie gespeichert sind.

Obwohl die Outlook-Add-In-API den Zugriff auf diese Einstellungen nur auf das Add-In beschränkt, das sie erstellt hat, sollten diese Einstellungen nicht als sicherer Speicher betrachtet werden. Auf sie kann über Exchange-Webdienste oder erweiterte MAPI zugegriffen werden. Sie sollten nicht zum Speichern vertraulicher Informationen wie Benutzeranmeldeinformationen oder Sicherheitstoken verwendet werden.

Der Name einer Einstellung ist eine Zeichenfolge, während der Wert vom Typ „string“, „number“, „boolean“, „null“, „object“ oder „array“ sein kann.

Der Zugriff auf das RoamingSettings-Objekt erfolgt über die roamingSettings-Eigenschaft im Office.context-Namespace.

Weitere Informationen zu RoamingSettingsfinden Sie unter Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In.

Hinweise

[ API-Satz: Postfach 1.1 ]

Wichtig:

  • Das RoamingSettings Objekt wird nur aus dem persistenten Speicher initialisiert, wenn das Add-In zum ersten Mal geladen wird. Für Aufgabenbereiche bedeutet dies, dass sie nur initialisiert wird, wenn der Aufgabenbereich zum ersten Mal geöffnet wird. Wenn der Aufgabenbereich zu einer anderen Seite navigiert oder die aktuelle Seite erneut lädt, wird das In-Memory-Objekt auf seine Anfangswerte zurückgesetzt, auch wenn das Add-In Änderungen beibehalten hat. Die beibehaltenen Änderungen sind erst verfügbar, wenn der Aufgabenbereich (oder das Element bei Add-Ins ohne Benutzeroberfläche) geschlossen und erneut geöffnet wird.

  • Wenn sie über Outlook unter Windows (neu oder klassisch) oder auf Dem Mac festgelegt und gespeichert werden, werden diese Einstellungen erst nach einer Browseraktualisierung in Outlook im Web angezeigt.

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Verfassen oder Lesen

Methoden

get(name)

Ruft die angegebene Einstellung ab.
remove(name)

Entfernt die angegebene Einstellung.
saveAsync(callback)

Speichert die Einstellungen.

Alle Einstellungen, die zuvor von einem Add-In gespeichert wurden, werden beim Initialisieren geladen. Daher können Sie während der Lebensdauer der Sitzung einfach die Set- und get-Methoden verwenden, um mit der Speicherkopie des Eigenschaftenbehälters für Einstellungen zu arbeiten. Wenn Sie die Einstellungen beibehalten möchten, damit sie bei der nächsten Verwendung des Add-Ins verfügbar sind, verwenden Sie die saveAsync -Methode.
set(name, value)

Legt die angegebene Einstellung fest oder erstellt sie.

Die set -Methode erstellt eine neue Einstellung des angegebenen Namens, falls noch nicht vorhanden, oder legt eine vorhandene Einstellung des angegebenen Namens fest. Der Wert wird im Dokument als JSON-Seriendarstellung seines Datentyps gespeichert.

Für die Einstellungen jedes Add-Ins sind maximal 32 KB verfügbar. Ein Fehler mit Code 9057 wird ausgelöst, wenn diese Größenbeschränkung überschritten wird.

Alle Änderungen, die mit der set -Methode an Einstellungen vorgenommen werden, werden erst auf dem Server gespeichert, wenn die saveAsync Methode aufgerufen wird.

Details zur Methode

get(name)

Ruft die angegebene Einstellung ab.

get(name: string): any;

Parameter

name

string

Der Name der abzurufenden Einstellung. Bei der Angabe des Namens wird die Groß-/Kleinschreibung berücksichtigt.

Gibt zurück

any

Typ: Zeichenfolge | Zahl | Boolescher Wert | Objekt | Anordnung

Hinweise

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Verfassen oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);

remove(name)

Entfernt die angegebene Einstellung.

remove(name: string): void;

Parameter

name

string

Der Name der zu entfernenden Einstellung. Bei der Angabe des Namens wird die Groß-/Kleinschreibung berücksichtigt.

Gibt zurück

void

Hinweise

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Verfassen oder Lesen

saveAsync(callback)

Speichert die Einstellungen.

Alle Einstellungen, die zuvor von einem Add-In gespeichert wurden, werden beim Initialisieren geladen. Daher können Sie während der Lebensdauer der Sitzung einfach die Set- und get-Methoden verwenden, um mit der Speicherkopie des Eigenschaftenbehälters für Einstellungen zu arbeiten. Wenn Sie die Einstellungen beibehalten möchten, damit sie bei der nächsten Verwendung des Add-Ins verfügbar sind, verwenden Sie die saveAsync -Methode.

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

Parameter

callback

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

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.

Gibt zurück

void

Hinweise

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Verfassen oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
  } else {
    console.log(`Settings saved with status: ${result.status}`);
  }
});

set(name, value)

Legt die angegebene Einstellung fest oder erstellt sie.

Die set -Methode erstellt eine neue Einstellung des angegebenen Namens, falls noch nicht vorhanden, oder legt eine vorhandene Einstellung des angegebenen Namens fest. Der Wert wird im Dokument als JSON-Seriendarstellung seines Datentyps gespeichert.

Für die Einstellungen jedes Add-Ins sind maximal 32 KB verfügbar. Ein Fehler mit Code 9057 wird ausgelöst, wenn diese Größenbeschränkung überschritten wird.

Alle Änderungen, die mit der set -Methode an Einstellungen vorgenommen werden, werden erst auf dem Server gespeichert, wenn die saveAsync Methode aufgerufen wird.

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

Parameter

name

string

Der Name der festzulegenden oder zu erstellenden Einstellung. Groß-/Kleinschreibung des Namens wird beachtet.

value

any

Gibt den zu speichernden Wert an.

Gibt zurück

void

Hinweise

[ API-Satz: Postfach 1.1 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Verfassen oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);