diff --git a/types/office-js-preview/index.d.ts b/types/office-js-preview/index.d.ts index 2064930dcff875..ec227a0ca97fb3 100644 --- a/types/office-js-preview/index.d.ts +++ b/types/office-js-preview/index.d.ts @@ -24276,8 +24276,9 @@ declare namespace Excel { /** * Represents an unknown cell control. * This represents a control that was added in a future version of Excel, and the current version of Excel doesn't know how to display this control. - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * + * @remarks + * [Api set: ExcelApi 1.18] */ interface UnknownCellControl { type: CellControlType.unknown; @@ -24285,8 +24286,9 @@ declare namespace Excel { /** * Represents an empty cell control. * This represents the state where a cell does not have a control. - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * + * @remarks + * [Api set: ExcelApi 1.18] */ interface EmptyCellControl { type: CellControlType.empty; @@ -24294,25 +24296,28 @@ declare namespace Excel { /** * Represents the result of a query that resulted in multiple cell controls. * If the result has multiple controls, then they can't be represented as a single result. - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * + * @remarks + * [Api set: ExcelApi 1.18] */ interface MixedCellControl { type: CellControlType.mixed; } /** - * Represents a checkbox. This is a cell control that allows a user to toggle the boolean value in a cell. - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta - */ + * Represents a checkbox. This is a cell control that allows a user to toggle the boolean value in a cell. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ interface CheckboxCellControl { type: CellControlType.checkbox; } /** - * Represents an interactable control inside of a cell. - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta - */ + * Represents an interactable control inside of a cell. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ type CellControl = UnknownCellControl | EmptyCellControl | MixedCellControl | CheckboxCellControl; /** * Represents a 2D array of cell values. @@ -32399,7 +32404,7 @@ declare namespace Excel { /** * Specifies whether to load on the `textRuns` property. * - * [Api set: ExcelApi BETA (PREVIEW ONLY)] + * [Api set: ExcelApi 1.18] */ textRuns?: boolean; } @@ -32602,7 +32607,7 @@ declare namespace Excel { /** * Represents the `textRuns` property. * - * [Api set: ExcelApi BETA (PREVIEW ONLY)] + * [Api set: ExcelApi 1.18] */ textRuns?: RangeTextRun[]; } @@ -36509,39 +36514,41 @@ declare namespace Excel { * Represents the type of cell control. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ enum CellControlType { /** * Type representing an unknown control. This represents a control that was added in a future version of Excel, and the current version of Excel doesn't know how to display this control. * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ unknown = "Unknown", /** * Type representing an empty control. * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ empty = "Empty", /** * Type representing a query that results in a mix of control results. * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ mixed = "Mixed", /** * Type representing a checkbox control. * @remarks + * [Api set: ExcelApi 1.18] + */ + checkbox = "Checkbox", + /** + * Type representing a dropdown control. + * @remarks * [Api set: ExcelApi BETA (PREVIEW ONLY)] * @beta */ - checkbox = "Checkbox" + dropdown = "Dropdown" } /** * Represents the direction that existing or remaining cells in a worksheet will shift when cells are inserted into or deleted from a worksheet. @@ -38107,8 +38114,7 @@ declare namespace Excel { * Returns a collection of all the notes objects in the workbook. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ readonly notes: Excel.NoteCollection; /** @@ -38634,8 +38640,7 @@ declare namespace Excel { * Returns a collection of all the notes objects in the worksheet. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ readonly notes: Excel.NoteCollection; /** @@ -39892,8 +39897,7 @@ declare namespace Excel { If the range has multiple cell controls, this returns `EmptyCellControl`. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ control: CellControl; /** @@ -40158,8 +40162,7 @@ declare namespace Excel { Otherwise, this sets the cells with controls to their default value and clears the values of the other cells in the range. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ clearOrResetContents(): void; /** @@ -41087,8 +41090,7 @@ declare namespace Excel { Otherwise, this sets the cells with controls to their default value and clears the values of the other cells in the ranges. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ clearOrResetContents(): void; /** @@ -41253,8 +41255,7 @@ declare namespace Excel { * Selects the specified range areas in the Excel UI. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ select(): void; /** @@ -41620,12 +41621,25 @@ declare namespace Excel { weight?: boolean; } /** + * Represents a sequence of one or more characters that share the same font attributes in a cell. Can be used as the `textRuns` properties of `getCellProperties` or the `textRuns` input parameter of `setCellProperties`. + * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ interface RangeTextRun { + /** + * The font attributes (such as font name, font size, and color) applied to this text run. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ font?: Excel.CellPropertiesFont; + /** + * The text of this text run. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ text: string; } /** @@ -61268,8 +61282,7 @@ declare namespace Excel { Cells with cell controls are set to the default value defined by each control. Cells without cell controls are set to blank. * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ resetContents = "ResetContents" } @@ -66128,8 +66141,7 @@ declare namespace Excel { * Represents a collection of note objects that are part of the workbook. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ class NoteCollection extends OfficeExtension.ClientObject { /** The request context associated with the object. This connects the add-in's process to the Office host application's process. */ @@ -66140,8 +66152,7 @@ declare namespace Excel { * Adds a new note with the given content on the given cell. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] * * @param cellAddress The cell to which the note is added. This can be a `Range` object or a string such as "A1". If the string is invalid, or the range is not a single cell, an `InvalidCellAddress` error is thrown. * @param content The text of the note. @@ -66151,20 +66162,38 @@ declare namespace Excel { * Gets the number of notes in the collection. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ getCount(): OfficeExtension.ClientResult; /** - * Gets a note object by its index in the collection. + * Gets a note by its cell address. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] + * + * @param key The cell address of the note. + * @returns The note with the given cell address. If there is no note with the given cell address, then the `ItemNotFound` error is thrown. + */ + getItem(key: string): Excel.Note; + /** + * Gets a note from the collection based on its position. + * + * @remarks + * [Api set: ExcelApi 1.18] * * @param index The index value of the note to be retrieved. Zero-indexed. */ getItemAt(index: number): Excel.Note; + /** + * Gets a note by its cell address. If the note object does not exist, then this method returns an object with its `isNullObject` property set to `true`. For further information, see {@link https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties | *OrNullObject methods and properties}. + * + * @remarks + * [Api set: ExcelApi 1.18] + * + * @param key The cell address of the note. + * @returns The note with the given cell address or null object. + */ + getItemOrNullObject(key: string): Excel.Note; /** * Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties. * @@ -66193,8 +66222,7 @@ declare namespace Excel { * Represents a note in the workbook or worksheet. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ class Note extends OfficeExtension.ClientObject { /** The request context associated with the object. This connects the add-in's process to the Office host application's process. */ @@ -66203,40 +66231,35 @@ declare namespace Excel { * Gets the author of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ readonly authorName: string; /** - * Gets or sets the text of the note. The string must be fewer than 256 characters. + * Gets or sets the text of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ content: string; /** * Specifies the height of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ height: number; /** * Specifies the visibility of the note. A value of `true` means the note is shown. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ visible: boolean; /** * Specifies the width of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ width: number; /** @@ -66251,16 +66274,14 @@ declare namespace Excel { * Deletes the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ delete(): void; /** * Gets the cell where this note is located. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ getLocation(): Excel.Range; /** @@ -70448,8 +70469,7 @@ declare namespace Excel { If the range has multiple cell controls, this returns `EmptyCellControl`. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ control?: CellControl; /** @@ -75144,35 +75164,31 @@ declare namespace Excel { /** An interface for updating data on the `Note` object, for use in `note.set({ ... })`. */ interface NoteUpdateData { /** - * Gets or sets the text of the note. The string must be fewer than 256 characters. + * Gets or sets the text of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ content?: string; /** * Specifies the height of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ height?: number; /** * Specifies the visibility of the note. A value of `true` means the note is shown. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ visible?: boolean; /** * Specifies the width of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ width?: number; } @@ -75607,8 +75623,7 @@ declare namespace Excel { * Returns a collection of all the notes objects in the workbook. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ notes?: Excel.Interfaces.NoteData[]; /** @@ -75841,8 +75856,7 @@ declare namespace Excel { * Returns a collection of all the notes objects in the worksheet. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ notes?: Excel.Interfaces.NoteData[]; /** @@ -76104,8 +76118,7 @@ declare namespace Excel { If the range has multiple cell controls, this returns `EmptyCellControl`. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ control?: CellControl; /** @@ -82164,40 +82177,35 @@ declare namespace Excel { * Gets the author of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ authorName?: string; /** - * Gets or sets the text of the note. The string must be fewer than 256 characters. + * Gets or sets the text of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ content?: string; /** * Specifies the height of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ height?: number; /** * Specifies the visibility of the note. A value of `true` means the note is shown. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ visible?: boolean; /** * Specifies the width of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ width?: number; } @@ -83558,8 +83566,7 @@ declare namespace Excel { If the range has multiple cell controls, this returns `EmptyCellControl`. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ control?: boolean; /** @@ -91890,8 +91897,7 @@ declare namespace Excel { If the range has multiple cell controls, this returns `EmptyCellControl`. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ control?: boolean; /** @@ -94035,8 +94041,7 @@ declare namespace Excel { * Represents a collection of note objects that are part of the workbook. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ interface NoteCollectionLoadOptions { /** @@ -94047,40 +94052,35 @@ declare namespace Excel { * For EACH ITEM in the collection: Gets the author of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ authorName?: boolean; /** - * For EACH ITEM in the collection: Gets or sets the text of the note. The string must be fewer than 256 characters. + * For EACH ITEM in the collection: Gets or sets the text of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ content?: boolean; /** * For EACH ITEM in the collection: Specifies the height of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ height?: boolean; /** * For EACH ITEM in the collection: Specifies the visibility of the note. A value of `true` means the note is shown. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ visible?: boolean; /** * For EACH ITEM in the collection: Specifies the width of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ width?: boolean; } @@ -94088,8 +94088,7 @@ declare namespace Excel { * Represents a note in the workbook or worksheet. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ interface NoteLoadOptions { /** @@ -94100,40 +94099,35 @@ declare namespace Excel { * Gets the author of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ authorName?: boolean; /** - * Gets or sets the text of the note. The string must be fewer than 256 characters. + * Gets or sets the text of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ content?: boolean; /** * Specifies the height of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ height?: boolean; /** * Specifies the visibility of the note. A value of `true` means the note is shown. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ visible?: boolean; /** * Specifies the width of the note. * * @remarks - * [Api set: ExcelApi BETA (PREVIEW ONLY)] - * @beta + * [Api set: ExcelApi 1.18] */ width?: boolean; } diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index 0d48232636b73e..ddcb05e100e39e 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -21869,6 +21869,52 @@ declare namespace OfficeCore { declare namespace Excel { + /** + * Represents an unknown cell control. + * This represents a control that was added in a future version of Excel, and the current version of Excel doesn't know how to display this control. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface UnknownCellControl { + type: CellControlType.unknown; + } + /** + * Represents an empty cell control. + * This represents the state where a cell does not have a control. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface EmptyCellControl { + type: CellControlType.empty; + } + /** + * Represents the result of a query that resulted in multiple cell controls. + * If the result has multiple controls, then they can't be represented as a single result. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface MixedCellControl { + type: CellControlType.mixed; + } + /** + * Represents a checkbox. This is a cell control that allows a user to toggle the boolean value in a cell. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface CheckboxCellControl { + type: CellControlType.checkbox; + } + /** + * Represents an interactable control inside of a cell. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + type CellControl = UnknownCellControl | EmptyCellControl | MixedCellControl | CheckboxCellControl; /** * Represents a 2D array of cell values. * @@ -30572,6 +30618,39 @@ declare namespace Excel { */ type: "WorkbookAutoSaveSettingChanged"; } + /** + * Represents the type of cell control. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + enum CellControlType { + /** + * Type representing an unknown control. + This represents a control that was added in a future version of Excel, and the current version of Excel doesn't know how to display this control. + * @remarks + * [Api set: ExcelApi 1.18] + */ + unknown = "Unknown", + /** + * Type representing an empty control. + * @remarks + * [Api set: ExcelApi 1.18] + */ + empty = "Empty", + /** + * Type representing a query that results in a mix of control results. + * @remarks + * [Api set: ExcelApi 1.18] + */ + mixed = "Mixed", + /** + * Type representing a checkbox control. + * @remarks + * [Api set: ExcelApi 1.18] + */ + checkbox = "Checkbox" + } /** * Represents the direction that existing or remaining cells in a worksheet will shift when cells are inserted into or deleted from a worksheet. * @@ -32049,6 +32128,13 @@ declare namespace Excel { * [Api set: ExcelApi 1.1] */ readonly names: Excel.NamedItemCollection; + /** + * Returns a collection of all the notes objects in the workbook. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + readonly notes: Excel.NoteCollection; /** * Represents a collection of PivotTableStyles associated with the workbook. * @@ -32535,6 +32621,13 @@ declare namespace Excel { * [Api set: ExcelApi 1.4] */ readonly names: Excel.NamedItemCollection; + /** + * Returns a collection of all the notes objects in the worksheet. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + readonly notes: Excel.NoteCollection; /** * Gets the `PageLayout` object of the worksheet. * @@ -33724,6 +33817,14 @@ declare namespace Excel { * [Api set: ExcelApi 1.1] */ readonly columnIndex: number; + /** + * Accesses the cell control applied to this range. + If the range has multiple cell controls, this returns `EmptyCellControl`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + control: CellControl; /** * Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead. * @@ -33979,7 +34080,16 @@ declare namespace Excel { * * @param applyTo Optional. Determines the type of clear action. See `Excel.ClearApplyTo` for details. */ - clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void; + clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void; + /** + * Clears the values of the cells in the range, with special consideration given to cells containing controls. + If the range contains only blank values and controls set to their default value, then the values and control formatting are removed. + Otherwise, this sets the cells with controls to their default value and clears the values of the other cells in the range. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + clearOrResetContents(): void; /** * Converts the range cells with data types into text. * @@ -34886,7 +34996,16 @@ declare namespace Excel { * * @param applyTo Optional. Determines the type of clear action. See `Excel.ClearApplyTo` for details. Default is "All". */ - clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void; + clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void; + /** + * Clears the values of the cells in the ranges, with special consideration given to cells containing controls. + If the ranges contain only blank values and controls set to their default value, then the values and control formatting are removed. + Otherwise, this sets the cells with controls to their default value and clears the values of the other cells in the ranges. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + clearOrResetContents(): void; /** * Converts all cells in the `RangeAreas` with data types into text. * @@ -35045,6 +35164,13 @@ declare namespace Excel { * @param valuesOnly Whether to only consider cells with values as used cells. */ getUsedRangeAreasOrNullObject(valuesOnly?: boolean): Excel.RangeAreas; + /** + * Selects the specified range areas in the Excel UI. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + select(): void; /** * Sets the `RangeAreas` to be recalculated when the next recalculation occurs. * @@ -35407,6 +35533,28 @@ declare namespace Excel { */ weight?: boolean; } + /** + * Represents a sequence of one or more characters that share the same font attributes in a cell. Can be used as the `textRuns` properties of `getCellProperties` or the `textRuns` input parameter of `setCellProperties`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface RangeTextRun { + /** + * The font attributes (such as font name, font size, and color) applied to this text run. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + font?: Excel.CellPropertiesFont; + /** + * The text of this text run. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + text: string; + } /** * Represents the `format.protection` properties of `getCellProperties`, `getRowProperties`, and `getColumnProperties`, or the `format.protection` input parameter of `setCellProperties`, `setRowProperties`, and `setColumnProperties`. * @@ -54417,7 +54565,15 @@ declare namespace Excel { * @remarks * [Api set: ExcelApi 1.7] */ - removeHyperlinks = "RemoveHyperlinks" + removeHyperlinks = "RemoveHyperlinks", + /** + * Sets all cells in the range to their default state. + Cells with cell controls are set to the default value defined by each control. + Cells without cell controls are set to blank. + * @remarks + * [Api set: ExcelApi 1.18] + */ + resetContents = "ResetContents" } /** * Represents the format options for a data bar axis. @@ -59218,6 +59374,182 @@ declare namespace Excel { */ toJSON(): Excel.Interfaces.NamedSheetViewCollectionData; } + /** + * Represents a collection of note objects that are part of the workbook. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + class NoteCollection extends OfficeExtension.ClientObject { + /** The request context associated with the object. This connects the add-in's process to the Office host application's process. */ + context: RequestContext; + /** Gets the loaded child items in this collection. */ + readonly items: Excel.Note[]; + /** + * Adds a new note with the given content on the given cell. + * + * @remarks + * [Api set: ExcelApi 1.18] + * + * @param cellAddress The cell to which the note is added. This can be a `Range` object or a string such as "A1". If the string is invalid, or the range is not a single cell, an `InvalidCellAddress` error is thrown. + * @param content The text of the note. + */ + add(cellAddress: Range | string, content: any): Excel.Note; + /** + * Gets the number of notes in the collection. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + getCount(): OfficeExtension.ClientResult; + /** + * Gets a note by its cell address. + * + * @remarks + * [Api set: ExcelApi 1.18] + * + * @param key The cell address of the note. + * @returns The note with the given cell address. If there is no note with the given cell address, then the `ItemNotFound` error is thrown. + */ + getItem(key: string): Excel.Note; + /** + * Gets a note from the collection based on its position. + * + * @remarks + * [Api set: ExcelApi 1.18] + * + * @param index The index value of the note to be retrieved. Zero-indexed. + */ + getItemAt(index: number): Excel.Note; + /** + * Gets a note by its cell address. + If the note object does not exist, then this method returns an object with its `isNullObject` property set to `true`. + For further information, see {@link https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties | *OrNullObject methods and properties}. + * + * @remarks + * [Api set: ExcelApi 1.18] + * + * @param key The cell address of the note. + * @returns The note with the given cell address or null object. + */ + getItemOrNullObject(key: string): Excel.Note; + /** + * 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. + */ + load(options?: Excel.Interfaces.NoteCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.NoteCollection; + /** + * Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties. + * + * @param propertyNames A comma-delimited string or an array of strings that specify the properties to load. + */ + load(propertyNames?: string | string[]): Excel.NoteCollection; + /** + * Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties. + * + * @param propertyNamesAndPaths `propertyNamesAndPaths.select` is a comma-delimited string that specifies the properties to load, and `propertyNamesAndPaths.expand` is a comma-delimited string that specifies the navigation properties to load. + */ + load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.NoteCollection; + /** + * Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that's passed to it.) + * Whereas the original `Excel.NoteCollection` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.NoteCollectionData`) that contains an "items" array with shallow copies of any loaded properties from the collection's items. + */ + toJSON(): Excel.Interfaces.NoteCollectionData; + } + /** + * Represents a note in the workbook or worksheet. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + class Note extends OfficeExtension.ClientObject { + /** The request context associated with the object. This connects the add-in's process to the Office host application's process. */ + context: RequestContext; + /** + * Gets the author of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + readonly authorName: string; + /** + * Gets or sets the text of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + content: string; + /** + * Specifies the height of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + height: number; + /** + * Specifies the visibility of the note. A value of `true` means the note is shown. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + visible: boolean; + /** + * Specifies the width of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + width: number; + /** + * Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type. + * @param properties A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called. + * @param options Provides an option to suppress errors if the properties object tries to set any read-only properties. + */ + set(properties: Interfaces.NoteUpdateData, options?: OfficeExtension.UpdateOptions): void; + /** Sets multiple properties on the object at the same time, based on an existing loaded object. */ + set(properties: Excel.Note): void; + /** + * Deletes the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + delete(): void; + /** + * Gets the cell where this note is located. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + getLocation(): Excel.Range; + /** + * 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. + */ + load(options?: Excel.Interfaces.NoteLoadOptions): Excel.Note; + /** + * Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties. + * + * @param propertyNames A comma-delimited string or an array of strings that specify the properties to load. + */ + load(propertyNames?: string | string[]): Excel.Note; + /** + * Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties. + * + * @param propertyNamesAndPaths `propertyNamesAndPaths.select` is a comma-delimited string that specifies the properties to load, and `propertyNamesAndPaths.expand` is a comma-delimited string that specifies the navigation properties to load. + */ + load(propertyNamesAndPaths?: { + select?: string; + expand?: string; + }): Excel.Note; + /** + * Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that's passed to it.) + * Whereas the original `Excel.Note` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.NoteData`) that contains shallow copies of any loaded child properties from the original object. + */ + toJSON(): Excel.Interfaces.NoteData; + } /** * An object containing the result of a function-evaluation operation * @@ -63294,6 +63626,14 @@ declare namespace Excel { * [Api set: ExcelApi 1.2] */ columnHidden?: boolean; + /** + * Accesses the cell control applied to this range. + If the range has multiple cell controls, this returns `EmptyCellControl`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + control?: CellControl; /** * Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead. * @@ -67943,6 +68283,41 @@ declare namespace Excel { interface NamedSheetViewCollectionUpdateData { items?: Excel.Interfaces.NamedSheetViewData[]; } + /** An interface for updating data on the `NoteCollection` object, for use in `noteCollection.set({ ... })`. */ + interface NoteCollectionUpdateData { + items?: Excel.Interfaces.NoteData[]; + } + /** An interface for updating data on the `Note` object, for use in `note.set({ ... })`. */ + interface NoteUpdateData { + /** + * Gets or sets the text of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + content?: string; + /** + * Specifies the height of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + height?: number; + /** + * Specifies the visibility of the note. A value of `true` means the note is shown. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + visible?: boolean; + /** + * Specifies the width of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + width?: number; + } /** An interface describing the data returned by calling `allowEditRange.toJSON()`. */ interface AllowEditRangeData { /** @@ -68168,6 +68543,13 @@ declare namespace Excel { */ names?: Excel.Interfaces.NamedItemData[]; /** + * Returns a collection of all the notes objects in the workbook. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + notes?: Excel.Interfaces.NoteData[]; + /** * Represents a collection of PivotTableStyles associated with the workbook. * * @remarks @@ -68369,6 +68751,13 @@ declare namespace Excel { */ names?: Excel.Interfaces.NamedItemData[]; /** + * Returns a collection of all the notes objects in the worksheet. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + notes?: Excel.Interfaces.NoteData[]; + /** * Gets the `PageLayout` object of the worksheet. * * @remarks @@ -68622,6 +69011,14 @@ declare namespace Excel { * [Api set: ExcelApi 1.1] */ columnIndex?: number; + /** + * Accesses the cell control applied to this range. + If the range has multiple cell controls, this returns `EmptyCellControl`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + control?: CellControl; /** * Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead. * @@ -74564,6 +74961,48 @@ declare namespace Excel { interface NamedSheetViewCollectionData { items?: Excel.Interfaces.NamedSheetViewData[]; } + /** An interface describing the data returned by calling `noteCollection.toJSON()`. */ + interface NoteCollectionData { + items?: Excel.Interfaces.NoteData[]; + } + /** An interface describing the data returned by calling `note.toJSON()`. */ + interface NoteData { + /** + * Gets the author of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + authorName?: string; + /** + * Gets or sets the text of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + content?: string; + /** + * Specifies the height of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + height?: number; + /** + * Specifies the visibility of the note. A value of `true` means the note is shown. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + visible?: boolean; + /** + * Specifies the width of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + width?: number; + } /** An interface describing the data returned by calling `functionResult.toJSON()`. */ interface FunctionResultData { /** @@ -75454,6 +75893,14 @@ declare namespace Excel { * [Api set: ExcelApi 1.1] */ columnIndex?: boolean; + /** + * Accesses the cell control applied to this range. + If the range has multiple cell controls, this returns `EmptyCellControl`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + control?: boolean; /** * Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead. * @@ -83737,6 +84184,14 @@ declare namespace Excel { * [Api set: ExcelApi 1.1] */ columnIndex?: boolean; + /** + * For EACH ITEM in the collection: Accesses the cell control applied to this range. + If the range has multiple cell controls, this returns `EmptyCellControl`. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + control?: boolean; /** * For EACH ITEM in the collection: Represents the formula in A1-style notation. If a cell has no formula, its value is returned instead. * @@ -85701,6 +86156,100 @@ declare namespace Excel { */ name?: boolean; } + /** + * Represents a collection of note objects that are part of the workbook. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface NoteCollectionLoadOptions { + /** + Specifying `$all` for the load options loads all the scalar properties (such as `Range.address`) but not the navigational properties (such as `Range.format.fill.color`). + */ + $all?: boolean; + /** + * For EACH ITEM in the collection: Gets the author of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + authorName?: boolean; + /** + * For EACH ITEM in the collection: Gets or sets the text of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + content?: boolean; + /** + * For EACH ITEM in the collection: Specifies the height of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + height?: boolean; + /** + * For EACH ITEM in the collection: Specifies the visibility of the note. A value of `true` means the note is shown. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + visible?: boolean; + /** + * For EACH ITEM in the collection: Specifies the width of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + width?: boolean; + } + /** + * Represents a note in the workbook or worksheet. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + interface NoteLoadOptions { + /** + Specifying `$all` for the load options loads all the scalar properties (such as `Range.address`) but not the navigational properties (such as `Range.format.fill.color`). + */ + $all?: boolean; + /** + * Gets the author of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + authorName?: boolean; + /** + * Gets or sets the text of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + content?: boolean; + /** + * Specifies the height of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + height?: boolean; + /** + * Specifies the visibility of the note. A value of `true` means the note is shown. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + visible?: boolean; + /** + * Specifies the width of the note. + * + * @remarks + * [Api set: ExcelApi 1.18] + */ + width?: boolean; + } /** * An object containing the result of a function-evaluation operation *