Office.RoamingSettings interface
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 in dem Postfach des Benutzers, in dem sie gespeichert sind.
Obwohl die Outlook-Add-In-API den Zugriff auf diese Einstellungen auf das Add-In beschränkt, das sie erstellt hat, sollten diese Einstellungen nicht als sicherer Speicher betrachtet werden. Exchange-Webdienste oder Extended MAPI können auf sie zugreifen. 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 RoamingSettingshierzu finden Sie unter Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In.
Hinweise
Wichtig:
Das
RoamingSettingsObjekt wird nur beim ersten Laden des Add-Ins aus dem persistenten Speicher initialisiert. Für Aufgabenbereiche bedeutet dies, dass er nur initialisiert wird, wenn der Aufgabenbereich zum ersten Mal geöffnet wird. Wenn der Aufgabenbereich zu einer anderen Seite navigiert oder die aktuelle Seite neu lädt, wird das In-Memory-Objekt auf seine Anfangswerte zurückgesetzt, auch wenn Ihr Add-In über persistente Änderungen verfügt. Die persistenten Änderungen sind erst verfügbar, wenn der Aufgabenbereich (oder das Element bei Add-Ins ohne Benutzeroberfläche) geschlossen und erneut geöffnet wird.Wenn im klassischen Outlook unter Windows Roamingeinstellungen auf einem anderen Outlook-Client konfiguriert wurden, muss der Desktopclient nicht neu gestartet werden. Das Add-In muss jedoch neu geladen werden, um auf diese Einstellungen zugreifen zu können. In Outlook im Web, auf dem Mac und im neuen Outlook unter Windows müssen Sie den Browser aktualisieren oder den Client neu starten, um auf Roamingeinstellungen zuzugreifen, die auf einem anderen Client festgelegt wurden.
Mindestberechtigungsstufe: Eingeschränkt
Anwendbarer Outlook-Modus: Compose oder Lesen
Verwendet von
Methoden
| get(name) | Ruft die angegebene Einstellung ab. |
| remove(name) | Entfernt die angegebene Einstellung. |
| save |
Speichert die Einstellungen. Alle Einstellungen, die zuvor von einem Add-In gespeichert wurden, werden beim Initialisieren geladen, sodass Sie während der Lebensdauer der Sitzung einfach den Satz verwenden und Methoden abrufen können, um mit der In-Memory-Kopie des Eigenschaftenbehälters für die Einstellungen zu arbeiten. Wenn Sie die Einstellungen beibehalten möchten, sodass sie bei der nächsten Verwendung des Add-Ins verfügbar sind, verwenden Sie die |
| set(name, value) | Legt die angegebene Einstellung fest oder erstellt sie. Die Für die Einstellungen jedes Add-Ins stehen maximal 32 KB zur Verfügung. Ein Fehler mit Code 9057 wird ausgelöst, wenn dieses Größenlimit überschritten wird. Alle Änderungen, die mit der |
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
Type: String | Anzahl | Boolescher Wert | Objekt | Matrix
Hinweise
Mindestberechtigungsstufe: Eingeschränkt
Anwendbarer Outlook-Modus: Compose 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 = (document.getElementById("settingName") as HTMLInputElement).value;
const settingValue = Office.context.roamingSettings.get(settingName);
(document.getElementById("settingValue") as HTMLInputElement).value = 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
Mindestberechtigungsstufe: Eingeschränkt
Anwendbarer Outlook-Modus: Compose oder Lesen
Beispiele
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
// Remove the specified setting from the mailbox.
const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
Office.context.roamingSettings.remove(settingName);
console.log(`The "${settingName}" setting has been removed.`);
saveAsync(callback)
Speichert die Einstellungen.
Alle Einstellungen, die zuvor von einem Add-In gespeichert wurden, werden beim Initialisieren geladen, sodass Sie während der Lebensdauer der Sitzung einfach den Satz verwenden und Methoden abrufen können, um mit der In-Memory-Kopie des Eigenschaftenbehälters für die Einstellungen zu arbeiten. Wenn Sie die Einstellungen beibehalten möchten, sodass 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
Mindestberechtigungsstufe: Eingeschränkt
Anwendbarer Outlook-Modus: Compose 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, wenn sie noch nicht vorhanden ist, 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 stehen maximal 32 KB zur Verfügung. Ein Fehler mit Code 9057 wird ausgelöst, wenn dieses Größenlimit überschritten wird.
Alle Änderungen, die mit der set Methode an den Einstellungen vorgenommen wurden, werden erst dann 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
Mindestberechtigungsstufe: Eingeschränkt
Anwendbarer Outlook-Modus: Compose 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 = (document.getElementById("settingName") as HTMLInputElement).value;
const settingValue = (document.getElementById("settingValue") as HTMLInputElement).value;
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);