Office.Settings interface

Stellt benutzerdefinierte Einstellungen für ein Aufgabenbereich- oder Inhalts-Add-In dar, die im Hostdokument als Name/Wert-Paare gespeichert werden.

Hinweise

Hosts: Excel, PowerPoint, Word

Die mit den Methoden des Settings-Objekts erstellten Einstellungen werden pro Add-In und pro Dokument gespeichert. Das bedeutet, dass sie nur für das Add-In verfügbar sind, die sie erstellt hat, und nur aus dem Dokument, in dem sie gespeichert wurden.

Der Name einer Einstellung ist eine Zeichenfolge, während es sich bei dem Wert um eine Zeichenfolge, eine Zahl, einen booleschen Wert, null, ein Objekt oder ein Array handelt.

Das Settings-Objekt wird automatisch als Teil des Document-Objekts geladen und ist durch Aufrufen der settings-Eigenschaft dieses Objekts verfügbar, wenn das Add-In aktiviert wird.

Der Entwickler ist dafür verantwortlich, die saveAsync-Methode nach dem Hinzufügen oder Entfernen von Einstellungen aufzurufen, um die Einstellungen im Dokument zu speichern.

Methoden

addHandlerAsync(eventType, handler, options, callback)

Fügt einen Ereignishandler für das settingsChanged-Ereignis hinzu.

Wichtig: Der Code Ihres Add-Ins kann einen Handler für das settingsChanged-Ereignis registrieren, wenn das Add-In mit einem beliebigen Excel-Client ausgeführt wird. Das Ereignis wird jedoch nur ausgelöst, wenn das Add-In mit einer Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehrere Benutzer die Kalkulationstabelle bearbeiten (mitautorisieren). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Gemeinsamen Dokumentierungsszenarien unterstützt.

addHandlerAsync(eventType, handler, callback)

Fügt einen Ereignishandler für das settingsChanged-Ereignis hinzu.

Wichtig: Der Code Ihres Add-Ins kann einen Handler für das settingsChanged-Ereignis registrieren, wenn das Add-In mit einem beliebigen Excel-Client ausgeführt wird. Das Ereignis wird jedoch nur ausgelöst, wenn das Add-In mit einer Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehrere Benutzer die Kalkulationstabelle bearbeiten (mitautorisieren). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Gemeinsamen Dokumentierungsszenarien unterstützt.

get(name)

Ruft die angegebene Einstellung ab.

refreshAsync(callback)

Liest alle im Dokument beibehaltenen Einstellungen und aktualisiert die Kopie dieser Einstellungen im Speicher des Inhalts- oder Aufgabenbereich-Add-In.

remove(name)

Entfernt die angegebene Einstellung.

Wichtig: Beachten Sie, dass sich die Settings.remove-Methode nur auf die im Arbeitsspeicher gespeicherte Kopie des Einstellungseigenschafts-Bag auswirkt. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

removeHandlerAsync(eventType, options, callback)

Entfernt einen Ereignishandler für das settingsChanged-Ereignis.

removeHandlerAsync(eventType, callback)

Entfernt einen Ereignishandler für das settingsChanged-Ereignis.

saveAsync(options, callback)

Speichert die speicherinterne Kopie des Eigenschaftenbehälters für Einstellungen dauerhaft im Dokument.

saveAsync(callback)

Speichert die speicherinterne Kopie des Eigenschaftenbehälters für Einstellungen dauerhaft im Dokument.

set(name, value)

Legt die angegebene Einstellung fest oder erstellt sie.

Wichtig: Beachten Sie, dass sich die Settings.set-Methode nur auf die im Arbeitsspeicher gespeicherte Kopie des Einstellungseigenschafts-Bag auswirkt. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

Details zur Methode

addHandlerAsync(eventType, handler, options, callback)

Fügt einen Ereignishandler für das settingsChanged-Ereignis hinzu.

Wichtig: Der Code Ihres Add-Ins kann einen Handler für das settingsChanged-Ereignis registrieren, wenn das Add-In mit einem beliebigen Excel-Client ausgeführt wird. Das Ereignis wird jedoch nur ausgelöst, wenn das Add-In mit einer Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehrere Benutzer die Kalkulationstabelle bearbeiten (mitautorisieren). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Gemeinsamen Dokumentierungsszenarien unterstützt.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameter

