Office.BeforeDocumentCloseNotification interface

  • Reference
Package:
office

Represents a modal notification dialog that can appear when the user attempts to close a document. The document won't close until the user responds. The notification dialog will allow the user to confirm the request to close the document or cancel the request to close the document. This API is only supported in Excel.

Remarks

Requirement set: SharedRuntime 1.2

Examples

// Enable the before document close modal notification dialog. 
async function enableNotification() {
    await Office.addin.beforeDocumentCloseNotification.enable(); 
}

// Add an event handler to detect when the document close operation is cancelled.
Office.addin.beforeDocumentCloseNotification.onCloseActionCancelled(async function () {
    // When the document close attempt is cancelled, write a message to the active range in the worksheet.
    await Excel.run(async (context) => {
        const range = context.workbook.getSelectedRange();
        range.values = [["Detected onCloseActionCancelled event."]];
        await context.sync();
    });
});

Methods

disable()

Prevents the notification dialog from appearing when the user attempts to close a document. The BeforeDocumentCloseNotification API is only supported in Excel.
enable()

Enable a modal notification dialog that appears when the user attempts to close a document. The document won't close until the user responds. This notification dialog asks the user to confirm the request to close the document, or allows the user to cancel the request to close the document. The BeforeDocumentCloseNotification API is only supported in Excel.
onCloseActionCancelled(handler)

Adds an event handler that detects when the BeforeDocumentCloseNotification close operation is cancelled. This event handler will be triggered if both of the following conditions are met.

  1. The add-in calls the enable method on the BeforeDocumentCloseNotification object.

  2. When the notification dialog is open, the end user clicks the Don't close button within the dialog, clicks the Close button in the upper right corner of the dialog, or presses the Esc key.

The BeforeDocumentCloseNotification API is only supported in Excel.

Method Details

disable()

Prevents the notification dialog from appearing when the user attempts to close a document. The BeforeDocumentCloseNotification API is only supported in Excel.

disable(): Promise<void>;

Returns

Promise<void>

Remarks

Requirement set: SharedRuntime 1.2

enable()

Enable a modal notification dialog that appears when the user attempts to close a document. The document won't close until the user responds. This notification dialog asks the user to confirm the request to close the document, or allows the user to cancel the request to close the document. The BeforeDocumentCloseNotification API is only supported in Excel.

enable(): Promise<void>;

Returns

Promise<void>

Remarks

Requirement set: SharedRuntime 1.2

onCloseActionCancelled(handler)

Adds an event handler that detects when the BeforeDocumentCloseNotification close operation is cancelled. This event handler will be triggered if both of the following conditions are met.

  1. The add-in calls the enable method on the BeforeDocumentCloseNotification object.

  2. When the notification dialog is open, the end user clicks the Don't close button within the dialog, clicks the Close button in the upper right corner of the dialog, or presses the Esc key.

The BeforeDocumentCloseNotification API is only supported in Excel.

onCloseActionCancelled(
            handler: () => void
        ): Promise<() => Promise<void>>;

Parameters

handler

() => void

The event handler that is called when the dialog is cancelled.

Returns

Promise<() => Promise<void>>

A promise that resolves when the event handler is added.

Remarks

Requirement set: SharedRuntime 1.2