Office.Settings interface

Paket:

office

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

Hinweise

Anwendungen: 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 der Wert eine Zeichenfolge, eine Zahl, einen booleschen Wert, null, ein Objekt oder ein Array sein kann.

Das Settings-Objekt wird automatisch als Teil des Document-Objekts geladen und ist verfügbar, indem die settings-Eigenschaft dieses Objekts aufgerufen wird, 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 Tabelle bearbeiten (gemeinsame Dokumenterstellung). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Szenarien mit der gemeinsamen Dokumenterstellung 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 Tabelle bearbeiten (gemeinsame Dokumenterstellung). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Szenarien mit der gemeinsamen Dokumenterstellung 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 Speicherkopie des Eigenschaftenbehälters für Einstellungen 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 Speicherkopie des Eigenschaftenbehälters für Einstellungen 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 Tabelle bearbeiten (gemeinsame Dokumenterstellung). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Szenarien mit der gemeinsamen Dokumenterstellung 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 vom Typ Office.SettingsChangedEventArgs ist. Erforderlich.

options

Office.AsyncContextOptions

Bietet eine Option zum Beibehalten von Kontextdaten eines beliebigen Typs , unverändert, für die Verwendung in einem Rückruf.

callback

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

Optional. Eine Funktion, die aufgerufen wird, wenn der Rückruf zurückgibt, deren einziger Parameter vom Typ Office.AsyncResult ist.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da beim Hinzufügen eines Ereignishandlers keine Daten oder Objekte abgerufen werden müssen.
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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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 Tabelle bearbeiten (gemeinsame Dokumenterstellung). Daher wird das settingsChanged-Ereignis nur in Excel im Web in Szenarien mit der gemeinsamen Dokumenterstellung 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 vom Typ Office.SettingsChangedEventArgs ist. Erforderlich.

callback

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

Optional. Eine Funktion, die aufgerufen wird, wenn der Rückruf zurückgibt, deren einziger Parameter vom Typ Office.AsyncResult ist.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da beim Hinzufügen eines Ereignishandlers keine Daten oder Objekte abgerufen werden müssen.
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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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, dessen Eigenschaftsnamen serialisierten JSON-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 aufgerufen wird, wenn der Rückruf zurückgibt, 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 Szenarien mit der gemeinsamen Dokumenterstellung in Excel, Word und PowerPoint nützlich, wenn mehrere Instanzen desselben Add-Ins für dasselbe Dokument arbeiten. Da jedes Add-In mit einer Speicherkopie der Einstellungen arbeitet, die zum Zeitpunkt des Öffnens durch den Benutzer aus dem Dokument geladen wurden, können die von jedem Benutzer verwendeten Einstellungswerte nicht mehr synchron sein. Dies kann immer dann der Fall sein, wenn ein instance des Add-Ins die Settings.saveAsync-Methode aufruft, um alle Einstellungen dieses Benutzers im Dokument beizubehalten. 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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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 Speicherkopie des Eigenschaftenbehälters für Einstellungen 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 bereit, um zu bestimmen, welche Ereignishandler oder Handler entfernt werden.

callback

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

Optional. Eine Funktion, die aufgerufen wird, wenn der Rückruf zurückgibt, 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.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da beim Festlegen von Formaten keine Daten oder Objekte zum Abrufen vorhanden sind.
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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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 aufgerufen wird, wenn der Rückruf zurückgibt, 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.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da beim Festlegen von Formaten keine Daten oder Objekte zum Abrufen vorhanden sind.
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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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

callback

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

Optional. Eine Funktion, die aufgerufen wird, wenn der Rückruf zurückgibt, 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 speichert den Eigenschaftenbehälter für In-Memory-Einstellungen in der Dokumentdatei. Die Änderungen an der Dokumentdatei selbst werden jedoch nur gespeichert, wenn der Benutzer (oder die AutoWiederherstellen-Einstellung) das Dokument im Dateisystem speichert. Die refreshAsync-Methode ist nur in Szenarien mit der gemeinsamen Dokumenterstellung nützlich, wenn andere Instanzen desselben Add-Ins möglicherweise die Einstellungen ändern und diese Änderungen für alle Instanzen verfügbar gemacht werden sollten.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da kein Objekt oder keine Daten 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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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 aufgerufen wird, wenn der Rückruf zurückgibt, 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 speichert den Eigenschaftenbehälter für In-Memory-Einstellungen in der Dokumentdatei. Die Änderungen an der Dokumentdatei selbst werden jedoch nur gespeichert, wenn der Benutzer (oder die AutoWiederherstellen-Einstellung) das Dokument im Dateisystem speichert. Die refreshAsync-Methode ist nur in Szenarien mit der gemeinsamen Dokumenterstellung nützlich, wenn andere Instanzen desselben Add-Ins möglicherweise die Einstellungen ändern und diese Änderungen für alle Instanzen verfügbar gemacht werden sollten.

Eigenschaft	Verwendung
AsyncResult.value	Gibt immer zurück undefined , da kein Objekt oder keine Daten 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	Definieren Sie ein Element eines beliebigen Typs, der im AsyncResult-Objekt zurückgegeben wird, ohne geändert zu werden.

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 Speicherkopie des Eigenschaftenbehälters für Einstellungen 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, sofern sie noch nicht vorhanden ist, oder legt eine vorhandene Einstellung des angegebenen Namens in der Speicherkopie des Eigenschaftenbehälters für Einstellungen 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');
}