eventType
Office.EventType

Gibt den Ereignistyp an, der hinzugefügt werden soll. Erforderlich.

handler

any

Die hinzuzufügende Ereignishandlerfunktion, deren einziger Parameter den Typ Office.SettingsChangedEventArgs hat.. Erforderlich.

options
Office.AsyncContextOptions

Stellt eine Option zum Beibehalten von Kontextdaten eines beliebigen Typs zur Verwendung in einem Rückruf zur Verfügung.

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Eigenschaft Verwendung
AsyncResult.value Gibt immer undefined zurück, da es beim Hinzufügen eines Ereignishandlers keine Daten oder Objekte gibt, die abgerufen werden können.
AsyncResult.status Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
AsyncResult.error Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
AsyncResult.asyncContext Ein benutzerdefiniertes Element beliebigen Typs, das im AsyncResult-Objekt ohne Änderung zurückgegeben wird.

Gibt zurück

void

Hinweise

Anforderungssatz: Nicht in einem Satz

Sie können mehrere Ereignishandler für den angegebenen eventType hinzufügen, solange der Name jeder Ereignishandlerfunktion eindeutig ist.

addHandlerAsync(eventType, handler, callback)

Fügt einen Ereignishandler für das settingsChanged-Ereignis hinzu.

Wichtig: Der Code Ihres Add-Ins kann einen Handler für das settingsChanged-Ereignis registrieren, wenn das Add-In mit einem beliebigen Excel-Client ausgeführt wird. Das Ereignis wird jedoch nur ausgelöst, wenn das Add-In mit einer Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehrere Benutzer die Kalkulationstabelle bearbeiten (mitautorisieren). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Gemeinsamen Dokumentierungsszenarien unterstützt.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

Parameter

eventType
Office.EventType

Gibt den Ereignistyp an, der hinzugefügt werden soll. Erforderlich.

handler

any

Die hinzuzufügende Ereignishandlerfunktion, deren einziger Parameter den Typ Office.SettingsChangedEventArgs hat.. Erforderlich.

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Eigenschaft Verwendung
AsyncResult.value Gibt immer undefined zurück, da es beim Hinzufügen eines Ereignishandlers keine Daten oder Objekte gibt, die abgerufen werden können.
AsyncResult.status Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
AsyncResult.error Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
AsyncResult.asyncContext Ein benutzerdefiniertes Element beliebigen Typs, das im AsyncResult-Objekt ohne Änderung zurückgegeben wird.

Gibt zurück

void

Hinweise

Anforderungssatz: Nicht in einem Satz

Sie können mehrere Ereignishandler für den angegebenen eventType hinzufügen, solange der Name jeder Ereignishandlerfunktion eindeutig ist.

Beispiele

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

get(name)

Ruft die angegebene Einstellung ab.

get(name: string): any;

Parameter

name

string

Gibt zurück

any

Ein Objekt mit Eigenschaftsnamen, die JSON serialisierten Werten zugeordnet sind.

Hinweise

Anforderungssatz: Einstellungen

Beispiele

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

refreshAsync(callback)

Liest alle im Dokument beibehaltenen Einstellungen und aktualisiert die Kopie dieser Einstellungen im Speicher des Inhalts- oder Aufgabenbereich-Add-In.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

Parameter

callback

(result: Office.AsyncResult<Office.Settings>) => void

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist.. Die value Eigenschaft des Ergebnisses ist ein Office.Settings-Objekt mit den aktualisierten Werten.

Gibt zurück

void

Hinweise

Anforderungssatz: Nicht in einem Satz

