From 6a825c9425430a2c80c92c132ad4edb354b17940 Mon Sep 17 00:00:00 2001 From: Alex Jerabek Date: Thu, 17 May 2018 15:20:53 -0700 Subject: [PATCH] first pass porting old docs text --- types/office-js/index.d.ts | 230 ++++++++++++++++++++++++++++++------- 1 file changed, 188 insertions(+), 42 deletions(-) diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index cee60e05fc..0ff10134b5 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -20,6 +20,9 @@ declare namespace Office { } export var Promise: PromiseConstructor; + /** + * Gets the Context object that represents the runtime environment of the add-in and provides access to the top-level objects of the API. + */ export var context: Context; /** * This method is called after the Office API was loaded. @@ -149,7 +152,9 @@ declare namespace Office { /** * Provides specific information about an error that occurred during an asynchronous data operation. * - * Remarks: The Error object is accessed from the AsyncResult object that is returned in the function passed as the callback argument of an asynchronous data operation, such as the setSelectedDataAsync method of the Document object. + * @remarks + * The Error object is accessed from the AsyncResult object that is returned in the function passed as the callback argument of an asynchronous data operation, such as the setSelectedDataAsync method of the Document object. + * Hosts: Access, Excel, Outlook, PowerPoint, Project, Word */ export interface Error { /** @@ -165,6 +170,9 @@ declare namespace Office { */ name: string; } + /** + * Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins. + */ export interface UI { /** * Displays a dialog to show or collect information from the user or to facilitate Web navigation. @@ -190,24 +198,18 @@ declare namespace Office { * @param callback Optional. Accepts a callback method to handle the dialog creation attempt. */ displayDialogAsync(startAddress: string, options: DialogOptions, callback: (result: AsyncResult) => void): void; - /** - * Synchronously delivers a message from the dialog to its parent add-in. + * 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. * @param messageObject Accepts a message from the dialog to deliver to the add-in. */ messageParent(messageObject: any): void; /** * Closes the UI container where the JavaScript is executing. - * - * Supported hosts: Outlook - Minimum requirement set: Mailbox 1.5 - * * The behavior of this method is specified by the following: - * - * Called from a UI-less command button: No effect. Any dialog opened by displayDialogAsync will remain open. - * - * Called from a taskpane: The taskpane will close. Any dialog opened by displayDialogAsync will also close. If the taskpane supports pinning and was pinned by the user, it will be un-pinned. - * - * Called from a module extension: No effect. + * - Called from a UI-less command button: No effect. Any dialog opened by displayDialogAsync will remain open. + * - Called from a taskpane: The taskpane will close. Any dialog opened by displayDialogAsync will also close. If the taskpane supports pinning and was pinned by the user, it will be un-pinned. + * - Called from a module extension: No effect. + * Hosts: Outlook - Minimum requirement set: Mailbox 1.5 */ closeContainer(): void; } @@ -826,18 +828,55 @@ declare namespace Office { */ type: EventType; } + /** + * Represents the document file associated with an Office Add-in. + * + * @remarks + * Access the File object with the AsyncResult.value property in the callback function passed to the Document.getFileAsync method. + * Hosts: PowerPoint, Word + */ export interface File { + /** + * Gets the document file size in bytes. + * @remarks + * Hosts: PowerPoint, Word + */ size: number; + /** + * Gets the number of slices into which the file is divided. + * @remarks + * Hosts: PowerPoint, Word + */ sliceCount: number; /** - * Closes the File. - * @param callback The optional callback method + * Closes the document file. + * No more than two documents are allowed to be in memory; otherwise the Document.getFileAsync operation will fail. Use the File.closeAsync method to close the file when you are finished working with it. + * Hosts: PowerPoint, Word + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. Optional. + * @remarks + * 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 closeAsync method, you can use the properties of the AsyncResult object to return the following information. + * Property - Use to... + * AsyncResult.value - Always returns undefined because there is no object or data to retrieve. + * AsyncResult.status - Determine the success or failure of the operation. + * AsyncResult.error - Access an Error object that provides error information if the operation failed. + * AsyncResult.asyncContext - Access your user-defined object or value, if you passed one as the asyncContext parameter. */ closeAsync(callback?: (result: AsyncResult) => void): void; /** - * Gets the specified slice. - * @param sliceIndex The index of the slice to be retrieved - * @param callback The optional callback method + * Returns the specified slice. + * @remarks + * Hosts: PowerPoint, Word + * @param sliceIndex Specifies the zero-based index of the slice to be retrieved. Required. + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. Optional. + * @remarks + * 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 getSliceAsync method, you can use the properties of the AsyncResult object to return the following information. + * Property - Use to... + * AsyncResult.value - Access the Slice object. + * AsyncResult.status - Determine the success or failure of the operation. + * AsyncResult.error - Access an Error object that provides error information if the operation failed. + * AsyncResult.asyncContext - Access your user-defined object or value, if you passed one as the asyncContext parameter. */ getSliceAsync(sliceIndex: number, callback?: (result: AsyncResult) => void): void; } @@ -851,58 +890,143 @@ declare namespace Office { columnCount: number; rowCount: number; } + /** + * Represents custom settings for a task pane or content add-in that are stored in the host document as name/value pairs. + * + * @remarks + * The settings created by using the methods of the Settings object are saved per add-in and per document. That is, they are available only to the add-in that created them, and only from the document in which they are saved. + * The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array. + * The Settings object is automatically loaded as part of the Document object, and is available by calling the settings property of that object when the add-in is activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the document. + * Hosts: Access, Excel, PowerPoint, Word + */ export interface Settings { /** - * Adds an event handler for the object using the specified event type. - * @param eventType The event type. For settings can be 'settingsChanged' - * @param handler The name of the handler - * @param options Syntax example: {asyncContext:context} - * asyncContext: Object keeping state for the callback - * @param callback The optional callback method + * Adds an event handler for the settingsChanged event. + * @remarks + * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. + * 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. + * Hosts: Excel + * @param eventType Specifies the type of event to add. Required. + * @param handler The event handler function to add. Required. + * @param options Specifies any of the following optional parameters. + * @param asyncContext: A user-defined item of any type that is returned in the AsyncResult object without being altered. + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. + * @remarks + * 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 addHandlerAsync method, you can use the properties of the AsyncResult object to return the following information. + * Property - Use to... + * AsyncResult.value - Always returns undefined because there is no data or object to retrieve when adding an event handler. + * AsyncResult.status - Determine the success or failure of the operation. + * AsyncResult.error - Access an Error object that provides error information if the operation failed. + * AsyncResult.asyncContext - Access your user-defined object or value, if you passed one as the asyncContext parameter. */ addHandlerAsync(eventType: EventType, handler: any, options?: any, callback?: (result: AsyncResult) => void): void; /** - * Retrieves the setting with the specified name. - * @param settingName The name of the setting + * Retrieves the specified setting. + * @remarks + * Hosts: Access, Excel, PowerPoint, Word + * @param settingName The case-sensitive name of the setting to retrieve. + * @returns An object that has property names mapped to JSON serialized values. */ get(name: string): any; /** - * Gets the latest version of the settings object. - * @param callback The optional callback method + * Reads all settings persisted in the document and refreshes the content or task pane add-in's copy of those settings held in memory. + * @remarks + * This method is useful in Word and PowerPoint coauthoring scenarios when multiple instances of the same add-in are working against the same document. Because each add-in is working against an in-memory copy of the settings loaded from the document at the time the user opened it, the settings values used by each user can get out of sync. This can happen whenever an instance of the add-in calls the Settings.saveAsync method to persist all of that user's settings to the document. Calling the refreshAsync method from the event handler for the settingsChanged event of the add-in will refresh the settings values for all users. + * The refreshAsync method can be called from add-ins created for Excel, but since it doesn't support coauthoring there is no reason to do so. + * Hosts: Access, Excel, PowerPoint, Word + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. + * @remarks + * 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 refreshAsync method, you can use the properties of the AsyncResult object to return the following information. + * Property - Use to... + * AsyncResult.value - Access a Settings object with the refreshed values. + * AsyncResult.status - Determine the success or failure of the operation. + * AsyncResult.error - Access an Error object that provides error information if the operation failed. + * AsyncResult.asyncContext - Access your user-defined object or value, if you passed one as the asyncContext parameter. */ refreshAsync(callback?: (result: AsyncResult) => void): void; /** - * Removes the setting with the specified name. - * @param settingName The name of the setting + * Removes the specified setting. + * @remarks + * null is a valid value for a setting. Therefore, assigning null to the setting will not remove it from the settings property bag. + * Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method. + * Hosts: Access, Excel, PowerPoint, Word + * @param settingName The case-sensitive name of the setting to remove. */ remove(name: string): void; /** - * Removes an event handler for the specified event type. - * @param eventType The event type. For settings can be 'settingsChanged' - * @param options Syntax example: {handler:eventHandler} - * handler: Indicates a specific handler to be removed, if not specified all handlers are removed - * asyncContext: Object keeping state for the callback - * @param callback The optional callback method + * Removes an event handler for the settingsChanged event. + * @remarks + * If the optional handler parameter is omitted when calling the removeHandlerAsync method, all event handlers for the specified eventType will be removed. + * Hosts: Access, Excel, PowerPoint + * @param eventType Specifies the type of event to remove. Required. + * @param options Specifies any of the following optional parameters. + * @param handler: Specifies the name of the handler to remove. + * @param asyncContext: A user-defined item of any type that is returned in the AsyncResult object without being altered. + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. + * @remarks + * 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. */ removeHandlerAsync(eventType: EventType, options?: any, callback?: (result: AsyncResult) => void): void; /** - * Saves all settings. + * 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 (which are only supported in Word) when other instances of the same add-in might change the settings and those changes should be made available to all instances. + * Hosts: Access, Excel, PowerPoint, Word * @param options Syntax example: {overwriteIfStale:false} - * overwriteIfStale: Indicates whether the setting will be replaced if stale. - * asyncContext: Object keeping state for the callback - * @param callback The optional callback method + * @param overwriteIfStale: Indicates whether the setting will be replaced if stale. + * @param asyncContext: Object keeping state for the callback + * @param callback A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. Optional. + * @remarks + * 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 saveAsync method, you can use the properties of the AsyncResult object to return the following information. + * Property - Use to... + * AsyncResult.value - Always returns undefined because there is no object or data to retrieve. + * AsyncResult.status - Determine the success or failure of the operation. + * AsyncResult.error - Access an Error object that provides error information if the operation failed. + * AsyncResult.asyncContext - Access your user-defined object or value, if you passed one as the asyncContext parameter. */ saveAsync(callback?: (result: AsyncResult) => void): void; /** - * Sets a value for the setting with the specified name. - * @param settingName The name of the setting - * @param value The value for the setting + * Sets or creates the specified setting. + * @remarks + * The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name in the in-memory copy of the settings property bag. After you call the Settings.saveAsync method, the value is stored in the document as the serialized JSON representation of its data type. A maximum of 2MB is available for the settings of each add-in. + * Important: Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document. + * Hosts: Access, Excel, PowerPoint, Word + * @param settingName The case-sensitive name of the setting to set or create. + * @param value Specifies the value to be stored. */ set(name: string, value: any): void; } + /** + * Represents a slice of a document file. + * @remarks + * The Slice object is accessed with the File.getSliceAsync method. + * Hosts: PowerPoint, Word + */ export interface Slice { + /** + * Gets the raw data of the file slice in Office.FileType.Text ("text") or Office.FileType.Compressed ("compressed") format as specified by the fileType parameter of the call to the Document.getFileAsync method. + * @remarks + * Files in the "compressed" format will return a byte array that can be transformed to a base64-encoded string if required. + * Hosts: PowerPoint, Word + */ data: any; + /** + * Gets the zero-based index of the file slice. + * @remarks + * Hosts: PowerPoint, Word + */ index: number; + /** + * Gets the size of the slice in bytes. + * @remarks + * Hosts: PowerPoint, Word + */ size: number; } export interface TableBinding extends Binding { @@ -968,10 +1092,32 @@ declare namespace Office { */ setTableOptionsAsync(tableOptions: any, options?: any, callback?: (result: AsyncResult) => void): void; } + /** + * Represents the data in a table or a TableBinding. + * @remarks + * Hosts: Excel, Word + */ export class TableData { constructor(rows: any[][], headers: any[]); constructor(); + /** + * Gets or sets the headers of the table. + * @remarks + * To specify headers, you must specify an array of arrays that corresponds to the structure of the table. For example, to specify headers for a two-column table you would set the header property to [['header1', 'header2']]. + * If you specify null for the headers property (or leaving the property empty when you construct a TableData object), the following results occur when your code executes: + * - If you insert a new table, the default column headers for the table are created. + * - If you overwrite or update an existing table, the existing headers are not altered. + * Hosts: Excel, Word + */ headers: any[]; + /** + * Gets or sets the rows in the table. Returns an array of arrays that contains the data in the table. Returns an empty array ``, if there are no rows. + * To specify rows, you must specify an array of arrays that corresponds to the structure of the table. For example, to specify two rows of string values in a two-column table you would set the rows property to [['a', 'b'], ['c', 'd']]. + * If you specify null for the rows property (or leave the property empty when you construct a TableData object), the following results occur when your code executes: + * - If you insert a new table, a blank row will be inserted. + * - If you overwrite or update an existing table, the existing rows are not altered. + * Hosts: Excel, Word + */ rows: any[][]; } export enum Table {