Office Scripts use the TypeScript language. For the most part, any TypeScript or JavaScript code will work in Office Scripts. However, there are a few restrictions enforced by the Code Editor to ensure your script works consistently and as intended with your Excel workbook.
No 'any' type in Office Scripts
Writing types is optional in TypeScript, because the types can be inferred. However, Office Scripts requires that a variable can't be of type any. Both explicit and implicit any are not allowed in Office Scripts. These cases are reported as errors.
Explicit any
You cannot explicitly declare a variable to be of type any in Office Scripts (that is, let value: any;). The any type causes issues when processed by Excel. For example, a Range needs to know that a value is a string, number, or boolean. You will receive a compile-time error (an error prior to running the script) if any variable is explicitly defined as the any type in the script.
In the previous screenshot, [2, 14] Explicit Any is not allowed indicates that line #2, column #14 defines any type. This helps you locate the error.
To get around this issue, always define the type of the variable. If you are uncertain about the type of a variable, you can use a union type. This can be useful for variables that hold Range values, which can be of type string, number, or boolean (the type for Range values is a union of those: string | number | boolean).
Implicit any
TypeScript variable types can be implicitly defined. If the TypeScript compiler is unable to determine the type of a variable (either because type is not defined explicitly or type inference isn't possible), then it's an implicit any and you will receive a compilation-time error.
The most common case on any implicit any is in a variable declaration, such as let value;. There are two ways to avoid this:
Assign the variable to an implicitly identifiable type (let value = 5; or let value = workbook.getWorksheet();).
Explicitly type the variable (let value: number;)
No inheriting Office Script classes or interfaces
Classes and interfaces that are created in your Office Script cannot extend or implement Office Scripts classes or interfaces. In other words, nothing in the ExcelScript namespace can have subclasses or subinterfaces.
Incompatible TypeScript functions
Office Scripts APIs cannot be used in the following:
The JavaScript eval function is not supported for security reasons.
Restricted identifiers
The following words can't be used as identifiers in a script. They are reserved terms.
Excel
ExcelScript
console
Only arrow functions in array callbacks
Your scripts can only use arrow functions when providing callback arguments for Array methods. You cannot pass any sort of identifier or "traditional" function to these methods.
const myArray = [1, 2, 3, 4, 5, 6];
let filteredArray = myArray.filter((x) => {
return x % 2 === 0;
});
/*
The following code generates a compiler error in the Office Scripts Code Editor.
filteredArray = myArray.filter(function (x) {
return x % 2 === 0;
});
*/
Unions of ExcelScript types and user-defined types aren't supported
Office Scripts are converted at runtime from synchronous to asynchronous code blocks. The communication with the workbook through promises is hidden from the script creator. This conversion doesn't support union types that include ExcelScript types and user-defined types. In that case, the Promise is returned to the script, but the Office Script compiler doesn't expect it and the script creator can't interact with the Promise.
The following code sample shows an unsupported union between ExcelScript.Table and a custom MyTable interface.
function main(workbook: ExcelScript.Workbook) {
const selectedSheet = workbook.getActiveWorksheet();
// This union is not supported.
const tableOrMyTable: ExcelScript.Table | MyTable = selectedSheet.getTables()[0];
// `getName` returns a promise that can't be resolved by the script.
const name = tableOrMyTable.getName();
// This logs "{}" instead of the table name.
console.log(name);
}
interface MyTable {
getName(): string
}
Constructors don't support Office Scripts APIs and console statements
console statements and many Office Scripts APIs require synchronization with the Excel workbook. These synchronizations use await statements in compiled runtime version of the script. await is not supported in constructors. If you need classes with constructors, avoid using Office Scripts APIs or console statements in those code blocks.
The following code sample demonstrates this scenario. It generates an error that says failed to load [code] [library].
function main(workbook: ExcelScript.Workbook) {
class MyClass {
constructor() {
// Console statements and Office Scripts APIs aren't supported in constructors.
console.log("This won't print.");
}
}
let test = new MyClass();
}
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Scripts feedback
Office Scripts is an open source project. Select a link to provide feedback:
Learn how using TypeScript for JavaScript development can help you build more robust code, reduce runtime type errors, take advantage of modern features before they are available in JavaScript, and work better with development teams.