From 8e96c7b4455a9c1ac5a16ae1b20ef9d24deef7b6 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Wed, 30 Jan 2019 13:51:17 -0800 Subject: [PATCH 1/2] Adding descriptions to async overloads --- types/office-js-preview/index.d.ts | 1844 +++++++++++++++++++++++++++- types/office-js/index.d.ts | 1844 +++++++++++++++++++++++++++- 2 files changed, 3658 insertions(+), 30 deletions(-) diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index 75e9ed910f..34ab184434 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -1093,6 +1093,104 @@ declare namespace Office { * @param callback - Optional. Accepts a callback method to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object. */ displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult) => void): void; + /** + * Displays a dialog to show or collect information from the user or to facilitate Web navigation. + * + * @remarks + * + * + *
HostsWord, Excel, Outlook, PowerPoint
Requirement setsDialogApi, Mailbox 1.4
+ * + * This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 + * for Outlook. For more on how to specify a requirement set in your manifest, see + * {@link https://docs.microsoft.com/office/dev/add-ins/develop/specify-office-hosts-and-api-requirements | Specify Office hosts and API requirements}. + * + * The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial page loads, you can go to + * other domains. + * + * Any page calling `office.context.ui.messageParent` must also be on the same domain as the parent page. + * + * **Design considerations**: + * + * The following design considerations apply to dialog boxes: + * + * - An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the same time from Add-in + * Commands (custom ribbon buttons or menu items). + * + * - Every dialog box can be moved and resized by the user. + * + * - Every dialog box is centered on the screen when opened. + * + * - Dialog boxes appear on top of the host application and in the order in which they were created. + * + * Use a dialog box to: + * + * - Display authentication pages to collect user credentials. + * + * - Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command. + * + * - Temporarily increase the surface area that a user has available to complete a task. + * + * Do not use a dialog box to interact with a document. Use a task pane instead. + * + * For a design pattern that you can use to create a dialog box, see + * {@link https://github.com/OfficeDev/Office-Add-in-UX-Design-Patterns/blob/master/Patterns/Client_Dialog.md | Client Dialog} in the Office + * Add-in UX Design Patterns repository on GitHub. + * + * **displayDialogAsync Errors**: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Code numberMeaning
12004The domain of the URL passed to displayDialogAsync is not trusted. The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the section of the add-in manifest.
12005The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
12007A dialog box is already opened from the task pane. A task pane add-in can only have one dialog box open at a time.
12009The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.
+ * + * In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the + * following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to
AsyncResult.valueAccess the Dialog object.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextAccess your user-defined object or value, if you passed one as the asyncContext parameter.
+ * + * @param startAddress - Accepts the initial HTTPS URL that opens in the dialog. + * @param callback - Optional. Accepts a callback method to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object. + */ displayDialogAsync(startAddress: string, callback?: (result: AsyncResult) => void): void; /** * Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent. @@ -2291,6 +2389,17 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: Office.AsyncResult) => void): void; + /** + * Adds an event handler to the object for the specified {@link Office.EventType}. Supported EventTypes are + * `Office.EventType.BindingDataChanged` and `Office.EventType.BindingSelectionChanged`. + * + * @remarks + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType The event type. For bindings, it can be `Office.EventType.BindingDataChanged` or `Office.EventType.BindingSelectionChanged`. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.BindingDataChangedEventArgs} or {@link Office.BindingSelectionChangedEventArgs}. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: Office.AsyncResult) => void): void; /** * Returns the data contained within the binding. @@ -2307,6 +2416,19 @@ declare namespace Office { * If the `coercionType` parameter is specified (and the call is successful), the data is returned in the format described in the CoercionType enumeration topic. */ getDataAsync(options?: GetBindingDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns the data contained within the binding. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * When called from a MatrixBinding or TableBinding, the getDataAsync method will return a subset of the bound values if the optional startRow, + * startColumn, rowCount, and columnCount parameters are specified (and they specify a contiguous and valid range). + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the values in the specified binding. + * If the `coercionType` parameter is specified (and the call is successful), the data is returned in the format described in the CoercionType enumeration topic. + */ getDataAsync(callback?: (result: AsyncResult) => void): void; /** * Removes the specified handler from the binding for the specified event type. @@ -2319,6 +2441,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes the specified handler from the binding for the specified event type. + * + * @remarks + *
Requirement SetsBindingEvents
+ * + * @param eventType The event type. For bindings, it can be `Office.EventType.BindingDataChanged` or `Office.EventType.BindingSelectionChanged`. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Writes data to the bound section of the document represented by the specified binding object. @@ -2451,6 +2582,134 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setDataAsync(data: TableData | any, options?: SetBindingDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Writes data to the bound section of the document represented by the specified binding object. + * + * @remarks + * + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * The value passed for data contains the data to be written in the binding. The kind of value passed determines what will be written as + * described in the following table. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringPlain text or anything that can be coerced to a string will be written.
An array of arrays ("matrix")Tabular data without headers will be written. For example, to write data to three rows in two columns, you can pass an array like this: `[["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]`. To write a single column of three rows, pass an array like this: `[["R1C1"], ["R2C1"], ["R3C1"]]`.
An {@link Office.TableData} objectA table with headers will be written.
+ * + * Additionally, these application-specific actions apply when writing data to a binding. For Word, the specified data is written to the + * binding as follows: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringThe specified text is written.
An array of arrays ("matrix") or an {@link Office.TableData} objectA Word table is written.
HTMLThe specified HTML is written. If any of the HTML you write is invalid, Word will not raise an error. Word will write as much of the HTML as it can and will omit any invalid data.
Office Open XML ("Open XML")The specified the XML is written.
+ * + * For Excel, the specified data is written to the binding as follows: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringThe specified text is inserted as the value of the first bound cell.You can also specify a valid formula to add that formula to the bound cell. For example, setting data to `"=SUM(A1:A5)"` will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result).
An array of arrays ("matrix"), and the shape exactly matches the shape of the binding specifiedThe set of rows and columns are written.You can also specify an array of arrays that contain valid formulas to add them to the bound cells. For example, setting data to `[["=SUM(A1:A5)","=AVERAGE(A1:A5)"]]` will add those two formulas to a binding that contains two cells. Just as when setting a formula on a single bound cell, you can't read the added formulas (or any pre-existing formulas) from the binding with the `Binding.getDataAsync` method - it returns only the data displayed in the bound cells.
An {@link Office.TableData} object, and the shape of the table matches the bound table.The specified set of rows and/or headers are written, if no other data in surrounding cells will be overwritten. Note: If you specify formulas in the TableData object you pass for the *data* parameter, you might not get the results you expect due to the "calculated columns" feature of Excel, which automatically duplicates formulas within a column. To work around this when you want to write *data* that contains formulas to a bound table, try specifying the data as an array of arrays (instead of a TableData object), and specify the *coercionType* as Microsoft.Office.Matrix or "matrix".
+ * + * For Excel Online: + * + * - The total number of cells in the value passed to the data parameter can't exceed 20,000 in a single call to this method. + * + * - The number of formatting groups passed to the cellFormat parameter can't exceed 100. + * A single formatting group consists of a set of formatting applied to a specified range of cells. + * + * In all other cases, an error is returned. + * + * The setDataAsync method will write data in a subset of a table or matrix binding if the optional startRow and startColumn parameters are + * specified, and they specify a valid range. + * + * In the callback function passed to the setDataAsync method, you can use the properties of the AsyncResult object to return the following + * information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * @param data The data to be set in the current selection. Possible data types by host: + * + * string: Excel, Excel Online, Word, and Word Online only + * + * array of arrays: Excel and Word only + * + * {@link Office.TableData}: Access, Excel, and Word only + * + * HTML: Word and Word Online only + * + * Office Open XML: Word only + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setDataAsync(data: TableData | any, callback?: (result: AsyncResult) => void): void; } @@ -2601,6 +2860,50 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the specified named item. */ addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult) => void): void; + /** + * Creates a binding against a named object in the document. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * For Excel, the itemName parameter can refer to a named range or a table. + * + * By default, adding a table in Excel assigns the name "Table1" for the first table you add, "Table2" for the second table you add, and so on. + * To assign a meaningful name for a table in the Excel UI, use the Table Name property on the Table Tools | Design tab of the ribbon. + * + * Note: In Excel, when specifying a table as a named item, you must fully qualify the name to include the worksheet name in the name of + * the table in this format: "Sheet1!Table1" + * + * For Word, the itemName parameter refers to the Title property of a Rich Text content control. (You can't bind to content controls other + * than the Rich Text content control). + * + * By default, a content control has no Title value assigned. To assign a meaningful name in the Word UI, after inserting a Rich Text content + * control from the Controls group on the Developer tab of the ribbon, use the Properties command in the Controls group to display the Content + * Control Properties dialog box. Then set the Title property of the content control to the name you want to reference from your code. + * + * Note: In Word, if there are multiple Rich Text content controls with the same Title property value (name), and you try to bind to one + * these content controls with this method (by specifying its name as the itemName parameter), the operation will fail. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * @param itemName Name of the bindable object in the document. For Example 'MyExpenses' table in Excel." + * @param bindingType The {@link Office.BindingType} for the data. The method returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the specified named item. + */ addFromNamedItemAsync(itemName: string, bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Create a binding by prompting the user to make a selection on the document. @@ -2633,6 +2936,35 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the selection specified by the user. */ addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult) => void): void; + /** + * Create a binding by prompting the user to make a selection on the document. + * + * @remarks + *
Requirement SetsNot in a set
+ * + * Adds a binding object of the specified type to the Bindings collection, which will be identified with the supplied id. + * The method fails if the specified selection cannot be bound. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
+ * + * @param bindingType Specifies the type of the binding object to create. Required. + * Returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the selection specified by the user. + */ addFromPromptAsync(bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Create a binding based on the user's current selection. @@ -2670,6 +3002,40 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the selection specified by the user. */ addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult) => void): void; + /** + * Create a binding based on the user's current selection. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * Adds the specified type of binding object to the Bindings collection, which will be identified with the supplied id. + * + * Note In Excel, if you call the addFromSelectionAsync method passing in the Binding.id of an existing binding, the Binding.type of that + * binding is used, and its type cannot be changed by specifying a different value for the bindingType parameter. + * If you need to use an existing id and change the bindingType, call the Bindings.releaseByIdAsync method first to release the binding, and + * then call the addFromSelectionAsync method to reestablish the binding with a new type. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param bindingType Specifies the type of the binding object to create. Required. + * Returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the selection specified by the user. + */ addFromSelectionAsync(bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Gets all bindings that were previously created. @@ -2698,6 +3064,31 @@ declare namespace Office { * The `value` property of the result is an array that contains each binding created for the referenced Bindings object. */ getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets all bindings that were previously created. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array that contains each binding created for the referenced Bindings object. + */ getAllAsync(callback?: (result: AsyncResult) => void): void; /** * Retrieves a binding based on its Name @@ -2727,8 +3118,36 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the Binding object specified by the id in the call. - */ + */ getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Retrieves a binding based on its Name + * + * @remarks + *
Requirement SetsCustomXmlParts, MatrixBindings, TableBindings, TextBindings
+ * + * Fails if the specified id does not exist. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param id Specifies the unique name of the binding object. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object specified by the id in the call. + */ getByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; /** * Removes the binding from the document @@ -2759,6 +3178,33 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ releaseByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes the binding from the document + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * Fails if the specified id does not exist. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param id Specifies the unique name to be used to identify the binding object. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ releaseByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; } /** @@ -2815,6 +3261,16 @@ declare namespace Office { * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the `xPath` parameter. */ getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the nodes associated with the XPath expression. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param xPath The XPath expression that specifies the nodes to get. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the `xPath` parameter. + */ getNodesAsync(xPath: string, callback?: (result: AsyncResult) => void): void; /** * Gets the node value. @@ -2827,6 +3283,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the value of the referenced node. */ getNodeValueAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the node value. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the value of the referenced node. + */ getNodeValueAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the text of an XML node in a custom XML part. @@ -2839,6 +3304,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the inner text of the referenced nodes. */ getTextAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the text of an XML node in a custom XML part. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the inner text of the referenced nodes. + */ getTextAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the node's XML. @@ -2851,6 +3325,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the XML of the referenced node. */ getXmlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the node's XML. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the XML of the referenced node. + */ getXmlAsync(callback?: (result: AsyncResult) => void): void; /** * Sets the node value. @@ -2863,6 +3346,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setNodeValueAsync(value: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the node value. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param value The value to be set on the node + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setNodeValueAsync(value: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously sets the text of an XML node in a custom XML part. @@ -2877,6 +3369,17 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setTextAsync(text: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously sets the text of an XML node in a custom XML part. + * + * @remarks + * + * + *
HostsWord
Requirement SetsCustomXmlParts
+ * + * @param text Required. The text value of the XML node. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setTextAsync(text: string, callback?: (result: AsyncResult) => void): void; /** * Sets the node XML. @@ -2889,6 +3392,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setXmlAsync(xml: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the node XML. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param xml The XML to be set on the node + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setXmlAsync(xml: string, callback?: (result: AsyncResult) => void): void; } /** @@ -2924,7 +3436,6 @@ declare namespace Office { * Gets the set of namespace prefix mappings ({@link Office.CustomXmlPrefixMappings}) used against the current CustomXmlPart. */ namespaceManager: CustomXmlPrefixMappings; - /** * Adds an event handler to the object using the specified event type. * @@ -2940,45 +3451,68 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler to the object using the specified event type. + * + * @remarks + * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType Specifies the type of event to add. For a CustomXmlPart object, the eventType parameter can be specified as + * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.NodeDeletedEventArgs}, + * {@link Office.NodeInsertedEventArgs}, or {@link Office.NodeReplacedEventArgs} + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, callback?: (result: AsyncResult) => void): void; /** * Deletes the Custom XML Part. * - * @remarks - * * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ deleteAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Deletes the Custom XML Part. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ deleteAsync(callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath. * - * @remarks - * * @param xPath An XPath expression that specifies the nodes you want returned. Required. * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the xPath parameter. - */ + */ getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath. + * + * @param xPath An XPath expression that specifies the nodes you want returned. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the xPath parameter. + */ getNodesAsync(xPath: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the XML inside this custom XML part. * - * @remarks - * * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string that contains the XML of the referenced CustomXmlPart object. - */ + */ getXmlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the XML inside this custom XML part. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the XML of the referenced CustomXmlPart object. + */ getXmlAsync(callback?: (result: AsyncResult) => void): void; /** * Removes an event handler for the specified event type. * - * @remarks - * * @param eventType Specifies the type of event to remove. For a CustomXmlPart object, the eventType parameter can be specified as * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. * @param handler The name of the handler to remove. @@ -2986,6 +3520,14 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the specified event type. + * + * @param eventType Specifies the type of event to remove. For a CustomXmlPart object, the eventType parameter can be specified as + * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. + * @param handler The name of the handler to remove. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, callback?: (result: AsyncResult) => void): void; } @@ -3126,6 +3668,13 @@ declare namespace Office { * The `value` property of the result is the newly created CustomXmlPart object. */ addAsync(xml: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously adds a new custom XML part to a file. + * + * @param xml The XML to add to the newly created custom XML part. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the newly created CustomXmlPart object. + */ addAsync(xml: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the specified custom XML part by its id. @@ -3137,6 +3686,14 @@ declare namespace Office { * If there is no custom XML part with the specified id, the method returns null. */ getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the specified custom XML part by its id. + * + * @param id The GUID of the custom XML part, including opening and closing braces. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a CustomXmlPart object that represents the specified custom XML part. + * If there is no custom XML part with the specified id, the method returns null. + */ getByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the specified custom XML part(s) by its namespace. @@ -3147,6 +3704,13 @@ declare namespace Office { * The `value` property of the result is an array of CustomXmlPart objects that match the specified namespace. */ getByNamespaceAsync(ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the specified custom XML part(s) by its namespace. + * + * @param ns The namespace URI. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlPart objects that match the specified namespace. + */ getByNamespaceAsync(ns: string, callback?: (result: AsyncResult) => void): void; } /** @@ -3183,6 +3747,16 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addNamespaceAsync(prefix: string, ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously adds a prefix to namespace mapping to use when querying an item. + * + * @remarks + * If no namespace is assigned to the requested prefix, the method returns an empty string (""). + * + * @param prefix Specifies the prefix to add to the prefix mapping list. Required. + * @param ns Specifies the namespace URI to assign to the newly added prefix. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addNamespaceAsync(prefix: string, ns: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the namespace mapped to the specified prefix. @@ -3198,6 +3772,18 @@ declare namespace Office { * The `value` property of the result is a string that contains the namespace mapped to the specified prefix. */ getNamespaceAsync(prefix: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the namespace mapped to the specified prefix. + * + * @remarks + * + * If the prefix already exists in the namespace manager, this method will overwrite the mapping of that prefix except when the prefix is one + * added or used by the data store internally, in which case it will return an error. + * + * @param prefix TSpecifies the prefix to get the namespace for. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the namespace mapped to the specified prefix. + */ getNamespaceAsync(prefix: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the prefix for the specified namespace. @@ -3211,8 +3797,20 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string that contains the prefix of the specified namespace. - */ + */ getPrefixAsync(ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the prefix for the specified namespace. + * + * @remarks + * + * If no prefix is assigned to the requested namespace, the method returns an empty string (""). If there are multiple prefixes specified in + * the namespace manager, the method returns the first prefix that matches the supplied namespace. + * + * @param ns Specifies the namespace to get the prefix for. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the prefix of the specified namespace. + */ getPrefixAsync(ns: string, callback?: (result: AsyncResult) => void): void; } /** @@ -3369,6 +3967,37 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler for a Document object event. + * + * @remarks + *
Requirement SetsDocumentEvents
+ * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
OneNote Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param eventType For a Document object event, the eventType parameter can be specified as `Office.EventType.Document.SelectionChanged` or + * `Office.EventType.Document.ActiveViewChanged`, or the corresponding text value of this enumeration. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.DocumentSelectionChangedEventArgs}. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult) => void): void; /** * Returns the state of the current view of the presentation (edit or read). @@ -3397,8 +4026,35 @@ declare namespace Office { * The `value` property of the result is the state of the presentation's current view. * The value returned can be either "edit" or "read". "edit" corresponds to any of the views in which you can edit slides, * such as Normal or Outline View. "read" corresponds to either Slide Show or Reading View. - */ + */ getActiveViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<"edit" | "read">) => void): void; + /** + * Returns the state of the current view of the presentation (edit or read). + * + * @remarks + *
Requirement SetsActiveView
+ * + * Can trigger an event when the view changes. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
PowerPoint Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the state of the presentation's current view. + * The value returned can be either "edit" or "read". "edit" corresponds to any of the views in which you can edit slides, + * such as Normal or Outline View. "read" corresponds to either Slide Show or Reading View. + */ getActiveViewAsync(callback?: (result: AsyncResult<"edit" | "read">) => void): void; /** * Returns the entire document file in slices of up to 4194304 bytes (4 MB). For add-ins for iOS, file slice is supported up to 65536 (64 KB). @@ -3444,6 +4100,48 @@ declare namespace Office { * The `value` property of the result is the File object. */ getFileAsync(fileType: FileType, options?: GetFileOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns the entire document file in slices of up to 4194304 bytes (4 MB). For add-ins for iOS, file slice is supported up to 65536 (64 KB). + * Note that specifying file slice size of above permitted limit will result in an "Internal Error" failure. + * + * @remarks + *
Requirement SetsFile
+ * + * For add-ins running in Office host applications other than Office for iOS, the getFileAsync method supports getting files in slices of up + * to 4194304 bytes (4 MB). For add-ins running in Office for iOS apps, the getFileAsync method supports getting files in slices of up to + * 65536 (64 KB). + * + * The fileType parameter can be specified by using the {@link Office.FileType} enumeration or text values. But the possible values vary with + * the host: + * + * Excel for Windows desktop, iPad, and Excel Online: `Office.FileType.Compressed` + * + * Excel for Mac: `Office.FileType.Compressed`, `Office.FileType.Pdf` + * + * PowerPoint for Windows desktop, Mac, iPad, and PowerPoint Online: `Office.FileType.Compressed`, `Office.FileType.Pdf` + * + * Word for Windows desktop, Mac, iPad, and Word Online: `Office.FileType.Compressed`, `Office.FileType.Pdf`, `Office.FileType.Text` + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param fileType The format in which the file will be returned + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the File object. + */ getFileAsync(fileType: FileType, callback?: (result: AsyncResult) => void): void; /** * Gets file properties of the current document. @@ -3472,8 +4170,35 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the file's properties (with the URL found at `asyncResult.value.url`). - */ + */ getFilePropertiesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets file properties of the current document. + * + * @remarks + *
Requirement SetsNot in a set
+ * + * You get the file's URL with the url property `asyncResult.value.url`. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the file's properties (with the URL found at `asyncResult.value.url`). + */ getFilePropertiesAsync(callback?: (result: AsyncResult) => void): void; /** * Reads the data contained in the current selection in the document. @@ -3571,6 +4296,98 @@ declare namespace Office { * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Reads the data contained in the current selection in the document. + * + * @remarks + *
Requirement SetsSelection
+ * + * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * the following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * The possible values for the {@link Office.CoercionType} parameter vary by the host. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
HostSupported coercionType
Excel, PowerPoint, Project, and Word`Office.CoercionType.Text` (string)
Excel and Word`Office.CoercionType.Matrix` (array of arrays)
Access, Excel, and Word`Office.CoercionType.Table` (TableData object)
Word`Office.CoercionType.Html`
Word`Office.CoercionType.Ooxml` (Office Open XML)
PowerPoint and PowerPoint Online`Office.CoercionType.SlideRange`
Excel, PowerPoint, and Word`Office.CoercionType.XmlSvg`
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param coercionType The type of data structure to return. See the remarks section for each host's supported coercion types. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the data in the current selection. + * This is returned in the data structure or format you specified with the coercionType parameter. + * (See Remarks for more information about data coercion.) + */ getSelectedDataAsync(coercionType: Office.CoercionType, callback?: (result: AsyncResult) => void): void; /** * Goes to the specified object or location in the document. @@ -3614,6 +4431,46 @@ declare namespace Office { * The `value` property of the result is the current view. */ goToByIdAsync(id: string | number, goToType: GoToType, options?: GoToByIdOptions, callback?: (result: AsyncResult) => void): void; + /** + * Goes to the specified object or location in the document. + * + * @remarks + *
Requirement Setsnot in a set
+ * + * PowerPoint doesn't support the goToByIdAsync method in Master Views. + * + * The behavior caused by the selectionMode option varies by host: + * + * In Excel: `Office.SelectionMode.Selected` selects all content in the binding, or named item. Office.SelectionMode.None for text bindings, + * selects the cell; for matrix bindings, table bindings, and named items, selects the first data cell (not first cell in header row for tables). + * + * In PowerPoint: `Office.SelectionMode.Selected` selects the slide title or first textbox on the slide. + * `Office.SelectionMode.None` doesn't select anything. + * + * In Word: `Office.SelectionMode.Selected` selects all content in the binding. Office.SelectionMode.None for text bindings, moves the cursor + * to the beginning of the text; for matrix bindings and table bindings, selects the first data cell (not first cell in header row for tables). + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y
+ * + * @param id The identifier of the object or location to go to. + * @param goToType The type of the location to go to. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the current view. + */ goToByIdAsync(id: string | number, goToType: GoToType, callback?: (result: AsyncResult) => void): void; /** * Removes an event handler for the specified event type. @@ -3644,6 +4501,33 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the specified event type. + * + * @remarks + *
Requirement SetsDocumentEvents
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
OneNote Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param eventType The event type. For document can be 'Document.SelectionChanged' or 'Document.ActiveViewChanged'. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Writes the specified data into the current selection. @@ -3762,6 +4646,121 @@ declare namespace Office { * The AsyncResult.value property always returns undefined because there is no object or data to retrieve. */ setSelectedDataAsync(data: string | TableData | any[][], options?: SetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Writes the specified data into the current selection. + * + * @remarks + *
Requirement SetsSelection
+ * + * **Application-specific behaviors** + * + * The following application-specific actions apply when writing data to a selection. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
WordIf there is no selection and the insertion point is at a valid location, the specified `data` is inserted at the insertion pointIf `data` is a string, the specified text is inserted.
If `data` is an array of arrays ("matrix") or a TableData object, a new Word table is inserted.
If `data` is HTML, the specified HTML is inserted. (Important: If any of the HTML you insert is invalid, Word won't raise an error. Word will insert as much of the HTML as it can and omits any invalid data).
If `data` is Office Open XML, the specified XML is inserted.
If `data` is a base64 encoded image stream, the specified image is inserted.
If there is a selectionIt will be replaced with the specified `data` following the same rules as above.
Insert imagesInserted images are placed inline. The imageLeft and imageTop parameters are ignored. The image aspect ratio is always locked. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
ExcelIf a single cell is selectedIf `data` is a string, the specified text is inserted as the value of the current cell.
If `data` is an array of arrays ("matrix"), the specified set of rows and columns are inserted, if no other data in surrounding cells will be overwritten.
If `data` is a TableData object, a new Excel table with the specified set of rows and headers is inserted, if no other data in surrounding cells will be overwritten.
If multiple cells are selectedIf the shape does not match the shape of `data`, an error is returned.
If the shape of the selection exactly matches the shape of `data`, the values of the selected cells are updated based on the values in `data`.
Insert imagesInserted images are floating. The position imageLeft and imageTop parameters are relative to currently selected cell(s). Negative imageLeft and imageTop values are allowed and possibly readjusted by Excel to position the image inside a worksheet. Image aspect ratio is locked unless both imageWidth and imageHeight parameters are provided. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
All other casesAn error is returned.
Excel OnlineIn addition to the behaviors described for Excel above, these limits apply when writing data in Excel OnlineThe total number of cells you can write to a worksheet with the `data` parameter can't exceed 20,000 in a single call to this method.
The number of formatting groups passed to the `cellFormat` parameter can't exceed 100. A single formatting group consists of a set of formatting applied to a specified range of cells.
PowerPointInsert imageInserted images are floating. The position imageLeft and imageTop parameters are optional but if provided, both should be present. If a single value is provided, it will be ignored. Negative imageLeft and imageTop values are allowed and can position an image outside of a slide. If no optional parameter is given and slide has a placeholder, the image will replace the placeholder in the slide. Image aspect ratio will be locked unless both imageWidth and imageHeight parameters are provided. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
+ * + * The possible values for the {@link Office.CoercionType} parameter vary by the host. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
HostSupported coercionType
Excel, PowerPoint, Project, and Word`Office.CoercionType.Text` (string)
Excel and Word`Office.CoercionType.Matrix` (array of arrays)
Access, Excel, and Word`Office.CoercionType.Table` (TableData object)
Word`Office.CoercionType.Html`
Word`Office.CoercionType.Ooxml` (Office Open XML)
PowerPoint and PowerPoint Online`Office.CoercionType.SlideRange`
Excel, PowerPoint, and Word`Office.CoercionType.XmlSvg`
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param data The data to be set. Either a string or {@link Office.CoercionType} value, 2d array or TableData object. + * + * If the value passed for `data` is: + * + * - A string: Plain text or anything that can be coerced to a string will be inserted. + * In Excel, you can also specify data as a valid formula to add that formula to the selected cell. For example, setting data to "=SUM(A1:A5)" + * will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added + * formula (or any pre-existing formula) from the bound cell. If you call the Document.getSelectedDataAsync method on the selected cell to + * read its data, the method can return only the data displayed in the cell (the formula's result). + * + * - An array of arrays ("matrix"): Tabular data without headers will be inserted. For example, to write data to three rows in two columns, + * you can pass an array like this: [["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]. To write a single column of three rows, pass an + * array like this: [["R1C1"], ["R2C1"], ["R3C1"]] + * + * In Excel, you can also specify data as an array of arrays that contains valid formulas to add them to the selected cells. For example if no + * other data will be overwritten, setting data to [["=SUM(A1:A5)","=AVERAGE(A1:A5)"]] will add those two formulas to the selection. Just as + * when setting a formula on a single cell as "text", you can't read the added formulas (or any pre-existing formulas) after they have been + * set - you can only read the formulas' results. + * + * - A TableData object: A table with headers will be inserted. + * In Excel, if you specify formulas in the TableData object you pass for the data parameter, you might not get the results you expect due to + * the "calculated columns" feature of Excel, which automatically duplicates formulas within a column. To work around this when you want to + * write `data` that contains formulas to a selected table, try specifying the data as an array of arrays (instead of a TableData object), and + * specify the coercionType as Microsoft.Office.Matrix or "matrix". + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The AsyncResult.value property always returns undefined because there is no object or data to retrieve. + */ setSelectedDataAsync(data: string | TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get Project field (Ex. ProjectWebAccessURL). @@ -3787,6 +4786,28 @@ declare namespace Office { * */ getProjectFieldAsync(fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get Project field (Ex. ProjectWebAccessURL). + * @param fieldId Project level fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the `fieldValue` property, which represents the value of the specified field. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getProjectFieldAsync(fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get resource field for provided resource Id. (Ex.ResourceName) @@ -3813,6 +4834,29 @@ declare namespace Office { * */ getResourceFieldAsync(resourceId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get resource field for provided resource Id. (Ex.ResourceName) + * @param resourceId Either a string or value of the Resource Id. + * @param fieldId Resource Fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getResourceFieldAsync(resourceId: string, fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected Resource's Id. @@ -3837,6 +4881,27 @@ declare namespace Office { * */ getSelectedResourceAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected Resource's Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedResourceAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected Task's Id. @@ -3861,6 +4926,27 @@ declare namespace Office { * */ getSelectedTaskAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected Task's Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedTaskAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected View Type (Ex. Gantt) and View Name. @@ -3887,6 +4973,29 @@ declare namespace Office { * */ getSelectedViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected View Type (Ex. Gantt) and View Name. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `viewName` - The name of the view, as a ProjectViewTypes constant. + * `viewType` - The type of view, as the integer value of a ProjectViewTypes constant. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedViewAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the Task Name, WSS Task Id, and ResourceNames for given taskId. @@ -3915,6 +5024,31 @@ declare namespace Office { * */ getTaskAsync(taskId: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the Task Name, WSS Task Id, and ResourceNames for given taskId. + * @param taskId Either a string or value of the Task Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `taskName` - The name of the task. + * `wssTaskId` - The ID of the task in the synchronized SharePoint task list. If the project is not synchronized with a SharePoint task list, the value is 0. + * `resourceNames` - The comma-separated list of the names of resources that are assigned to the task. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskAsync(taskId: string, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get task field for provided task Id. (Ex. StartDate). @@ -3941,6 +5075,29 @@ declare namespace Office { * */ getTaskFieldAsync(taskId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get task field for provided task Id. (Ex. StartDate). + * @param taskId Either a string or value of the Task Id. + * @param fieldId Task Fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the `fieldValue` property, which represents the value of the specified field. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskFieldAsync(taskId: string, fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. @@ -3967,6 +5124,29 @@ declare namespace Office { * */ getWSSUrlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `listName` - the name of the synchronized SharePoint task list. + * `serverUrl` - the URL of the synchronized SharePoint task list. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getWSSUrlAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the maximum index of the collection of resources in the current project. @@ -3994,6 +5174,30 @@ declare namespace Office { * */ getMaxResourceIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the maximum index of the collection of resources in the current project. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the highest index number in the current project's resource collection. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getMaxResourceIndexAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the maximum index of the collection of tasks in the current project. @@ -4021,6 +5225,30 @@ declare namespace Office { * */ getMaxTaskIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the maximum index of the collection of tasks in the current project. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the highest index number in the current project's task collection. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getMaxTaskIndexAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the GUID of the resource that has the specified index in the resource collection. @@ -4049,6 +5277,31 @@ declare namespace Office { * */ getResourceByIndexAsync(resourceIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the GUID of the resource that has the specified index in the resource collection. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param resourceIndex The index of the resource in the collection of resources for the project. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getResourceByIndexAsync(resourceIndex: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the GUID of the task that has the specified index in the task collection. @@ -4077,6 +5330,31 @@ declare namespace Office { * */ getTaskByIndexAsync(taskIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the GUID of the task that has the specified index in the task collection. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param taskIndex The index of the task in the collection of tasks for the project. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the task as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskByIndexAsync(taskIndex: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Set resource field for specified resource Id. @@ -4106,6 +5384,32 @@ declare namespace Office { * */ setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Set resource field for specified resource Id. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param resourceId Either a string or value of the Resource Id. + * @param fieldId Resource Fields. + * @param fieldValue Value of the target field. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Set task field for specified task Id. @@ -4135,6 +5439,32 @@ declare namespace Office { * */ setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Set task field for specified task Id. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param taskId Either a string or value of the Task Id. + * @param fieldId Task Fields. + * @param fieldValue Value of the target field. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult) => void): void; } /** @@ -4386,6 +5716,61 @@ declare namespace Office { * */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler for the settingsChanged event. + * + * Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but + * the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the + * spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. + * + * @remarks + * + *
Requirement SetsSettings
+ * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType Specifies the type of event to add. Required. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.SettingsChangedEventArgs}. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no data or object to retrieve when adding an event handler.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y
+ */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult) => void): void; /** * Retrieves the specified setting. @@ -4542,6 +5927,40 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the settingsChanged event. + * + * @remarks + * + *
Requirement SetsSettings
+ * + * If the optional handler parameter is omitted when calling the removeHandlerAsync method, all event handlers for the specified eventType + * will be removed. + * + * When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback + * function's only parameter. + * + * In the callback function passed to the removeHandlerAsync method, you can use the properties of the AsyncResult object to return the + * following information. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y
+ * + * @param eventType Specifies the type of event to remove. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Persists the in-memory copy of the settings property bag in the document. @@ -4600,6 +6019,61 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult) => void): void; + /** + * Persists the in-memory copy of the settings property bag in the document. + * + * @remarks + * Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use the + * set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they are + * available the next time the add-in is used, use the saveAsync method. + * + * Note: The saveAsync method persists the in-memory settings property bag into the document file. However, the changes to the document file + * itself are saved only when the user (or AutoRecover setting) saves the document to the file system. The refreshAsync method is only useful + * in coauthoring scenarios when other instances of the same add-in might change the settings and those changes should be made available to + * all instances. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ saveAsync(callback?: (result: AsyncResult) => void): void; /** * Sets or creates the specified setting. @@ -4861,6 +6335,47 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addColumnsAsync(tableData: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds the specified data to the table as additional columns. + * + * @remarks + * + * To add one or more columns specifying the values of the data and headers, pass a TableData object as the data parameter. To add one or more + * columns specifying only the data, pass an array of arrays ("matrix") as the data parameter. + * + * The success or failure of an addColumnsAsync operation is atomic. That is, the entire add columns operation must succeed, or it will be + * completely rolled back (and the AsyncResult.status property returned to the callback will report failure): + * + * - Each row in the array you pass as the data argument must have the same number of rows as the table being updated. If not, the entire + * operation will fail. + * + * - Each row and cell in the array must successfully add that row or cell to the table in the newly added column(s). If any row or cell + * fails to be set for any reason, the entire operation will fail. + * + * - If you pass a TableData object as the data argument, the number of header rows must match that of the table being updated. + * + * Additional remark for Excel Online: The total number of cells in the TableData object passed to the data parameter can't exceed 20,000 in + * a single call to this method. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param tableData An array of arrays ("matrix") or a TableData object that contains one or more columns of data to add to the table. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addColumnsAsync(tableData: TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Adds the specified data to the table as additional rows. @@ -4902,6 +6417,44 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addRowsAsync(rows: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds the specified data to the table as additional rows. + * + * @remarks + * + * The success or failure of an addRowsAsync operation is atomic. That is, the entire add columns operation must succeed, or it will be + * completely rolled back (and the AsyncResult.status property returned to the callback will report failure): + * + * - Each row in the array you pass as the data argument must have the same number of columns as the table being updated. If not, the entire + * operation will fail. + * + * - Each column and cell in the array must successfully add that column or cell to the table in the newly added rows(s). If any column or + * cell fails to be set for any reason, the entire operation will fail. + * + * - If you pass a TableData object as the data argument, the number of header rows must match that of the table being updated. + * + * Additional remark for Excel Online: The total number of cells in the TableData object passed to the data parameter can't exceed 20,000 in + * a single call to this method. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param rows An array of arrays ("matrix") or a TableData object that contains one or more rows of data to add to the table. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addRowsAsync(rows: TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Deletes all non-header rows and their values in the table, shifting appropriately for the host application. @@ -4930,6 +6483,31 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ deleteAllDataValuesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Deletes all non-header rows and their values in the table, shifting appropriately for the host application. + * + * @remarks + * + * In Excel, if the table has no header row, this method will delete the table itself. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ deleteAllDataValuesAsync(callback?: (result: AsyncResult) => void): void; /** * Clears formatting on the bound table. @@ -4955,6 +6533,28 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ clearFormatsAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Clears formatting on the bound table. + * + * @remarks + * See {@link https://docs.microsoft.com/office/dev/add-ins/excel/excel-add-ins-tables#format-a-table | Format tables in add-ins for Excel} for more information. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ clearFormatsAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the formatting on specified items in the table. @@ -5010,6 +6610,58 @@ declare namespace Office { * The `value` property of the result is an array containing one or more JavaScript objects specifying the formatting of their corresponding cells. */ getFormatsAsync(cellReference?: any, formats?: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult< ({ cells: any, format: any})[]>) => void): void; + /** + * Gets the formatting on specified items in the table. + * + * @remarks + * + * **Returned format structure** + * + * Each JavaScript object in the return value array has this form: `{cells:{ cell_range }, format:{ format_definition }}` + * + * The `cells:` property specifies the range you want format using one of the following values: + * + * **Supported ranges in cells property** + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
cells range settingsDescription
`{row: n}`Specifies the range that is the zero-based nth row of data in the table.
`{column: n}`Specifies the range that is the zero-based nth column of data in the table.
`{row: i, column: j}`Specifies the single cell that is the ith row and jth column of the table.
`Office.Table.All`Specifies the entire table, including column headers, data, and totals (if any).
`Office.Table.Data`Specifies only the data in the table (no headers and totals).
`Office.Table.Headers`Specifies only the header row.
+ * + * The `format:` property specifies values that correspond to a subset of the settings available in the Format Cells dialog box in Excel + * (Right-click \> Format Cells or Home \> Format \> Format Cells). + * + * @param cellReference An object literal containing name-value pairs that specify the range of cells to get formatting from. + * @param formats An array specifying the format properties to get. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array containing one or more JavaScript objects specifying the formatting of their corresponding cells. + */ getFormatsAsync(cellReference?: any, formats?: any[], callback?: (result: AsyncResult< ({ cells: any, format: any})[]>) => void): void; /** * Sets formatting on specified items and data in the table. @@ -5124,6 +6776,117 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setFormatsAsync(cellFormat: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets formatting on specified items and data in the table. + * + * @remarks + * + * **Specifying the cellFormat parameter** + * + * Use the cellFormat parameter to set or change cell formatting values, such as width, height, font, background, alignment, and so on. + * The value you pass as the cellFormat parameter is an array that contains a list of one or more JavaScript objects that specify which cells + * to target (`cells:`) and the formats (`format:`) to apply to them. + * + * Each JavaScript object in the cellFormat array has this form: `{cells:{ cell_range }, format:{ format_definition }}` + * + * The `cells:` property specifies the range you want format using one of the following values: + * + * **Supported ranges in cells property** + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
cells range settingsDescription
`{row: n}`Specifies the range that is the zero-based nth row of data in the table.
`{column: n}`Specifies the range that is the zero-based nth column of data in the table.
`{row: i, column: j}`Specifies the single cell that is the ith row and jth column of the table.
`Office.Table.All`Specifies the entire table, including column headers, data, and totals (if any).
`Office.Table.Data`Specifies only the data in the table (no headers and totals).
`Office.Table.Headers`Specifies only the header row.
+ * + * The `format:` property specifies values that correspond to a subset of the settings available in the Format Cells dialog box in Excel + * (Right-click \> Format Cells or Home \> Format \> Format Cells). + * + * You specify the value of the `format:` property as a list of one or more property name - value pairs in a JavaScript object literal. The + * property name specifies the name of the formatting property to set, and value specifies the property value. + * You can specify multiple values for a given format, such as both a font's color and size. + * + * Here's three `format:` property value examples: + * + * `//Set cells: font color to green and size to 15 points.` + * + * `format: {fontColor : "green", fontSize : 15}` + * + * `//Set cells: border to dotted blue.` + * + * `format: {borderStyle: "dotted", borderColor: "blue"}` + * + * `//Set cells: background to red and alignment to centered.` + * + * `format: {backgroundColor: "red", alignHorizontal: "center"}` + * + * + * You can specify number formats by specifying the number formatting "code" string in the `numberFormat:` property. + * The number format strings you can specify correspond to those you can set in Excel using the Custom category on the Number tab of the Format Cells dialog box. + * This example shows how to format a number as a percentage with two decimal places: + * + * `format: {numberFormat:"0.00%"}` + * + * For more detail, see how to {@link https://support.office.com/article/create-or-delete-a-custom-number-format-78f2a361-936b-4c03-8772-09fab54be7f4 | Create a custom number format}. + * + * To set formatting on tables when writing data, use the tableOptions and cellFormat optional parameters of the + * `Document.setSelectedDataAsync` or `TableBinding.setDataAsync` methods. + * + * Setting formatting with the optional parameters of the `Document.setSelectedDataAsync` and `TableBinding.setDataAsync` methods only works + * to set formatting when writing data the first time. + * To make formatting changes after writing data, use the following methods: + * + * - To update cell formatting, such as font color and style, use the `TableBinding.setFormatsAsync` method (this method). + * + * - To update table options, such as banded rows and filter buttons, use the `TableBinding.setTableOptions` method. + * + * - To clear formatting, use the `TableBinding.clearFormats` method. + * + * For more details and examples, see + * {@link https://docs.microsoft.com/office/dev/add-ins/excel/excel-add-ins-tables#format-a-table | How to format tables in add-ins for Excel}. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param cellFormat An array that contains one or more JavaScript objects that specify which cells to target and the formatting to apply to them. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setFormatsAsync(cellFormat: any[], callback?: (result: AsyncResult) => void): void; /** * Updates table formatting options on the bound table. @@ -5178,6 +6941,57 @@ declare namespace Office { * */ setTableOptionsAsync(tableOptions: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Updates table formatting options on the bound table. + * + * @remarks + * + * + *
HostsExcel
Requirement SetsNot in a set
+ * + * In the callback function passed to the goToByIdAsync method, you can use the properties of the AsyncResult object to return the following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no data or object to retrieve when setting formats.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param tableOptions An object literal containing a list of property name-value pairs that define the table options to apply. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + */ setTableOptionsAsync(tableOptions: any, callback?: (result: AsyncResult) => void): void; } /** diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index f0fee147ba..bea8c12db6 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -1093,6 +1093,104 @@ declare namespace Office { * @param callback - Optional. Accepts a callback method to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object. */ displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult) => void): void; + /** + * Displays a dialog to show or collect information from the user or to facilitate Web navigation. + * + * @remarks + * + * + *
HostsWord, Excel, Outlook, PowerPoint
Requirement setsDialogApi, Mailbox 1.4
+ * + * This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 + * for Outlook. For more on how to specify a requirement set in your manifest, see + * {@link https://docs.microsoft.com/office/dev/add-ins/develop/specify-office-hosts-and-api-requirements | Specify Office hosts and API requirements}. + * + * The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial page loads, you can go to + * other domains. + * + * Any page calling `office.context.ui.messageParent` must also be on the same domain as the parent page. + * + * **Design considerations**: + * + * The following design considerations apply to dialog boxes: + * + * - An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the same time from Add-in + * Commands (custom ribbon buttons or menu items). + * + * - Every dialog box can be moved and resized by the user. + * + * - Every dialog box is centered on the screen when opened. + * + * - Dialog boxes appear on top of the host application and in the order in which they were created. + * + * Use a dialog box to: + * + * - Display authentication pages to collect user credentials. + * + * - Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command. + * + * - Temporarily increase the surface area that a user has available to complete a task. + * + * Do not use a dialog box to interact with a document. Use a task pane instead. + * + * For a design pattern that you can use to create a dialog box, see + * {@link https://github.com/OfficeDev/Office-Add-in-UX-Design-Patterns/blob/master/Patterns/Client_Dialog.md | Client Dialog} in the Office + * Add-in UX Design Patterns repository on GitHub. + * + * **displayDialogAsync Errors**: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Code numberMeaning
12004The domain of the URL passed to displayDialogAsync is not trusted. The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the section of the add-in manifest.
12005The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
12007A dialog box is already opened from the task pane. A task pane add-in can only have one dialog box open at a time.
12009The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.
+ * + * In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the + * following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to
AsyncResult.valueAccess the Dialog object.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextAccess your user-defined object or value, if you passed one as the asyncContext parameter.
+ * + * @param startAddress - Accepts the initial HTTPS URL that opens in the dialog. + * @param callback - Optional. Accepts a callback method to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object. + */ displayDialogAsync(startAddress: string, callback?: (result: AsyncResult) => void): void; /** * Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent. @@ -2291,6 +2389,17 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: Office.AsyncResult) => void): void; + /** + * Adds an event handler to the object for the specified {@link Office.EventType}. Supported EventTypes are + * `Office.EventType.BindingDataChanged` and `Office.EventType.BindingSelectionChanged`. + * + * @remarks + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType The event type. For bindings, it can be `Office.EventType.BindingDataChanged` or `Office.EventType.BindingSelectionChanged`. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.BindingDataChangedEventArgs} or {@link Office.BindingSelectionChangedEventArgs}. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: Office.AsyncResult) => void): void; /** * Returns the data contained within the binding. @@ -2307,6 +2416,19 @@ declare namespace Office { * If the `coercionType` parameter is specified (and the call is successful), the data is returned in the format described in the CoercionType enumeration topic. */ getDataAsync(options?: GetBindingDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns the data contained within the binding. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * When called from a MatrixBinding or TableBinding, the getDataAsync method will return a subset of the bound values if the optional startRow, + * startColumn, rowCount, and columnCount parameters are specified (and they specify a contiguous and valid range). + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the values in the specified binding. + * If the `coercionType` parameter is specified (and the call is successful), the data is returned in the format described in the CoercionType enumeration topic. + */ getDataAsync(callback?: (result: AsyncResult) => void): void; /** * Removes the specified handler from the binding for the specified event type. @@ -2319,6 +2441,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes the specified handler from the binding for the specified event type. + * + * @remarks + *
Requirement SetsBindingEvents
+ * + * @param eventType The event type. For bindings, it can be `Office.EventType.BindingDataChanged` or `Office.EventType.BindingSelectionChanged`. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Writes data to the bound section of the document represented by the specified binding object. @@ -2451,6 +2582,134 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setDataAsync(data: TableData | any, options?: SetBindingDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Writes data to the bound section of the document represented by the specified binding object. + * + * @remarks + * + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * The value passed for data contains the data to be written in the binding. The kind of value passed determines what will be written as + * described in the following table. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringPlain text or anything that can be coerced to a string will be written.
An array of arrays ("matrix")Tabular data without headers will be written. For example, to write data to three rows in two columns, you can pass an array like this: `[["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]`. To write a single column of three rows, pass an array like this: `[["R1C1"], ["R2C1"], ["R3C1"]]`.
An {@link Office.TableData} objectA table with headers will be written.
+ * + * Additionally, these application-specific actions apply when writing data to a binding. For Word, the specified data is written to the + * binding as follows: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringThe specified text is written.
An array of arrays ("matrix") or an {@link Office.TableData} objectA Word table is written.
HTMLThe specified HTML is written. If any of the HTML you write is invalid, Word will not raise an error. Word will write as much of the HTML as it can and will omit any invalid data.
Office Open XML ("Open XML")The specified the XML is written.
+ * + * For Excel, the specified data is written to the binding as follows: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
`data` valueData written
A stringThe specified text is inserted as the value of the first bound cell.You can also specify a valid formula to add that formula to the bound cell. For example, setting data to `"=SUM(A1:A5)"` will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added formula (or any pre-existing formula) from the bound cell. If you call the Binding.getDataAsync method on the bound cell to read its data, the method can return only the data displayed in the cell (the formula's result).
An array of arrays ("matrix"), and the shape exactly matches the shape of the binding specifiedThe set of rows and columns are written.You can also specify an array of arrays that contain valid formulas to add them to the bound cells. For example, setting data to `[["=SUM(A1:A5)","=AVERAGE(A1:A5)"]]` will add those two formulas to a binding that contains two cells. Just as when setting a formula on a single bound cell, you can't read the added formulas (or any pre-existing formulas) from the binding with the `Binding.getDataAsync` method - it returns only the data displayed in the bound cells.
An {@link Office.TableData} object, and the shape of the table matches the bound table.The specified set of rows and/or headers are written, if no other data in surrounding cells will be overwritten. Note: If you specify formulas in the TableData object you pass for the *data* parameter, you might not get the results you expect due to the "calculated columns" feature of Excel, which automatically duplicates formulas within a column. To work around this when you want to write *data* that contains formulas to a bound table, try specifying the data as an array of arrays (instead of a TableData object), and specify the *coercionType* as Microsoft.Office.Matrix or "matrix".
+ * + * For Excel Online: + * + * - The total number of cells in the value passed to the data parameter can't exceed 20,000 in a single call to this method. + * + * - The number of formatting groups passed to the cellFormat parameter can't exceed 100. + * A single formatting group consists of a set of formatting applied to a specified range of cells. + * + * In all other cases, an error is returned. + * + * The setDataAsync method will write data in a subset of a table or matrix binding if the optional startRow and startColumn parameters are + * specified, and they specify a valid range. + * + * In the callback function passed to the setDataAsync method, you can use the properties of the AsyncResult object to return the following + * information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * @param data The data to be set in the current selection. Possible data types by host: + * + * string: Excel, Excel Online, Word, and Word Online only + * + * array of arrays: Excel and Word only + * + * {@link Office.TableData}: Access, Excel, and Word only + * + * HTML: Word and Word Online only + * + * Office Open XML: Word only + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setDataAsync(data: TableData | any, callback?: (result: AsyncResult) => void): void; } @@ -2601,6 +2860,50 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the specified named item. */ addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult) => void): void; + /** + * Creates a binding against a named object in the document. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * For Excel, the itemName parameter can refer to a named range or a table. + * + * By default, adding a table in Excel assigns the name "Table1" for the first table you add, "Table2" for the second table you add, and so on. + * To assign a meaningful name for a table in the Excel UI, use the Table Name property on the Table Tools | Design tab of the ribbon. + * + * Note: In Excel, when specifying a table as a named item, you must fully qualify the name to include the worksheet name in the name of + * the table in this format: "Sheet1!Table1" + * + * For Word, the itemName parameter refers to the Title property of a Rich Text content control. (You can't bind to content controls other + * than the Rich Text content control). + * + * By default, a content control has no Title value assigned. To assign a meaningful name in the Word UI, after inserting a Rich Text content + * control from the Controls group on the Developer tab of the ribbon, use the Properties command in the Controls group to display the Content + * Control Properties dialog box. Then set the Title property of the content control to the name you want to reference from your code. + * + * Note: In Word, if there are multiple Rich Text content controls with the same Title property value (name), and you try to bind to one + * these content controls with this method (by specifying its name as the itemName parameter), the operation will fail. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * @param itemName Name of the bindable object in the document. For Example 'MyExpenses' table in Excel." + * @param bindingType The {@link Office.BindingType} for the data. The method returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the specified named item. + */ addFromNamedItemAsync(itemName: string, bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Create a binding by prompting the user to make a selection on the document. @@ -2633,6 +2936,35 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the selection specified by the user. */ addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult) => void): void; + /** + * Create a binding by prompting the user to make a selection on the document. + * + * @remarks + *
Requirement SetsNot in a set
+ * + * Adds a binding object of the specified type to the Bindings collection, which will be identified with the supplied id. + * The method fails if the specified selection cannot be bound. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
+ * + * @param bindingType Specifies the type of the binding object to create. Required. + * Returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the selection specified by the user. + */ addFromPromptAsync(bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Create a binding based on the user's current selection. @@ -2670,6 +3002,40 @@ declare namespace Office { * The `value` property of the result is the Binding object that represents the selection specified by the user. */ addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult) => void): void; + /** + * Create a binding based on the user's current selection. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * Adds the specified type of binding object to the Bindings collection, which will be identified with the supplied id. + * + * Note In Excel, if you call the addFromSelectionAsync method passing in the Binding.id of an existing binding, the Binding.type of that + * binding is used, and its type cannot be changed by specifying a different value for the bindingType parameter. + * If you need to use an existing id and change the bindingType, call the Bindings.releaseByIdAsync method first to release the binding, and + * then call the addFromSelectionAsync method to reestablish the binding with a new type. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param bindingType Specifies the type of the binding object to create. Required. + * Returns null if the selected object cannot be coerced into the specified type. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object that represents the selection specified by the user. + */ addFromSelectionAsync(bindingType: BindingType, callback?: (result: AsyncResult) => void): void; /** * Gets all bindings that were previously created. @@ -2698,6 +3064,31 @@ declare namespace Office { * The `value` property of the result is an array that contains each binding created for the referenced Bindings object. */ getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets all bindings that were previously created. + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array that contains each binding created for the referenced Bindings object. + */ getAllAsync(callback?: (result: AsyncResult) => void): void; /** * Retrieves a binding based on its Name @@ -2727,8 +3118,36 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the Binding object specified by the id in the call. - */ + */ getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Retrieves a binding based on its Name + * + * @remarks + *
Requirement SetsCustomXmlParts, MatrixBindings, TableBindings, TextBindings
+ * + * Fails if the specified id does not exist. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param id Specifies the unique name of the binding object. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the Binding object specified by the id in the call. + */ getByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; /** * Removes the binding from the document @@ -2759,6 +3178,33 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ releaseByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes the binding from the document + * + * @remarks + *
Requirement SetsMatrixBindings, TableBindings, TextBindings
+ * + * Fails if the specified id does not exist. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param id Specifies the unique name to be used to identify the binding object. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ releaseByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; } /** @@ -2815,6 +3261,16 @@ declare namespace Office { * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the `xPath` parameter. */ getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the nodes associated with the XPath expression. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param xPath The XPath expression that specifies the nodes to get. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the `xPath` parameter. + */ getNodesAsync(xPath: string, callback?: (result: AsyncResult) => void): void; /** * Gets the node value. @@ -2827,6 +3283,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the value of the referenced node. */ getNodeValueAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the node value. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the value of the referenced node. + */ getNodeValueAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the text of an XML node in a custom XML part. @@ -2839,6 +3304,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the inner text of the referenced nodes. */ getTextAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the text of an XML node in a custom XML part. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the inner text of the referenced nodes. + */ getTextAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the node's XML. @@ -2851,6 +3325,15 @@ declare namespace Office { * The `value` property of the result is a string that contains the XML of the referenced node. */ getXmlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets the node's XML. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the XML of the referenced node. + */ getXmlAsync(callback?: (result: AsyncResult) => void): void; /** * Sets the node value. @@ -2863,6 +3346,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setNodeValueAsync(value: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the node value. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param value The value to be set on the node + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setNodeValueAsync(value: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously sets the text of an XML node in a custom XML part. @@ -2877,6 +3369,17 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setTextAsync(text: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously sets the text of an XML node in a custom XML part. + * + * @remarks + * + * + *
HostsWord
Requirement SetsCustomXmlParts
+ * + * @param text Required. The text value of the XML node. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setTextAsync(text: string, callback?: (result: AsyncResult) => void): void; /** * Sets the node XML. @@ -2889,6 +3392,15 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setXmlAsync(xml: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets the node XML. + * + * @remarks + *
Requirement SetsCustomXmlParts
+ * + * @param xml The XML to be set on the node + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setXmlAsync(xml: string, callback?: (result: AsyncResult) => void): void; } /** @@ -2924,7 +3436,6 @@ declare namespace Office { * Gets the set of namespace prefix mappings ({@link Office.CustomXmlPrefixMappings}) used against the current CustomXmlPart. */ namespaceManager: CustomXmlPrefixMappings; - /** * Adds an event handler to the object using the specified event type. * @@ -2940,45 +3451,68 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler to the object using the specified event type. + * + * @remarks + * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType Specifies the type of event to add. For a CustomXmlPart object, the eventType parameter can be specified as + * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.NodeDeletedEventArgs}, + * {@link Office.NodeInsertedEventArgs}, or {@link Office.NodeReplacedEventArgs} + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: (result: any) => void, callback?: (result: AsyncResult) => void): void; /** * Deletes the Custom XML Part. * - * @remarks - * * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ deleteAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Deletes the Custom XML Part. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ deleteAsync(callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath. * - * @remarks - * * @param xPath An XPath expression that specifies the nodes you want returned. Required. * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the xPath parameter. - */ + */ getNodesAsync(xPath: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets any CustomXmlNodes in this custom XML part which match the specified XPath. + * + * @param xPath An XPath expression that specifies the nodes you want returned. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlNode objects that represent the nodes specified by the XPath expression passed to the xPath parameter. + */ getNodesAsync(xPath: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the XML inside this custom XML part. * - * @remarks - * * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string that contains the XML of the referenced CustomXmlPart object. - */ + */ getXmlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the XML inside this custom XML part. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the XML of the referenced CustomXmlPart object. + */ getXmlAsync(callback?: (result: AsyncResult) => void): void; /** * Removes an event handler for the specified event type. * - * @remarks - * * @param eventType Specifies the type of event to remove. For a CustomXmlPart object, the eventType parameter can be specified as * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. * @param handler The name of the handler to remove. @@ -2986,6 +3520,14 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the specified event type. + * + * @param eventType Specifies the type of event to remove. For a CustomXmlPart object, the eventType parameter can be specified as + * `Office.EventType.NodeDeleted`, `Office.EventType.NodeInserted`, and `Office.EventType.NodeReplaced`. + * @param handler The name of the handler to remove. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, handler?: (result: any) => void, callback?: (result: AsyncResult) => void): void; } @@ -3126,6 +3668,13 @@ declare namespace Office { * The `value` property of the result is the newly created CustomXmlPart object. */ addAsync(xml: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously adds a new custom XML part to a file. + * + * @param xml The XML to add to the newly created custom XML part. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the newly created CustomXmlPart object. + */ addAsync(xml: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the specified custom XML part by its id. @@ -3137,6 +3686,14 @@ declare namespace Office { * If there is no custom XML part with the specified id, the method returns null. */ getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the specified custom XML part by its id. + * + * @param id The GUID of the custom XML part, including opening and closing braces. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a CustomXmlPart object that represents the specified custom XML part. + * If there is no custom XML part with the specified id, the method returns null. + */ getByIdAsync(id: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the specified custom XML part(s) by its namespace. @@ -3147,6 +3704,13 @@ declare namespace Office { * The `value` property of the result is an array of CustomXmlPart objects that match the specified namespace. */ getByNamespaceAsync(ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the specified custom XML part(s) by its namespace. + * + * @param ns The namespace URI. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array of CustomXmlPart objects that match the specified namespace. + */ getByNamespaceAsync(ns: string, callback?: (result: AsyncResult) => void): void; } /** @@ -3183,6 +3747,16 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addNamespaceAsync(prefix: string, ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously adds a prefix to namespace mapping to use when querying an item. + * + * @remarks + * If no namespace is assigned to the requested prefix, the method returns an empty string (""). + * + * @param prefix Specifies the prefix to add to the prefix mapping list. Required. + * @param ns Specifies the namespace URI to assign to the newly added prefix. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addNamespaceAsync(prefix: string, ns: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the namespace mapped to the specified prefix. @@ -3198,6 +3772,18 @@ declare namespace Office { * The `value` property of the result is a string that contains the namespace mapped to the specified prefix. */ getNamespaceAsync(prefix: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the namespace mapped to the specified prefix. + * + * @remarks + * + * If the prefix already exists in the namespace manager, this method will overwrite the mapping of that prefix except when the prefix is one + * added or used by the data store internally, in which case it will return an error. + * + * @param prefix TSpecifies the prefix to get the namespace for. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the namespace mapped to the specified prefix. + */ getNamespaceAsync(prefix: string, callback?: (result: AsyncResult) => void): void; /** * Asynchronously gets the prefix for the specified namespace. @@ -3211,8 +3797,20 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is a string that contains the prefix of the specified namespace. - */ + */ getPrefixAsync(ns: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Asynchronously gets the prefix for the specified namespace. + * + * @remarks + * + * If no prefix is assigned to the requested namespace, the method returns an empty string (""). If there are multiple prefixes specified in + * the namespace manager, the method returns the first prefix that matches the supplied namespace. + * + * @param ns Specifies the namespace to get the prefix for. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is a string that contains the prefix of the specified namespace. + */ getPrefixAsync(ns: string, callback?: (result: AsyncResult) => void): void; } /** @@ -3369,6 +3967,37 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler for a Document object event. + * + * @remarks + *
Requirement SetsDocumentEvents
+ * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
OneNote Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param eventType For a Document object event, the eventType parameter can be specified as `Office.EventType.Document.SelectionChanged` or + * `Office.EventType.Document.ActiveViewChanged`, or the corresponding text value of this enumeration. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.DocumentSelectionChangedEventArgs}. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult) => void): void; /** * Returns the state of the current view of the presentation (edit or read). @@ -3397,8 +4026,35 @@ declare namespace Office { * The `value` property of the result is the state of the presentation's current view. * The value returned can be either "edit" or "read". "edit" corresponds to any of the views in which you can edit slides, * such as Normal or Outline View. "read" corresponds to either Slide Show or Reading View. - */ + */ getActiveViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<"edit" | "read">) => void): void; + /** + * Returns the state of the current view of the presentation (edit or read). + * + * @remarks + *
Requirement SetsActiveView
+ * + * Can trigger an event when the view changes. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
PowerPoint Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the state of the presentation's current view. + * The value returned can be either "edit" or "read". "edit" corresponds to any of the views in which you can edit slides, + * such as Normal or Outline View. "read" corresponds to either Slide Show or Reading View. + */ getActiveViewAsync(callback?: (result: AsyncResult<"edit" | "read">) => void): void; /** * Returns the entire document file in slices of up to 4194304 bytes (4 MB). For add-ins for iOS, file slice is supported up to 65536 (64 KB). @@ -3444,6 +4100,48 @@ declare namespace Office { * The `value` property of the result is the File object. */ getFileAsync(fileType: FileType, options?: GetFileOptions, callback?: (result: AsyncResult) => void): void; + /** + * Returns the entire document file in slices of up to 4194304 bytes (4 MB). For add-ins for iOS, file slice is supported up to 65536 (64 KB). + * Note that specifying file slice size of above permitted limit will result in an "Internal Error" failure. + * + * @remarks + *
Requirement SetsFile
+ * + * For add-ins running in Office host applications other than Office for iOS, the getFileAsync method supports getting files in slices of up + * to 4194304 bytes (4 MB). For add-ins running in Office for iOS apps, the getFileAsync method supports getting files in slices of up to + * 65536 (64 KB). + * + * The fileType parameter can be specified by using the {@link Office.FileType} enumeration or text values. But the possible values vary with + * the host: + * + * Excel for Windows desktop, iPad, and Excel Online: `Office.FileType.Compressed` + * + * Excel for Mac: `Office.FileType.Compressed`, `Office.FileType.Pdf` + * + * PowerPoint for Windows desktop, Mac, iPad, and PowerPoint Online: `Office.FileType.Compressed`, `Office.FileType.Pdf` + * + * Word for Windows desktop, Mac, iPad, and Word Online: `Office.FileType.Compressed`, `Office.FileType.Pdf`, `Office.FileType.Text` + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param fileType The format in which the file will be returned + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the File object. + */ getFileAsync(fileType: FileType, callback?: (result: AsyncResult) => void): void; /** * Gets file properties of the current document. @@ -3472,8 +4170,35 @@ declare namespace Office { * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * The `value` property of the result is the file's properties (with the URL found at `asyncResult.value.url`). - */ + */ getFilePropertiesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Gets file properties of the current document. + * + * @remarks + *
Requirement SetsNot in a set
+ * + * You get the file's URL with the url property `asyncResult.value.url`. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param callback A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the file's properties (with the URL found at `asyncResult.value.url`). + */ getFilePropertiesAsync(callback?: (result: AsyncResult) => void): void; /** * Reads the data contained in the current selection in the document. @@ -3571,6 +4296,98 @@ declare namespace Office { * (See Remarks for more information about data coercion.) */ getSelectedDataAsync(coercionType: Office.CoercionType, options?: GetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Reads the data contained in the current selection in the document. + * + * @remarks + *
Requirement SetsSelection
+ * + * In the callback function that is passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return + * the following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * The possible values for the {@link Office.CoercionType} parameter vary by the host. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
HostSupported coercionType
Excel, PowerPoint, Project, and Word`Office.CoercionType.Text` (string)
Excel and Word`Office.CoercionType.Matrix` (array of arrays)
Access, Excel, and Word`Office.CoercionType.Table` (TableData object)
Word`Office.CoercionType.Html`
Word`Office.CoercionType.Ooxml` (Office Open XML)
PowerPoint and PowerPoint Online`Office.CoercionType.SlideRange`
Excel, PowerPoint, and Word`Office.CoercionType.XmlSvg`
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param coercionType The type of data structure to return. See the remarks section for each host's supported coercion types. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the data in the current selection. + * This is returned in the data structure or format you specified with the coercionType parameter. + * (See Remarks for more information about data coercion.) + */ getSelectedDataAsync(coercionType: Office.CoercionType, callback?: (result: AsyncResult) => void): void; /** * Goes to the specified object or location in the document. @@ -3614,6 +4431,46 @@ declare namespace Office { * The `value` property of the result is the current view. */ goToByIdAsync(id: string | number, goToType: GoToType, options?: GoToByIdOptions, callback?: (result: AsyncResult) => void): void; + /** + * Goes to the specified object or location in the document. + * + * @remarks + *
Requirement Setsnot in a set
+ * + * PowerPoint doesn't support the goToByIdAsync method in Master Views. + * + * The behavior caused by the selectionMode option varies by host: + * + * In Excel: `Office.SelectionMode.Selected` selects all content in the binding, or named item. Office.SelectionMode.None for text bindings, + * selects the cell; for matrix bindings, table bindings, and named items, selects the first data cell (not first cell in header row for tables). + * + * In PowerPoint: `Office.SelectionMode.Selected` selects the slide title or first textbox on the slide. + * `Office.SelectionMode.None` doesn't select anything. + * + * In Word: `Office.SelectionMode.Selected` selects all content in the binding. Office.SelectionMode.None for text bindings, moves the cursor + * to the beginning of the text; for matrix bindings and table bindings, selects the first data cell (not first cell in header row for tables). + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y
+ * + * @param id The identifier of the object or location to go to. + * @param goToType The type of the location to go to. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the current view. + */ goToByIdAsync(id: string | number, goToType: GoToType, callback?: (result: AsyncResult) => void): void; /** * Removes an event handler for the specified event type. @@ -3644,6 +4501,33 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the specified event type. + * + * @remarks + *
Requirement SetsDocumentEvents
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
OneNote Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param eventType The event type. For document can be 'Document.SelectionChanged' or 'Document.ActiveViewChanged'. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Writes the specified data into the current selection. @@ -3762,6 +4646,121 @@ declare namespace Office { * The AsyncResult.value property always returns undefined because there is no object or data to retrieve. */ setSelectedDataAsync(data: string | TableData | any[][], options?: SetSelectedDataOptions, callback?: (result: AsyncResult) => void): void; + /** + * Writes the specified data into the current selection. + * + * @remarks + *
Requirement SetsSelection
+ * + * **Application-specific behaviors** + * + * The following application-specific actions apply when writing data to a selection. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
WordIf there is no selection and the insertion point is at a valid location, the specified `data` is inserted at the insertion pointIf `data` is a string, the specified text is inserted.
If `data` is an array of arrays ("matrix") or a TableData object, a new Word table is inserted.
If `data` is HTML, the specified HTML is inserted. (Important: If any of the HTML you insert is invalid, Word won't raise an error. Word will insert as much of the HTML as it can and omits any invalid data).
If `data` is Office Open XML, the specified XML is inserted.
If `data` is a base64 encoded image stream, the specified image is inserted.
If there is a selectionIt will be replaced with the specified `data` following the same rules as above.
Insert imagesInserted images are placed inline. The imageLeft and imageTop parameters are ignored. The image aspect ratio is always locked. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
ExcelIf a single cell is selectedIf `data` is a string, the specified text is inserted as the value of the current cell.
If `data` is an array of arrays ("matrix"), the specified set of rows and columns are inserted, if no other data in surrounding cells will be overwritten.
If `data` is a TableData object, a new Excel table with the specified set of rows and headers is inserted, if no other data in surrounding cells will be overwritten.
If multiple cells are selectedIf the shape does not match the shape of `data`, an error is returned.
If the shape of the selection exactly matches the shape of `data`, the values of the selected cells are updated based on the values in `data`.
Insert imagesInserted images are floating. The position imageLeft and imageTop parameters are relative to currently selected cell(s). Negative imageLeft and imageTop values are allowed and possibly readjusted by Excel to position the image inside a worksheet. Image aspect ratio is locked unless both imageWidth and imageHeight parameters are provided. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
All other casesAn error is returned.
Excel OnlineIn addition to the behaviors described for Excel above, these limits apply when writing data in Excel OnlineThe total number of cells you can write to a worksheet with the `data` parameter can't exceed 20,000 in a single call to this method.
The number of formatting groups passed to the `cellFormat` parameter can't exceed 100. A single formatting group consists of a set of formatting applied to a specified range of cells.
PowerPointInsert imageInserted images are floating. The position imageLeft and imageTop parameters are optional but if provided, both should be present. If a single value is provided, it will be ignored. Negative imageLeft and imageTop values are allowed and can position an image outside of a slide. If no optional parameter is given and slide has a placeholder, the image will replace the placeholder in the slide. Image aspect ratio will be locked unless both imageWidth and imageHeight parameters are provided. If only one of the imageWidth and imageHeight parameter is given, the other value will be automatically scaled to keep the original aspect ratio.
+ * + * The possible values for the {@link Office.CoercionType} parameter vary by the host. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
HostSupported coercionType
Excel, PowerPoint, Project, and Word`Office.CoercionType.Text` (string)
Excel and Word`Office.CoercionType.Matrix` (array of arrays)
Access, Excel, and Word`Office.CoercionType.Table` (TableData object)
Word`Office.CoercionType.Html`
Word`Office.CoercionType.Ooxml` (Office Open XML)
PowerPoint and PowerPoint Online`Office.CoercionType.SlideRange`
Excel, PowerPoint, and Word`Office.CoercionType.XmlSvg`
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
PowerPoint Y Y Y Y
Project Y
Word Y Y Y Y
+ * + * @param data The data to be set. Either a string or {@link Office.CoercionType} value, 2d array or TableData object. + * + * If the value passed for `data` is: + * + * - A string: Plain text or anything that can be coerced to a string will be inserted. + * In Excel, you can also specify data as a valid formula to add that formula to the selected cell. For example, setting data to "=SUM(A1:A5)" + * will total the values in the specified range. However, when you set a formula on the bound cell, after doing so, you can't read the added + * formula (or any pre-existing formula) from the bound cell. If you call the Document.getSelectedDataAsync method on the selected cell to + * read its data, the method can return only the data displayed in the cell (the formula's result). + * + * - An array of arrays ("matrix"): Tabular data without headers will be inserted. For example, to write data to three rows in two columns, + * you can pass an array like this: [["R1C1", "R1C2"], ["R2C1", "R2C2"], ["R3C1", "R3C2"]]. To write a single column of three rows, pass an + * array like this: [["R1C1"], ["R2C1"], ["R3C1"]] + * + * In Excel, you can also specify data as an array of arrays that contains valid formulas to add them to the selected cells. For example if no + * other data will be overwritten, setting data to [["=SUM(A1:A5)","=AVERAGE(A1:A5)"]] will add those two formulas to the selection. Just as + * when setting a formula on a single cell as "text", you can't read the added formulas (or any pre-existing formulas) after they have been + * set - you can only read the formulas' results. + * + * - A TableData object: A table with headers will be inserted. + * In Excel, if you specify formulas in the TableData object you pass for the data parameter, you might not get the results you expect due to + * the "calculated columns" feature of Excel, which automatically duplicates formulas within a column. To work around this when you want to + * write `data` that contains formulas to a selected table, try specifying the data as an array of arrays (instead of a TableData object), and + * specify the coercionType as Microsoft.Office.Matrix or "matrix". + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The AsyncResult.value property always returns undefined because there is no object or data to retrieve. + */ setSelectedDataAsync(data: string | TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get Project field (Ex. ProjectWebAccessURL). @@ -3787,6 +4786,28 @@ declare namespace Office { * */ getProjectFieldAsync(fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get Project field (Ex. ProjectWebAccessURL). + * @param fieldId Project level fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the `fieldValue` property, which represents the value of the specified field. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getProjectFieldAsync(fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get resource field for provided resource Id. (Ex.ResourceName) @@ -3813,6 +4834,29 @@ declare namespace Office { * */ getResourceFieldAsync(resourceId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get resource field for provided resource Id. (Ex.ResourceName) + * @param resourceId Either a string or value of the Resource Id. + * @param fieldId Resource Fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getResourceFieldAsync(resourceId: string, fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected Resource's Id. @@ -3837,6 +4881,27 @@ declare namespace Office { * */ getSelectedResourceAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected Resource's Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedResourceAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected Task's Id. @@ -3861,6 +4926,27 @@ declare namespace Office { * */ getSelectedTaskAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected Task's Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedTaskAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the current selected View Type (Ex. Gantt) and View Name. @@ -3887,6 +4973,29 @@ declare namespace Office { * */ getSelectedViewAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the current selected View Type (Ex. Gantt) and View Name. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `viewName` - The name of the view, as a ProjectViewTypes constant. + * `viewType` - The type of view, as the integer value of a ProjectViewTypes constant. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getSelectedViewAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the Task Name, WSS Task Id, and ResourceNames for given taskId. @@ -3915,6 +5024,31 @@ declare namespace Office { * */ getTaskAsync(taskId: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the Task Name, WSS Task Id, and ResourceNames for given taskId. + * @param taskId Either a string or value of the Task Id. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `taskName` - The name of the task. + * `wssTaskId` - The ID of the task in the synchronized SharePoint task list. If the project is not synchronized with a SharePoint task list, the value is 0. + * `resourceNames` - The comma-separated list of the names of resources that are assigned to the task. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskAsync(taskId: string, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get task field for provided task Id. (Ex. StartDate). @@ -3941,6 +5075,29 @@ declare namespace Office { * */ getTaskFieldAsync(taskId: string, fieldId: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get task field for provided task Id. (Ex. StartDate). + * @param taskId Either a string or value of the Task Id. + * @param fieldId Task Fields. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the `fieldValue` property, which represents the value of the specified field. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskFieldAsync(taskId: string, fieldId: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. @@ -3967,6 +5124,29 @@ declare namespace Office { * */ getWSSUrlAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the WSS Url and list name for the Tasks List, the MPP is synced too. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result contains the following properties: + * `listName` - the name of the synchronized SharePoint task list. + * `serverUrl` - the URL of the synchronized SharePoint task list. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getWSSUrlAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the maximum index of the collection of resources in the current project. @@ -3994,6 +5174,30 @@ declare namespace Office { * */ getMaxResourceIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the maximum index of the collection of resources in the current project. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the highest index number in the current project's resource collection. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getMaxResourceIndexAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the maximum index of the collection of tasks in the current project. @@ -4021,6 +5225,30 @@ declare namespace Office { * */ getMaxTaskIndexAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the maximum index of the collection of tasks in the current project. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the highest index number in the current project's task collection. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getMaxTaskIndexAsync(callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the GUID of the resource that has the specified index in the resource collection. @@ -4049,6 +5277,31 @@ declare namespace Office { * */ getResourceByIndexAsync(resourceIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the GUID of the resource that has the specified index in the resource collection. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param resourceIndex The index of the resource in the collection of resources for the project. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the resource as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getResourceByIndexAsync(resourceIndex: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Get the GUID of the task that has the specified index in the task collection. @@ -4077,6 +5330,31 @@ declare namespace Office { * */ getTaskByIndexAsync(taskIndex: number, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Get the GUID of the task that has the specified index in the task collection. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param taskIndex The index of the task in the collection of tasks for the project. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is the GUID of the task as a string. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ getTaskByIndexAsync(taskIndex: number, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Set resource field for specified resource Id. @@ -4106,6 +5384,32 @@ declare namespace Office { * */ setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Set resource field for specified resource Id. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param resourceId Either a string or value of the Resource Id. + * @param fieldId Resource Fields. + * @param fieldValue Value of the target field. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ setResourceFieldAsync(resourceId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult) => void): void; /** * Project documents only. Set task field for specified task Id. @@ -4135,6 +5439,32 @@ declare namespace Office { * */ setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Project documents only. Set task field for specified task Id. + * + * Important: This API works only in Project 2016 on Windows desktop. + * + * @param taskId Either a string or value of the Task Id. + * @param fieldId Task Fields. + * @param fieldValue Value of the target field. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * @remarks + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser)
Project Y
+ */ setTaskFieldAsync(taskId: string, fieldId: number, fieldValue: string | number | boolean | object, callback?: (result: AsyncResult) => void): void; } /** @@ -4386,6 +5716,61 @@ declare namespace Office { * */ addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds an event handler for the settingsChanged event. + * + * Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but + * the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel Online, and more than one user is editing the + * spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios. + * + * @remarks + * + *
Requirement SetsSettings
+ * + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * + * @param eventType Specifies the type of event to add. Required. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.SettingsChangedEventArgs}. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no data or object to retrieve when adding an event handler.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y
+ */ addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult) => void): void; /** * Retrieves the specified setting. @@ -4542,6 +5927,40 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult) => void): void; + /** + * Removes an event handler for the settingsChanged event. + * + * @remarks + * + *
Requirement SetsSettings
+ * + * If the optional handler parameter is omitted when calling the removeHandlerAsync method, all event handlers for the specified eventType + * will be removed. + * + * When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback + * function's only parameter. + * + * In the callback function passed to the removeHandlerAsync method, you can use the properties of the AsyncResult object to return the + * following information. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y
+ * + * @param eventType Specifies the type of event to remove. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult) => void): void; /** * Persists the in-memory copy of the settings property bag in the document. @@ -4600,6 +6019,61 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult) => void): void; + /** + * Persists the in-memory copy of the settings property bag in the document. + * + * @remarks + * Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use the + * set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they are + * available the next time the add-in is used, use the saveAsync method. + * + * Note: The saveAsync method persists the in-memory settings property bag into the document file. However, the changes to the document file + * itself are saved only when the user (or AutoRecover setting) saves the document to the file system. The refreshAsync method is only useful + * in coauthoring scenarios when other instances of the same add-in might change the settings and those changes should be made available to + * all instances. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no object or data to retrieve.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
PowerPoint Y Y Y Y
Word Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ saveAsync(callback?: (result: AsyncResult) => void): void; /** * Sets or creates the specified setting. @@ -4861,6 +6335,47 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addColumnsAsync(tableData: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds the specified data to the table as additional columns. + * + * @remarks + * + * To add one or more columns specifying the values of the data and headers, pass a TableData object as the data parameter. To add one or more + * columns specifying only the data, pass an array of arrays ("matrix") as the data parameter. + * + * The success or failure of an addColumnsAsync operation is atomic. That is, the entire add columns operation must succeed, or it will be + * completely rolled back (and the AsyncResult.status property returned to the callback will report failure): + * + * - Each row in the array you pass as the data argument must have the same number of rows as the table being updated. If not, the entire + * operation will fail. + * + * - Each row and cell in the array must successfully add that row or cell to the table in the newly added column(s). If any row or cell + * fails to be set for any reason, the entire operation will fail. + * + * - If you pass a TableData object as the data argument, the number of header rows must match that of the table being updated. + * + * Additional remark for Excel Online: The total number of cells in the TableData object passed to the data parameter can't exceed 20,000 in + * a single call to this method. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param tableData An array of arrays ("matrix") or a TableData object that contains one or more columns of data to add to the table. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addColumnsAsync(tableData: TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Adds the specified data to the table as additional rows. @@ -4902,6 +6417,44 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ addRowsAsync(rows: TableData | any[][], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Adds the specified data to the table as additional rows. + * + * @remarks + * + * The success or failure of an addRowsAsync operation is atomic. That is, the entire add columns operation must succeed, or it will be + * completely rolled back (and the AsyncResult.status property returned to the callback will report failure): + * + * - Each row in the array you pass as the data argument must have the same number of columns as the table being updated. If not, the entire + * operation will fail. + * + * - Each column and cell in the array must successfully add that column or cell to the table in the newly added rows(s). If any column or + * cell fails to be set for any reason, the entire operation will fail. + * + * - If you pass a TableData object as the data argument, the number of header rows must match that of the table being updated. + * + * Additional remark for Excel Online: The total number of cells in the TableData object passed to the data parameter can't exceed 20,000 in + * a single call to this method. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param rows An array of arrays ("matrix") or a TableData object that contains one or more rows of data to add to the table. Required. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ addRowsAsync(rows: TableData | any[][], callback?: (result: AsyncResult) => void): void; /** * Deletes all non-header rows and their values in the table, shifting appropriately for the host application. @@ -4930,6 +6483,31 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ deleteAllDataValuesAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Deletes all non-header rows and their values in the table, shifting appropriately for the host application. + * + * @remarks + * + * In Excel, if the table has no header row, this method will delete the table itself. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Access Y
Excel Y Y Y Y
Word Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ deleteAllDataValuesAsync(callback?: (result: AsyncResult) => void): void; /** * Clears formatting on the bound table. @@ -4955,6 +6533,28 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ clearFormatsAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Clears formatting on the bound table. + * + * @remarks + * See {@link https://docs.microsoft.com/office/dev/add-ins/excel/excel-add-ins-tables#format-a-table | Format tables in add-ins for Excel} for more information. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ clearFormatsAsync(callback?: (result: AsyncResult) => void): void; /** * Gets the formatting on specified items in the table. @@ -5010,6 +6610,58 @@ declare namespace Office { * The `value` property of the result is an array containing one or more JavaScript objects specifying the formatting of their corresponding cells. */ getFormatsAsync(cellReference?: any, formats?: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult< ({ cells: any, format: any})[]>) => void): void; + /** + * Gets the formatting on specified items in the table. + * + * @remarks + * + * **Returned format structure** + * + * Each JavaScript object in the return value array has this form: `{cells:{ cell_range }, format:{ format_definition }}` + * + * The `cells:` property specifies the range you want format using one of the following values: + * + * **Supported ranges in cells property** + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
cells range settingsDescription
`{row: n}`Specifies the range that is the zero-based nth row of data in the table.
`{column: n}`Specifies the range that is the zero-based nth column of data in the table.
`{row: i, column: j}`Specifies the single cell that is the ith row and jth column of the table.
`Office.Table.All`Specifies the entire table, including column headers, data, and totals (if any).
`Office.Table.Data`Specifies only the data in the table (no headers and totals).
`Office.Table.Headers`Specifies only the header row.
+ * + * The `format:` property specifies values that correspond to a subset of the settings available in the Format Cells dialog box in Excel + * (Right-click \> Format Cells or Home \> Format \> Format Cells). + * + * @param cellReference An object literal containing name-value pairs that specify the range of cells to get formatting from. + * @param formats An array specifying the format properties to get. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * The `value` property of the result is an array containing one or more JavaScript objects specifying the formatting of their corresponding cells. + */ getFormatsAsync(cellReference?: any, formats?: any[], callback?: (result: AsyncResult< ({ cells: any, format: any})[]>) => void): void; /** * Sets formatting on specified items and data in the table. @@ -5124,6 +6776,117 @@ declare namespace Office { * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. */ setFormatsAsync(cellFormat: any[], options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Sets formatting on specified items and data in the table. + * + * @remarks + * + * **Specifying the cellFormat parameter** + * + * Use the cellFormat parameter to set or change cell formatting values, such as width, height, font, background, alignment, and so on. + * The value you pass as the cellFormat parameter is an array that contains a list of one or more JavaScript objects that specify which cells + * to target (`cells:`) and the formats (`format:`) to apply to them. + * + * Each JavaScript object in the cellFormat array has this form: `{cells:{ cell_range }, format:{ format_definition }}` + * + * The `cells:` property specifies the range you want format using one of the following values: + * + * **Supported ranges in cells property** + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
cells range settingsDescription
`{row: n}`Specifies the range that is the zero-based nth row of data in the table.
`{column: n}`Specifies the range that is the zero-based nth column of data in the table.
`{row: i, column: j}`Specifies the single cell that is the ith row and jth column of the table.
`Office.Table.All`Specifies the entire table, including column headers, data, and totals (if any).
`Office.Table.Data`Specifies only the data in the table (no headers and totals).
`Office.Table.Headers`Specifies only the header row.
+ * + * The `format:` property specifies values that correspond to a subset of the settings available in the Format Cells dialog box in Excel + * (Right-click \> Format Cells or Home \> Format \> Format Cells). + * + * You specify the value of the `format:` property as a list of one or more property name - value pairs in a JavaScript object literal. The + * property name specifies the name of the formatting property to set, and value specifies the property value. + * You can specify multiple values for a given format, such as both a font's color and size. + * + * Here's three `format:` property value examples: + * + * `//Set cells: font color to green and size to 15 points.` + * + * `format: {fontColor : "green", fontSize : 15}` + * + * `//Set cells: border to dotted blue.` + * + * `format: {borderStyle: "dotted", borderColor: "blue"}` + * + * `//Set cells: background to red and alignment to centered.` + * + * `format: {backgroundColor: "red", alignHorizontal: "center"}` + * + * + * You can specify number formats by specifying the number formatting "code" string in the `numberFormat:` property. + * The number format strings you can specify correspond to those you can set in Excel using the Custom category on the Number tab of the Format Cells dialog box. + * This example shows how to format a number as a percentage with two decimal places: + * + * `format: {numberFormat:"0.00%"}` + * + * For more detail, see how to {@link https://support.office.com/article/create-or-delete-a-custom-number-format-78f2a361-936b-4c03-8772-09fab54be7f4 | Create a custom number format}. + * + * To set formatting on tables when writing data, use the tableOptions and cellFormat optional parameters of the + * `Document.setSelectedDataAsync` or `TableBinding.setDataAsync` methods. + * + * Setting formatting with the optional parameters of the `Document.setSelectedDataAsync` and `TableBinding.setDataAsync` methods only works + * to set formatting when writing data the first time. + * To make formatting changes after writing data, use the following methods: + * + * - To update cell formatting, such as font color and style, use the `TableBinding.setFormatsAsync` method (this method). + * + * - To update table options, such as banded rows and filter buttons, use the `TableBinding.setTableOptions` method. + * + * - To clear formatting, use the `TableBinding.clearFormats` method. + * + * For more details and examples, see + * {@link https://docs.microsoft.com/office/dev/add-ins/excel/excel-add-ins-tables#format-a-table | How to format tables in add-ins for Excel}. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param cellFormat An array that contains one or more JavaScript objects that specify which cells to target and the formatting to apply to them. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + */ setFormatsAsync(cellFormat: any[], callback?: (result: AsyncResult) => void): void; /** * Updates table formatting options on the bound table. @@ -5178,6 +6941,57 @@ declare namespace Office { * */ setTableOptionsAsync(tableOptions: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult) => void): void; + /** + * Updates table formatting options on the bound table. + * + * @remarks + * + * + *
HostsExcel
Requirement SetsNot in a set
+ * + * In the callback function passed to the goToByIdAsync method, you can use the properties of the AsyncResult object to return the following information. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyUse to...
AsyncResult.valueAlways returns undefined because there is no data or object to retrieve when setting formats.
AsyncResult.statusDetermine the success or failure of the operation.
AsyncResult.errorAccess an Error object that provides error information if the operation failed.
AsyncResult.asyncContextA user-defined item of any type that is returned in the AsyncResult object without being altered.
+ * + * **Support details** + * + * A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this method. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad Office for Mac
Excel Y Y Y Y
+ * + * @param tableOptions An object literal containing a list of property name-value pairs that define the table options to apply. + * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. + * + */ setTableOptionsAsync(tableOptions: any, callback?: (result: AsyncResult) => void): void; } /** From 55de8ef502ce62a3f26342209b720a17d179abe7 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Fri, 1 Feb 2019 12:14:35 -0800 Subject: [PATCH 2/2] FIxing spacing --- types/office-js-preview/index.d.ts | 4 ++-- types/office-js/index.d.ts | 26 ++++++++++++++------------ 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index 34ab184434..1424875097 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -5169,7 +5169,7 @@ declare namespace Office { * * *Supported hosts, by platform* * - * + * * *
Office for Windows desktop Office Online (in browser)
Office for Windows desktop Office Online (in browser)
Project Y
*/ @@ -5194,7 +5194,7 @@ declare namespace Office { * * *Supported hosts, by platform* * - * + * * *
Office for Windows desktop Office Online (in browser)
Office for Windows desktop Office Online (in browser)
Project Y
*/ diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index bea8c12db6..8f4d4c6035 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -5169,7 +5169,7 @@ declare namespace Office { * * *Supported hosts, by platform* * - * + * * *
Office for Windows desktop Office Online (in browser)
Office for Windows desktop Office Online (in browser)
Project Y
*/ @@ -5194,7 +5194,7 @@ declare namespace Office { * * *Supported hosts, by platform* * - * + * * *
Office for Windows desktop Office Online (in browser)
Office for Windows desktop Office Online (in browser)
Project Y
*/ @@ -20439,20 +20439,22 @@ declare namespace Excel { /** * Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties. * - * @remarks - * - * In addition to this signature, this method has the following signatures: - * - * `load(option?: string | string[]): Excel.Application` - Where option is a comma-delimited string or an array of strings that specify the properties to load. - * - * `load(option?: { select?: string; expand?: string; }): Excel.Application` - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load. - * - * `load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.Application` - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items. - * * @param options Provides options for which properties of the object to load. */ load(option?: Excel.Interfaces.ApplicationLoadOptions): Excel.Application; + /** + * Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties. + * + * @param options The names of the properties to load. + */ load(option?: string | string[]): Excel.Application; + /** + * Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties. + * + * @param options Provides options for which properties of the object to load. + * `option.select` is a comma-delimited string that specifies the properties to load, + * and `options.expand` is a comma-delimited string that specifies the navigation properties to load. + */ load(option?: { select?: string; expand?: string;