Office.File interface

  • Reference
Package:
office

Represents the document file associated with an Office Add-in.

Remarks

Access the File object with the AsyncResult.value property in the callback function passed to the Document.getFileAsync method.

Properties

size

Gets the document file size in bytes.
sliceCount

Gets the number of slices into which the file is divided.

Methods

closeAsync(callback)

Closes the document file.
getSliceAsync(sliceIndex, callback)

Returns the specified slice.

Property Details

size

Gets the document file size in bytes.

size: number;

Property Value

number

sliceCount

Gets the number of slices into which the file is divided.

sliceCount: number;

Property Value

number

Method Details

closeAsync(callback)

Closes the document file.

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

Parameters

callback

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

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult.

Returns

void

Remarks

Requirement set: File

No more than two documents are allowed to be in memory; otherwise the Document.getFileAsync operation will fail. Use the File.closeAsync method to close the file when you are finished working with it.

In the callback function passed to the closeAsync method, you can use the properties of the AsyncResult object to return the following information.

Property Use
AsyncResult.value Always returns undefined because there's no object or data to retrieve.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext Define an item of any type that's returned in the AsyncResult object without being altered.

getSliceAsync(sliceIndex, callback)

Returns the specified slice.

getSliceAsync(sliceIndex: number, callback?: (result: AsyncResult<Office.Slice>) => void): void;

Parameters

sliceIndex

number

Specifies the zero-based index of the slice to be retrieved. Required.

callback

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

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult. The value property of the result is the Office.Slice object.

Returns

void

Remarks

Requirement set: File

In the callback function passed to the getSliceAsync method, you can use the properties of the AsyncResult object to return the following information.

Property Use
AsyncResult.value Access the Slice object.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext Define an item of any type that's returned in the AsyncResult object without being altered.

Examples

// This sample shows how to get all the slices of a file. 
// The asynchronous operation returns a Promise so it can be awaited.
private getAllSlices(file: any): Promise<any> {
    const self = this;
    let isError = false;

    return new Promise(async (resolve, reject) => {
        let documentFileData = [];
        for (let sliceIndex = 0; (sliceIndex < file.sliceCount) && !isError; sliceIndex++) {
            const sliceReadPromise = new Promise((sliceResolve, sliceReject) => {
                file.getSliceAsync(sliceIndex, (asyncResult) => {
                    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                        documentFileData = documentFileData.concat(asyncResult.value.data);
                        sliceResolve({
                            IsSuccess: true,
                            Data: documentFileData
                        });
                    } else {
                        file.closeAsync();
                        sliceReject({
                            IsSuccess: false,
                            ErrorMessage: `Error in reading the slice: ${sliceIndex} of the document`
                        });
                    }
                });
            });
            await sliceReadPromise.catch((error) => {
                isError = true;
            });
        }

        if (isError || !documentFileData.length) {
            reject('Error while reading document. Please try it again.');
            return;
        }

        file.closeAsync();

        resolve({
            IsSuccess: true,
            Data: documentFileData
        });
    });
}