スクリプトのユーザー入力を取得する

  • [アーティクル]

スクリプトにパラメーターを追加すると、他のユーザーはコードを編集することなく、スクリプトのデータを提供できます。 スクリプトがリボンまたはボタンを介して実行されると、入力を求めるプロンプトが表示されます。

パラメーターを含むスクリプトの実行時にユーザーに表示されるダイアログ ボックス。

重要

現時点では、パラメーター化されたスクリプトのデータの入力を求めるメッセージが表示されるのは、Web ユーザーの 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 parameters: スクリプトにデータを渡す

すべてのスクリプト入力は、main 関数の追加パラメーターとして指定されます。 必須の workbook: ExcelScript.Workbook パラメーターの後に新しいパラメーターが追加されます。 たとえば、入力として名前を表す string をスクリプトで受け入れるようにする場合は、main 署名を function 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"にのみできます。 スクリプトを実行すると、ユーザーはこれら 2 つのオプションを含むドロップダウン リストを取得します。

スクリプトを文書化する

JSDoc 標準に従うコード コメントは、スクリプトの実行時にユーザーに表示されます。 説明に含める詳細が多いほど、他のユーザーがスクリプトに簡単にアクセスできるようになります。 各入力パラメーターの目的と、制限または制限について説明します。 次のサンプル JSDoc は、taxRate というnumber パラメーターを使用してスクリプトを文書化する方法を示しています。

/**
 * 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" | 5ではなく"Left" | "Right"など) に属するリテラルの和集合である場合に許可されます。

  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})

関連項目