Поделиться через

Получение пользовательских входных данных для сценариев

  • Статья

Добавление параметров в скрипт позволяет другим пользователям предоставлять данные для скрипта без необходимости изменять код. При запуске скрипта с помощью ленты или кнопки появляется запрос на ввод.

Диалоговое окно, отображаемое пользователями при выполнении скрипта с параметрами.

Важно!

В настоящее время только пользователям Excel в Интернете будет предложено ввести данные для параметризованных скриптов. Потоки Power Automate также поддерживают предоставление данных скриптам с помощью параметров.

Пример. Выделение больших значений

В следующем примере показан скрипт, который принимает число и строку от пользователя. Чтобы протестировать его, откройте пустую книгу и введите несколько чисел в несколько ячеек.

/**
 * This script applies a background color to cells over a certain value.
 * @param highlightThreshold The value used for comparisons.
 * @param color A string representing the color to make the high value cells. 
 *   This must be a color code representing the color of the background, 
 *   in the form #RRGGBB (e.g., "FFA500") or a named HTML color (e.g., "orange").
 */
function main(
  workbook: ExcelScript.Workbook, 
  highlightThreshold: number, 
  color: string) {
    // Get the used cells in the current worksheet.
    const currentSheet = workbook.getActiveWorksheet();
    const usedRange = currentSheet.getUsedRange();
    
    const rangeValues = usedRange.getValues();
    for (let row = 0; row < rangeValues.length; row++) {
        for (let column = 0; column < rangeValues[row].length; column++) {
          if (rangeValues[row][column] >= highlightThreshold) {
              usedRange.getCell(row, column).getFormat().getFill().setColor(color);
          }
        }
    }
}

main параметры: передача данных в скрипт

Все входные данные скрипта указываются в качестве дополнительных main параметров для функции. После обязательного workbook: ExcelScript.Workbook параметра добавляются новые параметры. Например, если вы хотите, чтобы скрипт принимал string , который представляет имя в качестве входных данных, необходимо изменить подпись на mainfunction main(workbook: ExcelScript.Workbook, name: string).

Необязательные параметры

Необязательные параметры не требуют, чтобы пользователь предоставлял значение. Это означает, что скрипт имеет поведение по умолчанию или этот параметр требуется только в угловом случае. Они обозначаются в скрипте необязательным модификатором?. Например, параметр function main(workbook: ExcelScript.Workbook, Name?: string) является Name необязательным.

Значения параметров по умолчанию

Значения параметров по умолчанию автоматически заполняют поле действия значением. Чтобы задать значение по умолчанию, присвойте параметру в сигнатуре main значение. Например, в function main(workbook: ExcelScript.Workbook, location: string = "Seattle") параметре location есть значение "Seattle" , если не указано что-то другое.

Помогите другим пользователям, использующим ваш сценарий, в своем потоке, предоставив список допустимых вариантов параметров. Если скрипт использует небольшое подмножество значений, создайте параметр, представляющий собой эти литеральные значения. Для этого объявив тип параметра объединением значений литерала. Например, в function main(workbook: ExcelScript.Workbook, location: "Seattle" | "Redmond") параметре location может быть "Seattle" только или "Redmond". При выполнении скрипта пользователи получают раскрывающийся список с этими двумя параметрами.

Документирование скрипта

Примечания кода, которые соответствуют стандартам JSDoc , будут отображаться пользователям при выполнении скрипта. Чем больше сведений вы вложите в описания, тем проще будет для других в скриптах. Опишите назначение каждого входного параметра и любые ограничения или ограничения. В следующем примере JSDoc показано, как документировать скрипт с number помощью параметра с именем taxRate.

/**
 * A script to apply the current tax rate to sales figures.
 * @param taxRate The current sales tax rate in the region as a decimal number (enter 12% as .12).
 */
function main(workbook: ExcelScript.Workbook, taxRate: number)

Примечание.

Вам не нужно документировать ExcelScript.Workbook параметр в каждом скрипте.

Ограничения типов

При добавлении входных параметров и возвращаемых значений учитывайте следующие ограничения и ограничения.

  1. Первый параметр должен иметь тип ExcelScript.Workbook. Имя параметра не имеет значения.

  2. Типы string, number, boolean, unknownи object.

  3. Поддерживаются массивы (и []Array<T> стили) ранее перечисленных типов. Также поддерживаются вложенные массивы.

  4. Типы объединения разрешены, если они являются объединением литерал, принадлежащих к одному типу (например, , а "Left" | "Right"не "Left" | 5).

  5. Типы объектов допускаются, если они содержат свойства типа string, number, boolean, поддерживаемые массивы или другие поддерживаемые объекты. В следующем примере показаны вложенные объекты, которые поддерживаются в качестве типов параметров.

    // The Employee object is supported because Position is also composed of supported types.
interface Employee {
    name: string;
    job: Position;
}

interface Position {
    id: number;
    title: string;
}

  6. Объекты должны иметь определение интерфейса или класса в скрипте. Объект также можно определить анонимно, как показано в следующем примере.

    function main(workbook: ExcelScript.Workbook, contact: {name: string, email: string})

См. также