Ограничения TypeScript в сценариях Office

В сценариях Office используется язык TypeScript. По большей части любой код TypeScript или JavaScript будет работать в сценариях Office. Однако редактор кода применяет несколько ограничений, чтобы обеспечить согласованную работу скрипта с книгой Excel.

Нет типа "any" в сценариях Office

Запись типов в TypeScript необязательна, так как типы могут быть выведены. Однако для сценариев Office требуется, чтобы переменная не могла иметь тип any. Явные и неявные any не допускаются в сценариях Office. Эти случаи сообщаются как ошибки.

Явные any

Нельзя явно объявить переменную типа any в сценариях Office (т. е let value: any;. ). Тип any вызывает проблемы при обработке в Excel. Например, необходимо знать, Range что значением является string, numberили boolean. Вы получите ошибку во время компиляции (ошибку перед выполнением скрипта), если какая-либо переменная явно определена any как тип в скрипте.

На предыдущем снимке экрана указано, [2, 14] Explicit Any is not allowed что строка 2, столбец #14 определяет any тип. Это поможет найти ошибку.

Чтобы обойти эту проблему, всегда определите тип переменной. Если вы не знаете тип переменной, можно использовать тип объединения. Это может быть полезно для переменных, которые содержат Range значения, которые могут иметь тип string, numberили boolean (тип для Range значений является объединением: string | number | boolean).

Неявные any

Типы переменных TypeScript можно определить неявно . Если компилятору TypeScript не удается определить тип переменной (из-за того, что тип не определен явным образом или вывод типа недоступен), это неявно any , и вы получите ошибку во время компиляции.

Наиболее распространенный случай для любого неявного any — это объявление переменной, например let value;. Избежать этого можно двумя способами:

• Назначьте переменную неявно идентифицируемому типу (let value = 5; или let value = workbook.getWorksheet();).
• Явным образом введите переменную (let value: number;)

Отсутствуют наследующие классы или интерфейсы сценариев Office

Классы и интерфейсы, созданные в скрипте Office, не могут расширять или реализовывать классы или интерфейсы скриптов Office. Иными словами, ничто в ExcelScript пространстве имен не может иметь подклассы или подинтерфейсы.

Несовместимые функции TypeScript

API сценариев Office нельзя использовать в следующих случаях:

• Функции генератора
• Array.sort

eval не поддерживается

Функция eval JavaScript не поддерживается по соображениям безопасности.

Ограниченные идентификаторы

Следующие слова не могут использоваться в качестве идентификаторов в скрипте. Это зарезервированные условия.

• Excel
• ExcelScript
• console

Только функции со стрелками в обратных вызовах массива

Скрипты могут использовать функции со стрелками только при предоставлении аргументов обратного вызова для методов Array . Эти методы не могут передавать какой-либо идентификатор или "традиционную" функцию.

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;
  });
*/

ExcelScript Объединения типов и определяемых пользователем типов не поддерживаются

Скрипты Office преобразуются во время выполнения из синхронных в асинхронные блоки кода. Связь с книгой через обещания скрыта от создателя сценария. Это преобразование не поддерживает типы объединения , включающие ExcelScript типы и определяемые пользователем типы. В этом случае Promise объект возвращается в скрипт, но компилятор скрипта Office не ожидает его, и создатель скрипта не может взаимодействовать с Promise.

В следующем примере кода показано неподдерживаемое объединение между ExcelScript.Table и пользовательским MyTable интерфейсом.

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
}

Конструкторы не поддерживают API и console инструкции сценариев Office

console Инструкции и многие API скриптов Office требуют синхронизации с книгой Excel. Эти синхронизации используют await инструкции в скомпилированной версии среды выполнения скрипта. await не поддерживается в конструкторах. Если вам нужны классы с конструкторами, избегайте использования API или console инструкций скриптов Office в этих блоках кода.

Следующий пример кода демонстрирует этот сценарий. Он создает ошибку с сообщением 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();
}

Предупреждения о производительности

Анализатор редактора кода выдает предупреждения, если скрипт может иметь проблемы с производительностью. Варианты и способы их решения описаны в статье Повышение производительности сценариев Office.

Вызовы внешних API

Дополнительные сведения см. в разделе Поддержка внешних вызовов API в скриптах Office .

См. также

• Основы сценариев Office в Excel
• Повышение производительности сценариев Office