チュートリアル: Excel でのカスタム関数の作成

SUM などの組み込み関数と共に JavaScript カスタム関数を提供する Excel アドインを構築します。 計算を実行し、Web からデータを取得し、リアルタイムの更新をワークシートにストリーミングする関数を作成します。

このチュートリアルでは、次の操作を行います。

  • Office アドイン用 Yeoman ジェネレーターを使用して、カスタム関数アドインを作成します。
  • あらかじめ用意されているカスタム関数を使用し、単純な計算を実行します。
  • Web からデータを取得するカスタム関数を作成します。
  • Web からデータをリアルタイムでストリーミングするカスタム関数を作成します。

前提条件

  • Node.js (最新の Active LTS バージョン)。 Node.js サイトにアクセスして、オペレーティング システムに適したバージョンをダウンロードしてインストールします。

  • 最新バージョンの Yeoman と Office アドイン用の Yeoman ジェネレーター。これらのツールをグローバルにインストールするには、コマンド プロンプトから次のコマンドを実行します。

    npm install -g yo generator-office

    注:

    Yeomanのジェネレーターを過去に取付けている場合でも、npmからのパッケージを最新のバージョンにすることをお勧めします。

  • Microsoft 365 サブスクリプションに接続されている Office (Office for the web を含む)。

    注:

    まだ Office をお持ちでない場合は、Microsoft 365 開発者プログラムを通じてMicrosoft 365 E5開発者サブスクリプションを受ける資格がある場合があります。詳細については、FAQ を参照してください。 または、 1 か月間の無料試用版にサインアップ するか、 Microsoft 365 プランを購入することもできます。

カスタム関数プロジェクトを作成する

カスタム関数アドインのコード プロジェクトを作成します。 Office アドイン用 Yeoman ジェネレーターは、事前構築済みのカスタム関数を使用してプロジェクトを設定して試します。 カスタム関数クイック スタートでプロジェクトを既に生成している場合は、そのプロジェクトを使用し、「 Web からデータを要求するカスタム関数を作成する」を参照してください。

注:

Yo Office プロジェクトを再作成すると、Office キャッシュに同じ名前の関数のインスタンスが既に存在するため、エラーが発生する可能性があります。 このエラーを回避するには、npm run startを実行する前に Office キャッシュをクリアします。

  1. 次のコマンドを実行し、Yeoman ジェネレーターを使用してアドイン プロジェクトを作成します。 プロジェクトを含むフォルダーが現在のディレクトリに追加されます。

    yo office

    注:

    yo officeコマンドを実行すると、Yeoman のデータ収集ポリシーと Office アドイン CLI ツールに関するプロンプトが表示される場合があります。 提供された情報を使用して、必要に応じてプロンプトに応答します。

    プロンプトが表示されたら、以下の情報を入力してアドイン プロジェクトを作成します。

    • プロジェクトの種類を選択します。Excel Custom Functions using a Shared Runtime
    • スクリプトの種類を選択します。JavaScript
    • アドインに何の名前を付けたいですか?My custom functions add-in

    Yeoman Office アドイン ジェネレーターのコマンド ライン インターフェイスは、カスタム関数プロジェクトのプロンプトを表示します。

    Yeoman ジェネレーターはプロジェクト ファイルを作成し、サポートする Node コンポーネントをインストールします。

  2. プロジェクトのルート フォルダーに移動します。

    cd "My custom functions add-in"

  3. プロジェクトをビルドします。

    npm run build

    注:

    Office アドインは、開発中であっても HTTP ではなく HTTPS を使用する必要があります。 npm run buildを実行した後に証明書のインストールを求められた場合は、Yeoman ジェネレーターで提供される証明書をインストールするプロンプトに同意します。

  4. Node.js で実行しているローカル Web サーバーを開始します。 Excel でカスタム関数アドインを試すことができます。

