Skip to content

[excel] Update reference docs with latest IntelliSense file #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alison-mk merged 5 commits into from
Dec 5, 2025
Merged

[excel] Update reference docs with latest IntelliSense file #403

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
95a3196
[excel] Update reference docs with latest IntelliSense file
alison-mk Dec 4, 2025
a15328c
Adjust preview APIs overview article
alison-mk Dec 4, 2025
2a2a254
Merge branch 'main' into alison-mk-intellisense-120425
alison-mk Dec 4, 2025
217029e
Move namespace details to permanent location
alison-mk Dec 5, 2025
483823e
Apply suggestions from code review
alison-mk Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/docs-ref-autogen/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Office Scripts API reference
description: An overview of the Office Scripts JavaScript APIs.
ms.topic: overview
ms.date: 10/01/2022
ms.date: 12/04/2025
---

# Office Scripts API reference
Expand All @@ -12,6 +12,10 @@ The Office Scripts API lets you automate common tasks in Excel. Use this referen
> [!NOTE]
> If you're looking for the JavaScript APIs for developing Office Add-ins, visit the [Office Add-ins JavaScript API reference](/javascript/api/overview?view=excel-js-preview&preserve-view=true).

## Namespaces

Office Scripts APIs use two namespaces: [OfficeScript](/javascript/api/office-scripts/officescript) for APIs that are not connected to an Excel workbook, and [ExcelScript](/javascript/api/office-scripts/excelscript) for APIs that work with Excel workbooks.

## Common classes

The following list breaks down the basics of the Office Scripts object model. This shows the common classes and how they relate to one another.
Expand Down
17 changes: 5 additions & 12 deletions docs/docs-ref-autogen/preview-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Office Scripts preview APIs
description: Details about upcoming Office Scripts APIs.
ms.topic: whats-new
ms.date: 09/12/2025
ms.date: 12/04/2025
---

# Office Scripts preview APIs
Expand All @@ -12,19 +12,12 @@ New Office Scripts APIs are first introduced in "preview", and then later releas
> [!IMPORTANT]
> Preview APIs are subject to change and are not intended for use in a production environment. We recommend that you try them out in test and development environments only. Do not use preview APIs in a production environment or within business-critical documents.

