Edit

Share via

Office.File interface

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.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/get-file-in-slices-async.yaml

function getCurrentFile() {
    const sliceSize = 4096; /*Bytes*/

    // This snippet specifies a small slice size to show how the getFileAsync() method uses slices.
    Office.context.document.getFileAsync(Office.FileType.Compressed, { sliceSize: sliceSize }, function(result) {
        if (result.status === Office.AsyncResultStatus.Failed) {
            return onError(result.error);
        }

        // result.value is the File object.
        const file: Office.File = result.value
        getFileContents(file, onSuccess, onError); /* getFileContents is defined in the Office.File.getSliceAsync example. */
    });

    function onError(error: Office.Error): void {
        console.error(error);
    }

    function onSuccess(byteArray: number[]) {
        let base64string = base64js.fromByteArray(byteArray);
        // Do something with the file contents.
    }
}

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

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/get-file-in-slices-async.yaml

function getFileContents(
    file: Office.File,
    onSuccess: (byteArray: number[]) => void,
    onError: (error: Office.Error) => void
) {
    let expectedSliceCount = file.sliceCount;
    let fileSlices: Array<Array<number>> = [];

    console.log("Current file size in bytes: " + file.size);
    console.log("Number of file slices: " + file.sliceCount);

    getFileContentsHelper();

    /**
     * A helper function to retrieve all slices of the file recursively.
     * It fetches one slice at a time and stores it in the `fileSlices` array.
     * The recursion terminates when all slices have been retrieved.
     */
    function getFileContentsHelper() {
        file.getSliceAsync(fileSlices.length, function(result) {
            if (result.status === Office.AsyncResultStatus.Failed) {
                file.closeAsync();
                return onError(result.error);
            }

            // Got one slice, store it in a temporary array.
            fileSlices.push(result.value.data);

            if (fileSlices.length == expectedSliceCount) {
                console.log("All slices have been received.");
                file.closeAsync();

                let array = [];
                fileSlices.forEach((slice) => {
                    array = array.concat(slice);
                });

                onSuccess(array); /* onSuccess is defined in the Office.File example. */
            } else {
                getFileContentsHelper();
            }
        });
    }
}