Windows または Mac 上の Excel でアドインをテストするコマンドは、プロジェクトの作成時によって異なります。 プロジェクトのpackage.json ファイルの "scripts" セクションに start:desktop スクリプトがある場合は、 npm run start:desktopを実行します。 それ以外の場合は、 npm run startを実行します。 ローカル Web サーバーが起動し、アドインが読み込まれた状態で Excel が開きます。

注:

  • Office アドインでは、開発中でも HTTP ではなく HTTPS を使用する必要があります。 次のいずれかのコマンドを実行した後に証明書をインストールするように求められた場合は、Yeoman ジェネレーターが提供する証明書をインストールするプロンプトに同意します。 変更を行うには、管理者としてコマンド プロンプトまたはターミナルを実行する必要がある場合もあります。

  • 初めてコンピューターで Office アドインを開発する場合は、コマンド ラインで、Microsoft Edge WebView にループバックの除外を許可するように求められる場合があります (「Microsoft Edge WebView の localhost ループバックを許可する」)。 メッセージが表示されたら、「 Y 」と入力して除外を許可します。 除外を許可するには管理者特権が必要であることに注意してください。 許可されたら、(マシンから除外を削除しない限り) 今後 Office アドインをサイドロードするときに、除外を求められません。 詳細については、 Office アドインを読み込むか Fiddler を使用する場合は、「localhost からこのアドインを開くことができない」を参照してください。

    Microsoft Edge WebView にループバックの除外を許可するコマンド ラインのプロンプト。

  • Yeoman ジェネレーターを初めて使用して Office アドインを開発すると、既定のブラウザーでウィンドウが開き、Microsoft 365 アカウントにサインインするように求められます。 サインイン ウィンドウが表示されない場合にサイドローディングまたはログイン タイムアウト エラーが発生した場合は、 atk auth login m365を実行します。

事前構築済みのカスタム関数を試す

プロジェクトには、 ./src/functions/functions.jsに事前構築済みのカスタム関数が含まれています。 ./manifest.xml ファイルは、Excel の関数へのアクセスに使用するCONTOSO名前空間に割り当てます。

次に、次の手順を実行して、 ADD カスタム関数を試します。

  1. Excel で、任意のセルに移動し、=CONTOSO と入力します。 CONTOSO 名前空間にあるすべての関数がオートコンプリート メニューに一覧表示されます。

  2. セルに「 =CONTOSO.ADD(10,200) 」と入力し、[Enter] を選択 します。

ADDカスタム関数は、210を返します。

オートコンププリート メニューで CONTOSO 名前空間を使用できない場合、次の手順でアドインを Excel に登録します。

  1. [ ホーム>アドイン] を選択し、[ その他の設定] を選択します。

  2. [ Office アドイン ] ダイアログで、[ マイ アドインのアップロード] を選択します。

  3. [参照...] を選択し、Yeoman ジェネレーターによって作成されたプロジェクトのルート ディレクトリに移動します。

  4. manifest.xml ファイルを選択し、[開く] を選択し、[アップロード] を選択します。

  5. 新しい関数をお試しください。 セル B1 にテキスト =CONTOSO を入力します 。GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") を 押して Enter キーを押 します。 セル B1 の結果は Excel-Custom-Functions Github リポジトリ に与えられた現在の星の数です。

注:

アドインをサイドローディングするときにエラーが発生した場合は、この記事の 「トラブルシューティング 」セクションを参照してください。

Web からデータを要求するカスタム関数を作成する

Web からのデータの統合は、カスタム関数を使用して Excel を拡張する優れた方法です。 GitHub リポジトリの星の数を取得する getStarCount カスタム関数を作成します。

  1. マイ カスタム関数アドイン プロジェクトで、コード エディターで ./src/functions/functions.js を開きます。

  2. functions.jsで、次のコードを追加します。

    /**
 * Gets the star count for a GitHub repository.
 * @customfunction
 * @param {string} userName GitHub user or organization name.
 * @param {string} repoName GitHub repository name.
 * @returns {number} Number of stars given to the GitHub repository.
 */
