Skip to content

Commit cd48d0d

Browse files
AlexJerabekAlexJerabek
authored
[all hosts] (Common APIs) Refreshing Office.File sample (#2283)
* Refreshing Office.File sample * Add helper function comment * Put sample link on one line
1 parent d275691 commit cd48d0d

File tree

65 files changed

+452
-350
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+452
-350
lines changed

‎docs/code-snippets/office-snippets.yaml

Lines changed: 68 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -3958,51 +3958,80 @@ Office.EventType:enum:
39583958
});
39593959
});
39603960
}
3961-
Office.File#getSliceAsync:member(1):
3961+
Office.File:interface:
39623962
- |-
3963-
// This sample shows how to get all the slices of a file.
3964-
// The asynchronous operation returns a Promise so it can be awaited.
3965-
private getAllSlices(file: any): Promise<any> {
3966-
const self = this;
3967-
let isError = false;
3968-
3969-
return new Promise(async (resolve, reject) => {
3970-
let documentFileData = [];
3971-
for (let sliceIndex = 0; (sliceIndex < file.sliceCount) && !isError; sliceIndex++) {
3972-
const sliceReadPromise = new Promise((sliceResolve, sliceReject) => {
3973-
file.getSliceAsync(sliceIndex, (asyncResult) => {
3974-
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
3975-
documentFileData = documentFileData.concat(asyncResult.value.data);
3976-
sliceResolve({
3977-
IsSuccess: true,
3978-
Data: documentFileData
3979-
});
3980-
} else {
3981-
file.closeAsync();
3982-
sliceReject({
3983-
IsSuccess: false,
3984-
ErrorMessage: `Error in reading the slice: ${sliceIndex} of the document`
3985-
});
3986-
}
3987-
});
3988-
});
3989-
await sliceReadPromise.catch((error) => {
3990-
isError = true;
3991-
});
3992-
}
3963+
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
39933964
3994-
if (isError || !documentFileData.length) {
3995-
reject('Error while reading document. Please try it again.');
3996-
return;
3965+
function getCurrentFile() {
3966+
const sliceSize = 4096; /*Bytes*/
3967+
3968+
// This snippet specifies a small slice size to show how the getFileAsync() method uses slices.
3969+
Office.context.document.getFileAsync(Office.FileType.Compressed, { sliceSize: sliceSize }, function(result) {
3970+
if (result.status === Office.AsyncResultStatus.Failed) {
3971+
return onError(result.error);
39973972
}
39983973
3999-
file.closeAsync();
3974+
// result.value is the File object.
3975+
const file: Office.File = result.value
3976+
getFileContents(file, onSuccess, onError); /* getFileContents is defined in the Office.File.getSliceAsync example. */
3977+
});
3978+
3979+
function onError(error: Office.Error): void {
3980+
console.error(error);
3981+
}
40003982
4001-
resolve({
4002-
IsSuccess: true,
4003-
Data: documentFileData
3983+
function onSuccess(byteArray: number[]) {
3984+
let base64string = base64js.fromByteArray(byteArray);
3985+
// Do something with the file contents.
3986+
}
3987+
}
3988+
Office.File#getSliceAsync:member(1):
3989+
- |-
3990+
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
3991+
3992+
function getFileContents(
3993+
file: Office.File,
3994+
onSuccess: (byteArray: number[]) => void,
3995+
onError: (error: Office.Error) => void
3996+
) {
3997+
let expectedSliceCount = file.sliceCount;
3998+
let fileSlices: Array<Array<number>> = [];
3999+
4000+
console.log("Current file size in bytes: " + file.size);
4001+
console.log("Number of file slices: " + file.sliceCount);
4002+
4003+
getFileContentsHelper();
4004+
4005+
/**
4006+
* A helper function to retrieve all slices of the file recursively.
4007+
* It fetches one slice at a time and stores it in the `fileSlices` array.
4008+
* The recursion terminates when all slices have been retrieved.
4009+
*/
4010+
function getFileContentsHelper() {
4011+
file.getSliceAsync(fileSlices.length, function(result) {
4012+
if (result.status === Office.AsyncResultStatus.Failed) {
4013+
file.closeAsync();
4014+
return onError(result.error);
4015+
}
4016+
4017+
// Got one slice, store it in a temporary array.
4018+
fileSlices.push(result.value.data);
4019+
4020+
if (fileSlices.length == expectedSliceCount) {
4021+
console.log("All slices have been received.");
4022+
file.closeAsync();
4023+
4024+
let array = [];
4025+
fileSlices.forEach((slice) => {
4026+
array = array.concat(slice);
4027+
});
4028+
4029+
onSuccess(array); /* onSuccess is defined in the Office.File example. */
4030+
} else {
4031+
getFileContentsHelper();
4032+
}
40044033
});
4005-
});
4034+
}
40064035
}
40074036
Office.HostType:enum:
40084037
- |-

‎docs/docs-ref-autogen/office/office/office.file.yml

Lines changed: 81 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,42 @@ remarks: >-
88
Access the File object with the AsyncResult.value property in the callback
99
function passed to the Document.getFileAsync method.
1010
11+
12+
#### Examples
13+
14+
15+
```TypeScript
16+
17+
// Link to full sample:
18+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
19+
20+
21+
function getCurrentFile() {
22+
const sliceSize = 4096; /*Bytes*/
23+
24+
// This snippet specifies a small slice size to show how the getFileAsync() method uses slices.
25+
Office.context.document.getFileAsync(Office.FileType.Compressed, { sliceSize: sliceSize }, function(result) {
26+
if (result.status === Office.AsyncResultStatus.Failed) {
27+
return onError(result.error);
28+
}
29+
30+
// result.value is the File object.
31+
const file: Office.File = result.value
32+
getFileContents(file, onSuccess, onError); /* getFileContents is defined in the Office.File.getSliceAsync example. */
33+
});
34+
35+
function onError(error: Office.Error): void {
36+
console.error(error);
37+
}
38+
39+
function onSuccess(byteArray: number[]) {
40+
let base64string = base64js.fromByteArray(byteArray);
41+
// Do something with the file contents.
42+
}
43+
}
44+
45+
```
46+
1147
isPreview: false
1248
isDeprecated: false
1349
type: interface
@@ -117,51 +153,53 @@ methods:
117153
118154
```TypeScript
119155
120-
// This sample shows how to get all the slices of a file.
121-
122-
// The asynchronous operation returns a Promise so it can be awaited.
123-
124-
private getAllSlices(file: any): Promise<any> {
125-
const self = this;
126-
let isError = false;
127-
128-
return new Promise(async (resolve, reject) => {
129-
let documentFileData = [];
130-
for (let sliceIndex = 0; (sliceIndex < file.sliceCount) && !isError; sliceIndex++) {
131-
const sliceReadPromise = new Promise((sliceResolve, sliceReject) => {
132-
file.getSliceAsync(sliceIndex, (asyncResult) => {
133-
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
134-
documentFileData = documentFileData.concat(asyncResult.value.data);
135-
sliceResolve({
136-
IsSuccess: true,
137-
Data: documentFileData
138-
});
139-
} else {
140-
file.closeAsync();
141-
sliceReject({
142-
IsSuccess: false,
143-
ErrorMessage: `Error in reading the slice: ${sliceIndex} of the document`
144-
});
145-
}
156+
// Link to full sample:
157+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
158+
159+
160+
function getFileContents(
161+
file: Office.File,
162+
onSuccess: (byteArray: number[]) => void,
163+
onError: (error: Office.Error) => void
164+
) {
165+
let expectedSliceCount = file.sliceCount;
166+
let fileSlices: Array<Array<number>> = [];
167+
168+
console.log("Current file size in bytes: " + file.size);
169+
console.log("Number of file slices: " + file.sliceCount);
170+
171+
getFileContentsHelper();
172+
173+
/**
174+
* A helper function to retrieve all slices of the file recursively.
175+
* It fetches one slice at a time and stores it in the `fileSlices` array.
176+
* The recursion terminates when all slices have been retrieved.
177+
*/
178+
function getFileContentsHelper() {
179+
file.getSliceAsync(fileSlices.length, function(result) {
180+
if (result.status === Office.AsyncResultStatus.Failed) {
181+
file.closeAsync();
182+
return onError(result.error);
183+
}
184+
185+
// Got one slice, store it in a temporary array.
186+
fileSlices.push(result.value.data);
187+
188+
if (fileSlices.length == expectedSliceCount) {
189+
console.log("All slices have been received.");
190+
file.closeAsync();
191+
192+
let array = [];
193+
fileSlices.forEach((slice) => {
194+
array = array.concat(slice);
146195
});
147-
});
148-
await sliceReadPromise.catch((error) => {
149-
isError = true;
150-
});
151-
}
152-
153-
if (isError || !documentFileData.length) {
154-
reject('Error while reading document. Please try it again.');
155-
return;
156-
}
157-
158-
file.closeAsync();
159-
160-
resolve({
161-
IsSuccess: true,
162-
Data: documentFileData
196+
197+
onSuccess(array); /* onSuccess is defined in the Office.File example. */
198+
} else {
199+
getFileContentsHelper();
200+
}
163201
});
164-
});
202+
}
165203
}
166204
167205
```

‎docs/docs-ref-autogen/office_release/office/office.file.yml

Lines changed: 81 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,42 @@ remarks: >-
88
Access the File object with the AsyncResult.value property in the callback
99
function passed to the Document.getFileAsync method.
1010
11+
12+
#### Examples
13+
14+
15+
```TypeScript
16+
17+
// Link to full sample:
18+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
19+
20+
21+
function getCurrentFile() {
22+
const sliceSize = 4096; /*Bytes*/
23+
24+
// This snippet specifies a small slice size to show how the getFileAsync() method uses slices.
25+
Office.context.document.getFileAsync(Office.FileType.Compressed, { sliceSize: sliceSize }, function(result) {
26+
if (result.status === Office.AsyncResultStatus.Failed) {
27+
return onError(result.error);
28+
}
29+
30+
// result.value is the File object.
31+
const file: Office.File = result.value
32+
getFileContents(file, onSuccess, onError); /* getFileContents is defined in the Office.File.getSliceAsync example. */
33+
});
34+
35+
function onError(error: Office.Error): void {
36+
console.error(error);
37+
}
38+
39+
function onSuccess(byteArray: number[]) {
40+
let base64string = base64js.fromByteArray(byteArray);
41+
// Do something with the file contents.
42+
}
43+
}
44+
45+
```
46+
1147
isPreview: false
1248
isDeprecated: false
1349
type: interface
@@ -117,51 +153,53 @@ methods:
117153
118154
```TypeScript
119155
120-
// This sample shows how to get all the slices of a file.
121-
122-
// The asynchronous operation returns a Promise so it can be awaited.
123-
124-
private getAllSlices(file: any): Promise<any> {
125-
const self = this;
126-
let isError = false;
127-
128-
return new Promise(async (resolve, reject) => {
129-
let documentFileData = [];
130-
for (let sliceIndex = 0; (sliceIndex < file.sliceCount) && !isError; sliceIndex++) {
131-
const sliceReadPromise = new Promise((sliceResolve, sliceReject) => {
132-
file.getSliceAsync(sliceIndex, (asyncResult) => {
133-
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
134-
documentFileData = documentFileData.concat(asyncResult.value.data);
135-
sliceResolve({
136-
IsSuccess: true,
137-
Data: documentFileData
138-
});
139-
} else {
140-
file.closeAsync();
141-
sliceReject({
142-
IsSuccess: false,
143-
ErrorMessage: `Error in reading the slice: ${sliceIndex} of the document`
144-
});
145-
}
156+
// Link to full sample:
157+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/refs/heads/main/samples/excel/26-document/get-file-in-slices-async.yaml
158+
159+
160+
function getFileContents(
161+
file: Office.File,
162+
onSuccess: (byteArray: number[]) => void,
163+
onError: (error: Office.Error) => void
164+
) {
165+
let expectedSliceCount = file.sliceCount;
166+
let fileSlices: Array<Array<number>> = [];
167+
168+
console.log("Current file size in bytes: " + file.size);
169+
console.log("Number of file slices: " + file.sliceCount);
170+
171+
getFileContentsHelper();
172+
173+
/**
174+
* A helper function to retrieve all slices of the file recursively.
175+
* It fetches one slice at a time and stores it in the `fileSlices` array.
176+
* The recursion terminates when all slices have been retrieved.
177+
*/
178+
function getFileContentsHelper() {
179+
file.getSliceAsync(fileSlices.length, function(result) {
180+
if (result.status === Office.AsyncResultStatus.Failed) {
181+
file.closeAsync();
182+
return onError(result.error);
183+
}
184+
185+
// Got one slice, store it in a temporary array.
186+
fileSlices.push(result.value.data);
187+
188+
if (fileSlices.length == expectedSliceCount) {
189+
console.log("All slices have been received.");
190+
file.closeAsync();
191+
192+
let array = [];
193+
fileSlices.forEach((slice) => {
194+
array = array.concat(slice);
146195
});
147-
});
148-
await sliceReadPromise.catch((error) => {
149-
isError = true;
150-
});
151-
}
152-
153-
if (isError || !documentFileData.length) {
154-
reject('Error while reading document. Please try it again.');
155-
return;
156-
}
157-
158-
file.closeAsync();
159-
160-
resolve({
161-
IsSuccess: true,
162-
Data: documentFileData
196+
197+
onSuccess(array); /* onSuccess is defined in the Office.File example. */
198+
} else {
199+
getFileContentsHelper();
200+
}
163201
});
164-
});
202+
}
165203
}
166204
167205
```

0 commit comments

Comments
 (0)