Diese Methode ist in Excel-, Word- und PowerPoint-Szenarien hilfreich, wenn mehrere Instanzen desselben Add-Ins für dasselbe Dokument arbeiten. Da jedes Add-In mit einer In-Memory-Kopie der Einstellungen arbeitet, die zum Zeitpunkt des Öffnens des Dokuments aus dem Dokument geladen wurden, können die von jedem Benutzer verwendeten Einstellungswerte nicht mehr synchronisiert werden. Dies kann vorkommen, wenn eine Instanz des Add-Ins die Settings.saveAsync-Methode aufruft, um alle Einstellungen dieses Benutzers im Dokument zu speichern. Durch Aufrufen der refreshAsync-Methode aus dem Ereignishandler für das settingsChanged-Ereignis des Add-Ins werden die Einstellungswerte für alle Benutzer aktualisiert.

In der callback-Funktion, die an die refreshAsync-Methode weitergegeben wird, können Sie die Eigenschaften des AsyncResult-Objekts verwenden, um die folgenden Informationen zurückzugeben.

Eigenschaft Verwendung
AsyncResult.value Zugriff auf ein Einstellungen-Objekt mit den aktualisierten Werten.
AsyncResult.status Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
AsyncResult.error Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
AsyncResult.asyncContext Ein benutzerdefiniertes Element beliebigen Typs, das im AsyncResult-Objekt ohne Änderung zurückgegeben wird.

Beispiele

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

remove(name)

Entfernt die angegebene Einstellung.

Wichtig: Beachten Sie, dass sich die Settings.remove-Methode nur auf die im Arbeitsspeicher gespeicherte Kopie des Einstellungseigenschafts-Bag auswirkt. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

remove(name: string): void;

Parameter

name

string

Gibt zurück

void

Hinweise

Anforderungssatz: Einstellungen

null ist ein gültiger Wert für eine Einstellung. Daher wird durch Zuweisen von null zu der Einstellung diese nicht aus dem Eigenschaftenbehälter für Einstellungen entfernt.

Beispiele

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

Entfernt einen Ereignishandler für das settingsChanged-Ereignis.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameter

eventType
Office.EventType

Gibt den Typ des zu entfernenden Ereignisses an. Erforderlich.

options
Office.RemoveHandlerOptions

Stellt Optionen zur Verfügung, um zu bestimmen, welche Ereignishandler oder Handler entfernt werden.

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Gibt zurück

void

Hinweise

Anforderungssatz: Nicht in einem Satz

Wenn der optionale handler-Parameter beim Aufrufen der removeHandlerAsync-Methode nicht angegeben wird, werden alle Ereignishandler für den angegebenen eventType entfernt.

Wenn die Funktion, die Sie an den callback-Parameter übergeben haben, ausgeführt wird, empfängt sie ein AsyncResult-Objekt, auf das Sie vom einzigen Parameter der Rückruffunktion aus zugreifen können.

In der Rückruffunktion, die Sie an die removeHandlerAsync-Methode übergeben haben, können Sie die Eigenschaften des AsyncResult-Objekts verwenden, um die folgenden Informationen zurückzugeben.

removeHandlerAsync(eventType, callback)

Entfernt einen Ereignishandler für das settingsChanged-Ereignis.

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Parameter

eventType
Office.EventType

Gibt den Typ des zu entfernenden Ereignisses an. Erforderlich.

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Gibt zurück

void

Hinweise

Anforderungssatz: Nicht in einem Satz

Wenn der optionale handler-Parameter beim Aufrufen der removeHandlerAsync-Methode nicht angegeben wird, werden alle Ereignishandler für den angegebenen eventType entfernt.

Wenn die Funktion, die Sie an den callback-Parameter übergeben haben, ausgeführt wird, empfängt sie ein AsyncResult-Objekt, auf das Sie vom einzigen Parameter der Rückruffunktion aus zugreifen können.

In der Rückruffunktion, die Sie an die removeHandlerAsync-Methode übergeben haben, können Sie die Eigenschaften des AsyncResult-Objekts verwenden, um die folgenden Informationen zurückzugeben.

Beispiele

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

saveAsync(options, callback)

Speichert die speicherinterne Kopie des Eigenschaftenbehälters für Einstellungen dauerhaft im Dokument.

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameter

options
Office.SaveSettingsOptions

Stellt Optionen zum Speichern von Einstellungen zur Verfügung.

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Gibt zurück

void

Hinweise

Anforderungssatz: Einstellungen

