Office.File interface

表示与 Office 外接程序关联的文档文件。

注解

使用传递给 Document.getFileAsync 方法的回调函数中的 AsyncResult.value 属性访问 File 对象。

使用方

示例

// 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.
    }
}

属性

size

获取以字节为单位的文档文件大小。

sliceCount

获取文件分为的切片数。

方法

closeAsync(callback)

关闭文档文件。

getSliceAsync(sliceIndex, callback)

返回指定的切片。

属性详细信息

size

获取以字节为单位的文档文件大小。

size: number;

属性值

number

sliceCount

获取文件分为的切片数。

sliceCount: number;

属性值

number

方法详细信息

closeAsync(callback)

关闭文档文件。

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

参数

callback

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

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult。

返回

void

注解

要求集: 文件

内存中不允许两个以上的文档;否则 Document.getFileAsync 操作将会失败。 处理完文件后,使用 File.closeAsync 方法关闭文件。

在传递给 closeAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用途
AsyncResult.value 始终返回 undefined ,因为没有要检索的对象或数据。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 定义在 AsyncResult 对象中返回且不进行更改的任何类型的项。

getSliceAsync(sliceIndex, callback)

返回指定的切片。

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

参数

sliceIndex

number

Specifies the zero-based index of the slice to be retrieved. 必填。

callback

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

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult。 value结果的属性是 Office.Slice 对象。

返回

void

注解

要求集: 文件

在传递给 getSliceAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用途
AsyncResult.value 访问 Slice 对象。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 定义在 AsyncResult 对象中返回且不进行更改的任何类型的项。

示例

// 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();
            }
        });
    }
}