diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index b22cb5246e..a262cf8755 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -325,7 +325,47 @@ declare namespace Office { * @param useShortNamespace True to use the shortcut alias; otherwise false to disable it. The default is true. */ function useShortNamespace(useShortNamespace: boolean): void; + /** + * Represents the add-in. + */ + const addin: Addin; + /** + * Represents the ribbon associated with the Office application. + */ + const ribbon: Ribbon; + /** + * Checks if the specified requirement set is supported by the host Office application. + * @param name - Set name; e.g., "MatrixBindings". + * @param minVersion - The minimum required version; e.g., "1.4". + */ + function isSetSupported(name: string, minVersion?: string): boolean; // Enumerations + /** + * Provides options to determine the startup behavior of the add-in upon next start-up. + */ + enum StartupBehavior { + /** + * The add-in does not load until opened by the user. + */ + none = 'None', + /** + * Load the add-in but do not show UI. + */ + load = 'Load', + } + /** + * Visibility mode of the add-in. + */ + enum VisibilityMode { + /** + * UI is Hidden + */ + hidden = 'Hidden', + /** + * Displayed as taskpane + */ + taskpane = 'Taskpane', + } /** * Specifies the result of an asynchronous call. * @@ -476,6 +516,114 @@ declare namespace Office { */ value: T; } + /** + * Message used in the `onVisibilityModeChanged` invocation. + */ + interface VisibilityModeChangedMessage { + /** + * Visibility changed state. + */ + visibilityMode: Office.VisibilityMode; + } + /** + * Function type to turn off the event. + */ + type RemoveEventListener = () => Promise; + /** + * Represents add-in level functionality for operating or configuring various aspects of the add-in. + */ + interface Addin { + /** + * Set the startup behavior for the add-in for when the document is opened next time. + * @param - behavior Specifies startup behavior of the add-in. + */ + setStartupBehavior(behavior: Office.StartupBehavior): Promise; + /** + * Get the current startup behavior for the add-in. + */ + getStartupBehavior(): Promise; + /** + * Shows the task pane associated with the add-in. + * @returns A promise that is resolved when the UI is shown. + */ + showAsTaskpane(): Promise; + /** + * Hides the task pane. + * @returns A promise that is resolved when the UI is hidden. + */ + hide(): Promise; + /** + * Adds a listener for the `onVisbilityModeChanged` event. + * @param listener - The listener function that is called when the event is emitted. This function takes in a message for the receiving component. + * @returns A promise that resolves when the listener is added. + */ + onVisibilityModeChanged( + listener: (message: VisibilityModeChangedMessage) => void, + ): Promise; + } + /** + * An interface that contains all the functionality provided to manage the state of the OFfice ribbon. + */ + interface Ribbon { + /** + * Sends a request to Office to update the ribbon. + * Note that this API is only to request an update. The actual UI update to the ribbon is controlled by the Office application and hence the exact timing of the ribbon update (or refresh) cannot be determined by the completion of this API. + * @param input - Represents the updates to be made to the ribbon. Note that only the changes specified in the input parameter are made. + */ + requestUpdate(input: RibbonUpdaterData): Promise; + } + /** + * Specifies changes to the ribbon, such as the enabled or disabled status of a button. + */ + interface RibbonUpdaterData { + /** + * Collection of tabs whose state is set with the call of `requestUpdate`. + */ + tabs: Tab[]; + } + /** + * Represents an individual tab and the state it should have. + */ + interface Tab { + /** + * Identifier of the tab as specified in the manifest. + */ + id: string; + /** + * Specifies whether the tab is visible. The default is true. + */ + visible?: boolean; + /** + * Specifies the controls in the tab, such as menu items, buttons, etc. + */ + controls?: Control[]; + } + /** + * Represents an individual control or command and the state it should have. + */ + interface Control { + /** + * Identifier of the control as specified in the manifest. + */ + id: string; + /** + * Indicates whether the control should be visible or hidden. The default is true. + */ + visible?: boolean; + /** + * Indicates whether the control should be enabled or disabled. The default is true. + */ + enabled?: boolean; + } + /** + * Represents a gallery that displays a collection of related items or controls in the ribbon. + */ + interface Gallery extends Control { + /** + * Used to refresh the gallery control including optional data to be passed to the gallery control at the time of refresh action. + */ + refreshData?: { [key: string]: string | null }; + } /** * Represents the runtime environment of the add-in and provides access to key objects of the API. * The current context exists as a property of Office. It is accessed using `Office.context`. @@ -14254,7 +14402,7 @@ declare namespace Office { * **{@link https://docs.microsoft.com/outlook/add-ins/understanding-outlook-add-in-permissions | Minimum permission level}**: ReadItem * * **{@link https://docs.microsoft.com/outlook/add-ins/#extension-points | Applicable Outlook mode}**: Message Read - + * The itemClass property specifies the message class of the selected item. * The following are the default message classes for the message or appointment item. * diff --git a/types/office-js-preview/office-js-preview-tests.ts b/types/office-js-preview/office-js-preview-tests.ts index 53d242967c..73984164a0 100644 --- a/types/office-js-preview/office-js-preview-tests.ts +++ b/types/office-js-preview/office-js-preview-tests.ts @@ -7,314 +7,328 @@ Copyright (c) Microsoft Corporation function test_excel() { - // Range - Excel.run(function (ctx) { - var range = ctx.workbook.getSelectedRange().load("values"); - return ctx.sync() - .then(function () { - var vals = range.values; - for (var i = 0; i < vals.length; i += 1) { - for (var j = 0; j < vals[i].length; j += 1) { - vals[i][j] = vals[i][j].toUpperCase(); - } - } - range.values = vals; - }) - .then(ctx.sync); - }).catch(function (error) { - console.log(error); - }); + // Range + Excel.run(function (ctx) { + var range = ctx.workbook.getSelectedRange().load("values"); + return ctx.sync() + .then(function () { + var vals = range.values; + for (var i = 0; i < vals.length; i += 1) { + for (var j = 0; j < vals[i].length; j += 1) { + vals[i][j] = vals[i][j].toUpperCase(); + } + } + range.values = vals; + }) + .then(ctx.sync); + }).catch(function (error) { + console.log(error); + }); - // Chart - Excel.run(function (ctx) { - var sheet = ctx.workbook.worksheets.getItem("Sheet1"); + // Chart + Excel.run(function (ctx) { + var sheet = ctx.workbook.worksheets.getItem("Sheet1"); - var range = sheet.getRange("A1:B3"); - range.values = [ - ["", "Gender"], - ["Male", 12], - ["Female", 14] - ]; + var range = sheet.getRange("A1:B3"); + range.values = [ + ["", "Gender"], + ["Male", 12], + ["Female", 14] + ]; - var chart = sheet.charts.add(Excel.ChartType._3DColumn, range, "Auto"); + var chart = sheet.charts.add(Excel.ChartType._3DColumn, range, "Auto"); - chart.format.fill.setSolidColor("F8F8FF"); + chart.format.fill.setSolidColor("F8F8FF"); - chart.title.text = "Class Demographics"; - chart.title.format.font.bold = true; - chart.title.format.font.size = 18; - chart.title.format.font.color = "568568"; + chart.title.text = "Class Demographics"; + chart.title.format.font.bold = true; + chart.title.format.font.size = 18; + chart.title.format.font.color = "568568"; - chart.legend.position = "Right"; - chart.legend.format.font.name = "Algerian"; - chart.legend.format.font.size = 13; + chart.legend.position = "Right"; + chart.legend.format.font.name = "Algerian"; + chart.legend.format.font.size = 13; - chart.dataLabels.showPercentage = true; - chart.dataLabels.format.font.size = 15; - chart.dataLabels.format.font.color = "444444"; + chart.dataLabels.showPercentage = true; + chart.dataLabels.format.font.size = 15; + chart.dataLabels.format.font.color = "444444"; - var points = chart.series.getItemAt(0).points; - points.getItemAt(0).format.fill.setSolidColor("8FBC8F"); - points.getItemAt(1).format.fill.setSolidColor("D87093"); + var points = chart.series.getItemAt(0).points; + points.getItemAt(0).format.fill.setSolidColor("8FBC8F"); + points.getItemAt(1).format.fill.setSolidColor("D87093"); - return ctx.sync(); - }).catch(function (error) { - console.log(error); - }); + return ctx.sync(); + }).catch(function (error) { + console.log(error); + }); - // Table - Excel.run(function (ctx) { - var rows = ctx.workbook.tables.getItem("Table1").rows.load("values"); - return ctx.sync() - .then(function () { - var largestRow = 0; - var largestValue = 0; + // Table + Excel.run(function (ctx) { + var rows = ctx.workbook.tables.getItem("Table1").rows.load("values"); + return ctx.sync() + .then(function () { + var largestRow = 0; + var largestValue = 0; - for (var i = 0; i < rows.items.length; i += 1) { - if (rows.items[i].values[0][1] > largestValue) { - largestRow = i; - largestValue = rows.items[i].values[0][1]; - } - } + for (var i = 0; i < rows.items.length; i += 1) { + if (rows.items[i].values[0][1] > largestValue) { + largestRow = i; + largestValue = rows.items[i].values[0][1]; + } + } - var largestRowRng = rows.getItemAt(largestRow).getRange(); - largestRowRng.format.fill.color = "#ff0000"; + var largestRowRng = rows.getItemAt(largestRow).getRange(); + largestRowRng.format.fill.color = "#ff0000"; - }) - .then(ctx.sync); - }).catch(function (error) { - console.log(error); - }); + }) + .then(ctx.sync); + }).catch(function (error) { + console.log(error); + }); - // Object.set - Excel.run(ctx => { - const range = ctx.workbook.getSelectedRange(); - range.set({ - values: [[1]], - format: { - font: { - bold: true - }, - fill: { - color: "red" - } - } - }); + // Object.set + Excel.run(ctx => { + const range = ctx.workbook.getSelectedRange(); + range.set({ + values: [[1]], + format: { + font: { + bold: true + }, + fill: { + color: "red" + } + } + }); - return ctx.sync(); - }).catch(console.log); + return ctx.sync(); + }).catch(console.log); } function test_word() { - // Search - Word.run(function (context) { + // Search + Word.run(function (context) { - // Create a proxy object for the document body. - var body = context.document.body; + // Create a proxy object for the document body. + var body = context.document.body; - // Setup the search options. - var options = Word.SearchOptions.newObject(context); - options.matchCase = false + // Setup the search options. + var options = Word.SearchOptions.newObject(context); + options.matchCase = false - // Queue a commmand to search the document. - var searchResults = context.document.body.search('video', options); + // Queue a commmand to search the document. + var searchResults = context.document.body.search('video', options); - // Queue a commmand to load the results. - context.load(searchResults, 'text, font'); + // Queue a commmand to load the results. + context.load(searchResults, 'text, font'); - // Synchronize the document state by executing the queued-up commands, - // and return a promise to indicate task completion. - return context.sync().then(function () { - var results = 'Found count: ' + searchResults.items.length + - '; we highlighted the results.'; + // Synchronize the document state by executing the queued-up commands, + // and return a promise to indicate task completion. + return context.sync().then(function () { + var results = 'Found count: ' + searchResults.items.length + + '; we highlighted the results.'; - // Queue a command to change the font for each found item. - for (var i = 0; i < searchResults.items.length; i += 1) { - searchResults.items[i].font.color = '#FF0000' // Change color to Red - searchResults.items[i].font.highlightColor = '#FFFF00'; - searchResults.items[i].font.bold = true; - } + // Queue a command to change the font for each found item. + for (var i = 0; i < searchResults.items.length; i += 1) { + searchResults.items[i].font.color = '#FF0000' // Change color to Red + searchResults.items[i].font.highlightColor = '#FFFF00'; + searchResults.items[i].font.bold = true; + } - // Synchronize the document state by executing the queued-up commands, - // and return a promise to indicate task completion. - return context.sync().then(function () { - console.log(results); - }); - }); - }) - .catch(function (error) { - console.log('Error: ' + JSON.stringify(error)); - if (error instanceof OfficeExtension.Error) { - console.log('Debug info: ' + JSON.stringify(error.debugInfo)); - } - }); + // Synchronize the document state by executing the queued-up commands, + // and return a promise to indicate task completion. + return context.sync().then(function () { + console.log(results); + }); + }); + }) + .catch(function (error) { + console.log('Error: ' + JSON.stringify(error)); + if (error instanceof OfficeExtension.Error) { + console.log('Debug info: ' + JSON.stringify(error.debugInfo)); + } + }); - // Content control - Word.run(function (context) { + // Content control + Word.run(function (context) { - // Create a proxy range object for the current selection. - var range = context.document.getSelection(); + // Create a proxy range object for the current selection. + var range = context.document.getSelection(); - // Queue a commmand to create the content control. - var myContentControl = range.insertContentControl(); - myContentControl.tag = 'Customer-Address'; - myContentControl.title = 'Enter Customer Address Here:'; - myContentControl.style = 'Heading 2'; - myContentControl.insertText('One Microsoft Way, Redmond, WA 98052', 'Replace'); - myContentControl.cannotEdit = true; - myContentControl.appearance = 'Tags'; + // Queue a commmand to create the content control. + var myContentControl = range.insertContentControl(); + myContentControl.tag = 'Customer-Address'; + myContentControl.title = 'Enter Customer Address Here:'; + myContentControl.style = 'Heading 2'; + myContentControl.insertText('One Microsoft Way, Redmond, WA 98052', 'Replace'); + myContentControl.cannotEdit = true; + myContentControl.appearance = 'Tags'; - // Queue a command to load the id property for the content control you created. - context.load(myContentControl, 'id'); + // Queue a command to load the id property for the content control you created. + context.load(myContentControl, 'id'); - // Synchronize the document state by executing the queued-up commands, - // and return a promise to indicate task completion. - return context.sync().then(function () { - console.log('Created content control with id: ' + myContentControl.id); - }); - }) - .catch(function (error) { - console.log('Error: ' + JSON.stringify(error)); - if (error instanceof OfficeExtension.Error) { - console.log('Debug info: ' + JSON.stringify(error.debugInfo)); - } - }); + // Synchronize the document state by executing the queued-up commands, + // and return a promise to indicate task completion. + return context.sync().then(function () { + console.log('Created content control with id: ' + myContentControl.id); + }); + }) + .catch(function (error) { + console.log('Error: ' + JSON.stringify(error)); + if (error instanceof OfficeExtension.Error) { + console.log('Debug info: ' + JSON.stringify(error.debugInfo)); + } + }); - // Body.insertInlinePictureFromBase64 Word 1.1 - Word.run(function (context) { + // Body.insertInlinePictureFromBase64 Word 1.1 + Word.run(function (context) { - // Create a proxy body object. - var body = context.document.body; + // Create a proxy body object. + var body = context.document.body; - // Queue a command to insert the image into the document. - var image = body.insertInlinePictureFromBase64('', Word.InsertLocation.start); + // Queue a command to insert the image into the document. + var image = body.insertInlinePictureFromBase64('', Word.InsertLocation.start); - // Queue a command to select the image. - image.select(); + // Queue a command to select the image. + image.select(); - // Synchronize the document state by executing the queued commands, - // and returning a promise to indicate task completion. - return context.sync() - }) - .catch(function (error) { - console.log('Error: ' + JSON.stringify(error)); - if (error instanceof OfficeExtension.Error) { - console.log('Debug info: ' + JSON.stringify(error.debugInfo)); - } - }); + // Synchronize the document state by executing the queued commands, + // and returning a promise to indicate task completion. + return context.sync() + }) + .catch(function (error) { + console.log('Error: ' + JSON.stringify(error)); + if (error instanceof OfficeExtension.Error) { + console.log('Debug info: ' + JSON.stringify(error.debugInfo)); + } + }); - // Body.insertInlinePictureFromBase64 Word 1.2 - Word.run((context) => { + // Body.insertInlinePictureFromBase64 Word 1.2 + Word.run((context) => { - // Create a proxy object for the range at the current selection. - var imageRange = context.document.getSelection(); + // Create a proxy object for the range at the current selection. + var imageRange = context.document.getSelection(); - // Load the selected range. - context.load(imageRange, 'text'); + // Load the selected range. + context.load(imageRange, 'text'); - // Synchronize the document state by executing the queued commands, - // and return a promise to indicate task completion. - return context.sync() - .then(() => { + // Synchronize the document state by executing the queued commands, + // and return a promise to indicate task completion. + return context.sync() + .then(() => { - // Queue a command to insert the image into the document. - var insertedImage = imageRange.insertInlinePictureFromBase64('', Word.InsertLocation.replace); + // Queue a command to insert the image into the document. + var insertedImage = imageRange.insertInlinePictureFromBase64('', Word.InsertLocation.replace); - // Queue a command to navigate the UI to the insert picture. - insertedImage.select(); + // Queue a command to navigate the UI to the insert picture. + insertedImage.select(); - // Queue an indefinite number of commands to insert paragraphs - // based on the number of callouts added to the image. - if (this._calloutNumber > 0) { - var lastParagraph = insertedImage.insertParagraph('Here are your callout descriptions:', Word.InsertLocation.after) as Word.Paragraph; + // Queue an indefinite number of commands to insert paragraphs + // based on the number of callouts added to the image. + if (this._calloutNumber > 0) { + var lastParagraph = insertedImage.insertParagraph('Here are your callout descriptions:', Word.InsertLocation.after) as Word.Paragraph; - for (var i = 0; i < this._calloutNumber; i += 1) { - lastParagraph = lastParagraph.insertParagraph((i + 1) + ') [enter callout description].', Word.InsertLocation.after); - } - } - }) - // Synchronize the document state by executing the queued commands. - .then(context.sync); - }) - .catch((error) => { - console.log('Error: ' + JSON.stringify(error)); - if (error instanceof OfficeExtension.Error) { - console.log('Debug info: ' + JSON.stringify(error.debugInfo)); - } - }); + for (var i = 0; i < this._calloutNumber; i += 1) { + lastParagraph = lastParagraph.insertParagraph((i + 1) + ') [enter callout description].', Word.InsertLocation.after); + } + } + }) + // Synchronize the document state by executing the queued commands. + .then(context.sync); + }) + .catch((error) => { + console.log('Error: ' + JSON.stringify(error)); + if (error instanceof OfficeExtension.Error) { + console.log('Debug info: ' + JSON.stringify(error.debugInfo)); + } + }); } async function test_visio() { - const url = "someurl"; + const url = "someurl"; - try { - const session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe", container: document.getElementById("iframeHost") }); - await session.init(); - await Visio.run(session, async context => { - const eventResult = context.document.onPageLoadComplete.add(async args => { - console.log(Date.now() + ": Page Load Complete Event: " + JSON.stringify(args)); - }); - await context.sync(); - console.log("Success"); - }); - } catch (error) { - if (error instanceof OfficeExtension.Error) { - console.log("Debug info: " + JSON.stringify(error.debugInfo)); - } - } + try { + const session = new OfficeExtension.EmbeddedSession(url, { id: "embed-iframe", container: document.getElementById("iframeHost") }); + await session.init(); + await Visio.run(session, async context => { + const eventResult = context.document.onPageLoadComplete.add(async args => { + console.log(Date.now() + ": Page Load Complete Event: " + JSON.stringify(args)); + }); + await context.sync(); + console.log("Success"); + }); + } catch (error) { + if (error instanceof OfficeExtension.Error) { + console.log("Debug info: " + JSON.stringify(error.debugInfo)); + } + } } function test_OfficePromise() { - let p1: Promise = Excel.run(async () => { return 10 }); - let p2: Promise = new OfficeExtension.Promise(resolve => setTimeout(resolve, 1000)); - let p3: Promise = new Office.Promise(resolve => setTimeout(resolve, 1000)); - let p4: OfficeExtension.IPromise = new OfficeExtension.Promise(resolve => setTimeout(resolve, 1000)); + let p1: Promise = Excel.run(async () => { return 10 }); + let p2: Promise = new OfficeExtension.Promise(resolve => setTimeout(resolve, 1000)); + let p3: Promise = new Office.Promise(resolve => setTimeout(resolve, 1000)); + let p4: OfficeExtension.IPromise = new OfficeExtension.Promise(resolve => setTimeout(resolve, 1000)); } async function test_interfaces() { - await Excel.run(async context => { - let range = context.workbook.getSelectedRange(); - range.set({ - values: [["Hi"]], - format: { - fill: { - color: "red" - } - } - }); + await Excel.run(async context => { + let range = context.workbook.getSelectedRange(); + range.set({ + values: [["Hi"]], + format: { + fill: { + color: "red" + } + } + }); - let rangeSettables: Excel.Interfaces.RangeUpdateData = { - values: [["Hi"]], - format: { - fill: { - color: "red" - } - } - }; - range.set(rangeSettables); - }); + let rangeSettables: Excel.Interfaces.RangeUpdateData = { + values: [["Hi"]], + format: { + fill: { + color: "red" + } + } + }; + range.set(rangeSettables); + }); } async function testResumeExistingObject () { - let range: Excel.Range; - await Excel.run(async context => { - range = context.workbook.getSelectedRange(); - await context.sync(); - }); + let range: Excel.Range; + await Excel.run(async context => { + range = context.workbook.getSelectedRange(); + await context.sync(); + }); - await Excel.run(range, async context => { - range.clear(); - await context.sync(); - }); + await Excel.run(range, async context => { + range.clear(); + await context.sync(); + }); - await Excel.run({delayForCellEdit: true, previousObjects: range}, async context => { - range.clear(); - await context.sync(); - }); + await Excel.run({delayForCellEdit: true, previousObjects: range}, async context => { + range.clear(); + await context.sync(); + }); +} + +/* Office direct API tests */ +async function testOfficeDirectApis() { + let supported = Office.isSetSupported('ExcelApi', '1.10'); + Office.addin.setStartupBehavior(Office.StartupBehavior.load); + let startupBehavior = Office.addin.getStartupBehavior(); + Office.ribbon.requestUpdate({ + tabs: [ + { + id: 'test-id', + }, + ], + }); }