async function getStarCount(userName, repoName) {
  try {
    const url = `https://api.github.com/repos/${userName}/${repoName}`;
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(response.statusText);
    }

    const jsonResponse = await response.json();
    return jsonResponse.stargazers_count;
  } catch (error) {
    throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, String(error));
  }
}

  3. 次のコマンドを実行してプロジェクトを再構築します。

    npm run build

  4. Excel のアドインを再登録するには、次の手順を完了します (Web、Windows または Mac 上の Excel の場合)。 新しい関数を使用できるようにするには、これらの手順を完了する必要があります。

  1. Excel を閉じて再び開きます。

  2. [Excel] リボンで、[ホーム] >[アドイン] を選択します。

  3. [ 開発者アドイン ] セクションで、[ マイ カスタム関数アドイン ] を選択して登録します。

    [マイ カスタム関数アドイン] ボタンが強調表示されている、アクティブなアドインを表示する [マイ アドイン] ダイアログ。

  4. セル B1 に「 =CONTOSO.GETSTARCOUNT("OfficeDev", "Office-Add-in-Samples")」と入力し、[Enter] を選択 します。 セルには、 Office アドイン サンプル リポジトリの現在の星の数が表示されます。

注:

アドインをサイドローディングするときにエラーが発生した場合は、この記事の 「トラブルシューティング 」セクションを参照してください。

非同期でデータをストリーミングするカスタム関数を作成する

getStarCount関数は、特定の時点の星の数を返します。 一方、ストリーミング関数はセルを繰り返し更新できます。 これには、 関数を呼び出したセルを表す invocation パラメーターが含まれています。

次の例には、2 つの関数が含まれています。 currentTime は現在の時刻を文字列として返します。 ストリーミング clock 関数は、 invocation.setResult を呼び出してセルを 1 秒ごとに更新し、excel が関数を取り消したときに invocation.onCanceled を使用してタイマーを停止します。

マイ カスタム関数アドイン プロジェクトには、./src/functions/functions.jsにこれらの関数が既に含まれています。

/**
 * Returns the current time
 * @returns {string} String with the current time formatted for the current locale.
 */
function currentTime() {
  return new Date().toLocaleTimeString();
}

/**
 * Displays the current time once a second.
 * @customfunction
 * @param {CustomFunctions.StreamingInvocation<string>} invocation Custom function invocation
 */
function clock(invocation) {
  const timer = setInterval(() => {
    const time = currentTime();
    invocation.setResult(time);
  }, 1000);

  invocation.onCanceled = () => {
    clearInterval(timer);
  };
}

ストリーミング関数を試すには、セル C1 に「=CONTOSO.CLOCK()」と入力し、[Enter] を選択します。 セルには現在の時刻が表示され、1 秒ごとに更新されます。 Web からリアルタイム データを要求する関数でも、同じタイマー パターンを使用できます。

トラブルシューティング

チュートリアルを複数回実行すると、問題が発生する可能性があります。 Office キャッシュに同じ名前を持つ関数のインスタンスが既に存在する場合、アドインのサイドロード時にエラーが発生します。

この競合を防ぐには、npm run startを実行する前に Office キャッシュをクリアします。 npm プロセスが既に実行されている場合は、「 npm run stop」と入力し、Office キャッシュをクリアしてから npm を再起動します。

Excelで '関数のインストール中にエラーが発生しました' というタイトルのエラー メッセージが表示されます。これには、'同じ名前を持つカスタム関数が既に存在するため、このアドインはインストールされませんでした' というテキストが含まれます。

次の手順

新しいカスタム関数プロジェクトを作成し、事前構築済み関数を試し、Web からデータを要求するカスタム関数を作成し、データをストリーミングするカスタム関数を作成しました。 次に、 作業ウィンドウでカスタム関数データを共有する方法について説明します。

  • Last updated on