Office.Settings interface

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 dem Add-In eine Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehr als ein Benutzer die Kalkulationstabelle bearbeitet (gemeinsam Dokumenterstellung). Daher wird das settingsChanged Ereignis effektiv nur in Excel im Web in Szenarien für die gemeinsame Dokumenterstellung unterstützt.

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

Parameter

Gibt zurück

Hinweise

Anforderungssatz: Nicht in einem Satz

Sie können mehrere Ereignishandler für das angegebene eventType Element hinzufügen, solange der Name der einzelnen Ereignishandlerfunktionen eindeutig ist.

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 dem Add-In eine Kalkulationstabelle geladen wird, die in Excel im Web geöffnet wird, und mehr als ein Benutzer die Kalkulationstabelle bearbeitet (gemeinsam Dokumenterstellung). Daher wird das settingsChanged Ereignis effektiv nur in Excel im Web in Szenarien für die gemeinsame Dokumenterstellung unterstützt.

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

Parameter

Gibt zurück

Hinweise

Anforderungssatz: Nicht in einem Satz

Sie können mehrere Ereignishandler für das angegebene eventType Element hinzufügen, solange der Name der einzelnen Ereignishandlerfunktionen eindeutig ist.

Beispiele

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

function MyHandler(eventArgs: Office.SettingsChangedEventArgs) {
    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;
}

Ruft die angegebene Einstellung ab.

get(name: string): any;

Parameter

Gibt zurück

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;
}

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

Gibt zurück

Hinweise

Anforderungssatz: Nicht in einem Satz

Diese Methode ist in Excel-, Word- und PowerPoint-Szenarien für die gemeinsame Dokumenterstellung nützlich, 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 durch den Benutzer geladen wurden, können die von jedem Benutzer verwendeten Einstellungswerte nicht synchronisiert werden. Dies kann immer dann geschehen, wenn eine Instance des Add-Ins die Settings.saveAsync Methode aufruft, um alle Einstellungen dieses Benutzers für das Dokument zu speichern. Wenn Sie die refreshAsync Methode über den Ereignishandler für das settingsChanged Ereignis des Add-Ins aufrufen, werden die Einstellungswerte für alle Benutzer aktualisiert.

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

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;
}

Entfernt die angegebene Einstellung.

Wichtig: Beachten Sie, dass sich die Settings.remove Methode nur auf die In-Memory-Kopie des Eigenschaftenbags "Einstellungen" auswirkt. Um das Entfernen der angegebenen Einstellung im Dokument beizubehalten, müssen Sie irgendwann nach dem Aufruf der Settings.remove Methode und vor dem Schließen des Add-Ins die Settings.saveAsync Methode aufrufen.

remove(name: string): void;

Parameter

Gibt zurück

Hinweise

Anforderungssatz: Einstellungen

null ist ein gültiger Wert für eine Einstellung. Daher wird sie durch das Zuweisen null der Einstellung nicht aus dem Eigenschaftenbereich "Einstellungen" entfernt.

Beispiele

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

Entfernt einen Ereignishandler für das settingsChanged Ereignis.

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

Parameter

Gibt zurück

Hinweise

Anforderungssatz: Nicht in einem Satz

Wenn der optionale Handlerparameter beim Aufrufen der removeHandlerAsync Methode weggelassen wird, werden alle Ereignishandler für die angegebene eventType Methode entfernt.

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

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

Entfernt einen Ereignishandler für das settingsChanged Ereignis.

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

Parameter

Gibt zurück

Hinweise

Anforderungssatz: Nicht in einem Satz

Wenn der optionale Handlerparameter beim Aufrufen der removeHandlerAsync Methode weggelassen wird, werden alle Ereignishandler für die angegebene eventType Methode entfernt.

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

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

Beispiele

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

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

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

Parameter

Gibt zurück

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

Hinweis: Die saveAsync Methode überträgt den Eigenschaftsbeutel für die In-Memory-Einstellungen in die Dokumentdatei. Ä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 für die gemeinsame Dokumenterstellung nützlich, in denen andere Instanzen desselben Add-Ins die Einstellungen ändern können, und diese Änderungen sollten für alle Instanzen verfügbar gemacht werden.

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

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

Parameter

Gibt zurück

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

Hinweis: Die saveAsync Methode überträgt den Eigenschaftsbeutel für die In-Memory-Einstellungen in die Dokumentdatei. Ä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 für die gemeinsame Dokumenterstellung nützlich, in denen andere Instanzen desselben Add-Ins die Einstellungen ändern können, und diese Änderungen sollten für alle Instanzen verfügbar gemacht 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;
}

Legt die angegebene Einstellung fest oder erstellt sie.

Wichtig: Beachten Sie, dass sich die Settings.set Methode nur auf die In-Memory-Kopie des Eigenschaftenbags "Einstellungen" auswirkt. Um sicherzustellen, dass Ergänzungen oder Änderungen an Einstellungen für Ihr Add-In verfügbar sind, wenn das Dokument das nächste Mal geöffnet wird, müssen Sie irgendwann nach dem Aufruf der Settings.set Methode und vor dem Schließen des Add-Ins die Settings.saveAsync Methode aufrufen, um Einstellungen im Dokument zu erhalten.

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

Parameter

Gibt zurück

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 In-Memory-Kopie des Einstellungseigenschaftenbags fest. Nachdem Sie die Settings.saveAsync Methode aufgerufen haben, wird der Wert im Dokument als serialisierte JSON-Darstellung seines Datentyps gespeichert.

Beispiele

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