The following table provides a concise summary of the APIs, while the subsequent [API list](#api-list) section gives a detailed list.

| Feature area | Description | Relevant objects |
|:--- |:--- |:--- |
| Save and email a PDF | Save a worksheet as a PDF and email it to yourself or your team. For a sample, see [Save a worksheet and email it as a PDF](/office/dev/scripts/resources/samples/save-as-pdf-email-as-pdf). | [EmailAttachment](/javascript/api/office-scripts/officescript/officescript.emailattachment), [MailProperties](/javascript/api/office-scripts/officescript/officescript.mailproperties) |

## API list

Office Scripts APIs use two namespaces: `OfficeScript` for APIs that are not connected to an Excel workbook, and `ExcelScript` for APIs that work with Excel workbooks. Currently, the only preview APIs are in the `OfficeScript` namespace. The following section lists those APIs.

### OfficeScript namespace

[!INCLUDE[API table](../includes/officescript-preview.md)]
<!-- [!INCLUDE[API table](../includes/officescript-preview.md)] -->
<!-- [!INCLUDE[API table](../includes/excelscript-preview.md)] -->
> [!NOTE]
> There are currently no APIs in preview.

## See also

Expand Down
73 changes: 23 additions & 50 deletions generate-docs/script-inputs/office-scripts-docs.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1886,7 +1886,7 @@ declare namespace ExcelScript {
getEntireRow(): Range;

/**
* Returns a range object that includes the current range and up to the edge of the range, based on the provided direction. This matches the <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Arrow key</kbd> behavior in the Excel on Windows UI.
* Returns a range object that includes the current range and up to the edge of the range, based on the provided direction. This matches the Ctrl+Shift+Arrow key behavior in the Excel on Windows UI.
* @param direction The direction from the active cell.
* @param activeCell The active cell in this range. By default, the active cell is the top-left cell of the range. An error is thrown if the active cell is not in this range.
*/
Expand Down Expand Up @@ -1946,7 +1946,7 @@ declare namespace ExcelScript {
getPrecedents(): WorkbookRangeAreas;

/**
* Returns a range object that is the edge cell of the data region that corresponds to the provided direction. This matches the <kbd>Ctrl</kbd>+<kbd>Arrow key</kbd> behavior in the Excel on Windows UI.
* Returns a range object that is the edge cell of the data region that corresponds to the provided direction. This matches the Ctrl+Arrow key behavior in the Excel on Windows UI.
* @param direction The direction from the active cell.
* @param activeCell The active cell in this range. By default, the active cell is the top-left cell of the range. An error is thrown if the active cell is not in this range.
*/
Expand Down Expand Up @@ -15226,106 +15226,93 @@ declare namespace ExcelScript {
declare namespace OfficeScript {
/**
* Saves a copy of the current workbook in OneDrive, in the same directory as the original file, with the specified file name.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
* This API must be called before other APIs.
* @param filename The file name of the copied and saved file. The file name must end with ".xlsx".
* @throws InvalidExtensionError The error thrown if the file name doesn't end with ".xlsx".
* @throws SaveCopyAsFileMayAlreadyExistError The error thrown if the file name of the copy already exists.
* @throws SaveCopyAsErrorInvalidCharacters The error thrown if the file name contains invalid characters.
* @throws SaveCopyAsFileNotOnOneDriveError The error thrown if the document is not saved to OneDrive.
* @throws ExternalApiTimeout The error thrown if the API reaches the timeout limit of 30 seconds. Note that the copy may still be created.
* @throws `SaveCopyAsInvalidExtension` Thrown if the file name doesn't end with ".xlsx".
* @throws `SaveCopyAsMustBeCalledFirst` Thrown if this method is called after other APIs.
* @throws `SaveCopyAsFileMayAlreadyExist` Thrown if the file name of the copy already exists.
* @throws `SaveCopyAsInvalidCharacters` Thrown if the file name contains invalid characters.
* @throws `SaveCopyAsFileNotOnOneDrive` Thrown if the document is not saved to OneDrive.
* @throws `ExternalApiTimeout` Thrown if the API reaches the timeout limit of 30 seconds. Note that the copy may still be created.
*/
function saveCopyAs(filename: string): void;

/**
* Converts the document to a PDF and returns the text encoding of it.
* Note: Recent changes made to the workbook in Excel on the web, through Office Scripts or the Excel UI, may not be captured in the PDF.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
* @returns The content of the workbook as a string, in PDF format.
* @throws ConvertToPdfEmptyWorkbook The error thrown if the document is empty.
* @throws ConvertToPdfProtectedWorkbook The error thrown if the document is protected.
* @throws ExternalApiTimeout The error thrown if the API reaches the timeout limit of 30 seconds.
* @throws `ConvertToPdfEmptyWorkbook` Thrown if the document is empty.
* @throws `ConvertToPdfProtectedWorkbook` Thrown if the document is protected.
* @throws `ExternalApiTimeout` Thrown if the API reaches the timeout limit of 30 seconds.
*/
function convertToPdf(): string;

/**
* Downloads a specified file to the default download location specified by the local machine.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
* @param fileProperties The file to download.
* @throws DownloadFileNameMissing The error thrown if the name is empty.
* @throws DownloadFileContentMissing The error thrown if the content is empty.
* @throws DownloadFileInvalidExtension The error thrown if the file name extension is not ".txt" or ".pdf".
* @throws ExternalApiTimeout The error thrown if the API reaches the timeout limit of 30 seconds.
* @throws `DownloadFileNameMissing` Thrown if the name is empty.
* @throws `DownloadFileContentMissing` Thrown if the content is empty.
* @throws `DownloadFileInvalidExtension` Thrown if the file name extension is not ".txt" or ".pdf".
* @throws `ExternalApiTimeout` Thrown if the API reaches the timeout limit of 30 seconds.
*/
function downloadFile(fileProperties: FileProperties): void;
function downloadFile(fileProperties: DownloadFileProperties): void;

/**
* The file to download.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
export interface FileProperties {
export interface DownloadFileProperties {
/**
* The name of the file once downloaded. The file extension determines the type of the file. Supported extensions are ".txt" and ".pdf". Default is ".txt".
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
name: string;

/**
* The content of the file.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
content: string;
}

/**
* Send an email with an Office Script. Use `MailProperties` to specify the content and recipients of the email.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
* @param message The properties that define the content and recipients of the email.
* @throws SendMailErrorMaxCalls The error thrown if the maximum number of API calls is exceeded. The limit is 100 API calls.
* @throws SendMailNoRecipient The error thrown if no recipient is specified.
* @throws SendMailInvalidEmail The error thrown if an invalid email address is provided.
* @throws SendMailExtensionNotSupported The error thrown if the attachment name extension is not ".txt" or ".pdf".
* @throws ExternalApiTimeout The error thrown if the API reaches the timeout limit of 30 seconds.
* @throws `SendMailMaxCalls` Thrown if the maximum number of API calls is exceeded. The limit is 100 API calls.
* @throws `SendMailNoRecipient` Thrown if no recipient is specified.
* @throws `SendMailInvalidEmail` Thrown if an invalid email address is provided.
* @throws `SendMailExtensionNotSupported` Thrown if the attachment name extension is not ".txt" or ".pdf".
* @throws `ExternalApiTimeout` Thrown if the API reaches the timeout limit of 30 seconds.
*/
function sendMail(mailProperties: MailProperties): void;

/**
* The type of the content. Possible values are text or HTML.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
enum EmailContentType {
/**
* The email message body is in HTML format.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
html = "html",

/**
* The email message body is in plain text format.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
text = "text",
}

/**
* The importance value of the email. Corresponds to "high", "normal", and "low" importance values available in the Outlook UI.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
enum EmailImportance {
/**
* Email is marked as low importance.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
low = "low",

/**
* Email does not have any importance specified.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
normal = "normal",

/**
* Email is marked as high importance.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
high = "high",
}
Expand All @@ -15334,83 +15321,69 @@ declare namespace OfficeScript {
* The attachment to send with the email.
* A value must be specified for at least one of the `to`, `cc`, or `bcc` parameters.
* If no recipient is specified, the following error is shown: "The message has no recipient. Please enter a value for at least one of the "to", "cc", or "bcc" parameters."
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
export interface EmailAttachment {
/**
* The text that is displayed below the icon representing the attachment. This string doesn't need to match the file name.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
name: string;
/**
* The contents of the file.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
content: string;
}

/**
* The properties of the email to be sent.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
export interface MailProperties {
/**
* The subject of the email. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
subject?: string;

/**
* The content of the email. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
content?: string;

/**
* The type of the content in the email. Possible values are text or HTML. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
contentType?: EmailContentType;

/**
* The importance of the email. The possible values are `low`, `normal`, and `high`. Default value is `normal`. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
importance?: EmailImportance;

/**
* The direct recipient or recipients of the email. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
to?: string | string[];

/**
* The carbon copy (CC) recipient or recipients of the email. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
cc?: string | string[];

/**
* The blind carbon copy (BCC) recipient or recipients of the email. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
bcc?: string | string[];

/**
* A file (such as a text file or Excel workbook) attached to a message. Optional.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
attachments?: EmailAttachment | EmailAttachment[];
}

/**
* Metadata about the script.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
namespace Metadata {
/**
* Get the name of the currently running script.
* @beta This API is in preview and may change based on feedback. Do not use this API in a production environment.
*/
function getScriptName(): string;
}
Expand Down