次の方法で共有

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

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

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

シナリオ例: 大きな値を強調表示する

次の例は、ユーザーから数値と文字列を受け取るスクリプトを示しています。 テストするには、空のブックを開き、いくつかのセルに数値を入力します。

/**
 * 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 をスクリプトで受け入れるようにする場合は、main 署名を function main(workbook: ExcelScript.Workbook, name: string) に変更します。

ユーザーがパラメーター化されたスクリプトを使用してブックをインポートできるようにするには、ブックを受け入れる各パラメーターに 2 次元配列を使用します。 パラメーターには、 string 型または number型を指定できます。 次の例は、両方のパラメーターのブックのインポートを受け入れるスクリプトを作成する方法を示しています。

/**​
 * This script generates a monthly sales report.​
 * @param productData The product data for this month.
 * @param salesData The sales data for this month.​
 */
function main(workbook: ExcelScript.Workbook, productData: string[][], salesData: string[][]) {
    // Code to process data goes here.
    // Both the `productData` and `salesData` parameters accept workbook imports.
}​

オプションのパラメーター

省略可能なパラメーターでは、ユーザーが値を指定する必要はありません。 これは、スクリプトに既定の動作があるか、またはこのパラメーターが特殊なケースでのみ必要であることを意味します。 これらは、省略可能な修飾子?を使用してスクリプト内で示されます。 たとえば、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})

関連項目

  • Last updated on