Alle von einem Add-In bereits gespeicherten Einstellungen werden bei der Initialisierung geladen, daher können Sie während der Gültigkeitszeit der Sitzung einfach die Methoden set und get verwenden, um mit der speicherinternen Kopie des Einstellungseigenschaftenbehälters zu arbeiten. Wenn Sie die Einstellungen speichern möchten, damit sie bei der nächsten Verwendung des Add-Ins verfügbar sind, verwenden Sie die saveAsync-Methode.

Hinweis: Die saveAsync-Methode enthält den Eigenschaftenspeicher für Speichereinstellungen in der Dokumentdatei. Die Änderungen an der Dokumentdatei selbst werden jedoch nur gespeichert, wenn der Benutzer (oder die AutoRecover-Einstellung) das Dokument im Dateisystem speichert. Die refreshAsync-Methode ist nur in Szenarien hilfreich, in denen andere Instanzen desselben Add-Ins die Einstellungen ändern können und diese Änderungen allen Instanzen zur Verfügung stehen sollten.

Eigenschaft Verwendung
AsyncResult.value Gibt immer undefined zurück, weil kein Objekt oder Daten zum Abruf existieren.
AsyncResult.status Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
AsyncResult.error Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
AsyncResult.asyncContext Ein benutzerdefiniertes Element beliebigen Typs, das im AsyncResult-Objekt ohne Änderung zurückgegeben wird.

saveAsync(callback)

Speichert die speicherinterne Kopie des Eigenschaftenbehälters für Einstellungen dauerhaft im Dokument.

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

Parameter

callback

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

Optional. Eine Funktion, die beim Zurückgeben des Rückrufs aufgerufen wird, deren einziger Parameter vom Typ Office.AsyncResult ist..

Gibt zurück

void

Hinweise

Anforderungssatz: Einstellungen

Alle von einem Add-In bereits gespeicherten Einstellungen werden bei der Initialisierung geladen, daher können Sie während der Gültigkeitszeit der Sitzung einfach die Methoden set und get verwenden, um mit der speicherinternen Kopie des Einstellungseigenschaftenbehälters zu arbeiten. Wenn Sie die Einstellungen speichern möchten, damit sie bei der nächsten Verwendung des Add-Ins verfügbar sind, verwenden Sie die saveAsync-Methode.

Hinweis: Die saveAsync-Methode enthält den Eigenschaftenspeicher für Speichereinstellungen in der Dokumentdatei. Die Änderungen an der Dokumentdatei selbst werden jedoch nur gespeichert, wenn der Benutzer (oder die AutoRecover-Einstellung) das Dokument im Dateisystem speichert. Die refreshAsync-Methode ist nur in Szenarien hilfreich, in denen andere Instanzen desselben Add-Ins die Einstellungen ändern können und diese Änderungen allen Instanzen zur Verfügung stehen sollten.

Eigenschaft Verwendung
AsyncResult.value Gibt immer undefined zurück, weil kein Objekt oder Daten zum Abruf existieren.
AsyncResult.status Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
AsyncResult.error Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
AsyncResult.asyncContext Ein benutzerdefiniertes Element beliebigen Typs, das im AsyncResult-Objekt ohne Änderung zurückgegeben wird.

Beispiele

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

set(name, value)

Legt die angegebene Einstellung fest oder erstellt sie.

Wichtig: Beachten Sie, dass sich die Settings.set-Methode nur auf die im Arbeitsspeicher gespeicherte Kopie des Einstellungseigenschafts-Bag auswirkt. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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

Parameter

name

string

value

any

Gibt den zu speichernden Wert an.

Gibt zurück

void

Hinweise

Anforderungssatz: Einstellungen

Die set-Methode erstellt eine neue Einstellung des angegebenen Namens, wenn sie noch nicht vorhanden ist, oder legt eine vorhandene Einstellung des angegebenen Namens in der Speicherkopie des Einstellungseigenschafts-Bags fest. Nach dem Aufrufen der Settings.saveAsync-Methode wird der Wert im Dokument als serialisierte JSON-Darstellung des Datentyps gespeichert.

Beispiele

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}