Excel カスタム関数の開発を開始する

[アーティクル]
10/02/2024

カスタム関数機能を使用すると、開発者は、アドインの一部としてカスタム関数を JavaScript または TypeScript で定義することによって、新しい関数を Excel に追加できます。 Excel のユーザーは、SUM() など、Excel のすべてのネイティブ関数にアクセスするとの同じようにカスタム関数にアクセスできます。

前提条件

Node.js (最新 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 プランを購入することもできます。

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

はじめに、Yeoman ジェネレーターを使って、カスタム関数プロジェクトを作成します。これにより、カスタム関数のコーディングを開始するための正しいフォルダー構造、ソースファイル、依存関係によるプロジェクトがセットアップされます。

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

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

プロンプトが表示されたら、以下の情報を入力してアドインプロジェクトを作成します。
- プロジェクトの種類を選択します。Excel Custom Functions using a Shared Runtime
- スクリプトの種類を選択します。JavaScript
- アドインに何の名前を付けたいですか?My custom functions add-in
Yeoman ジェネレーターはプロジェクトファイルを作成し、サポートしているノードコンポーネントをインストールします。
Yeoman ジェネレーターによりプロジェクトの作業に関する手順がコマンドライン内にいくつか示されますが、これらは無視し、ここに書かれている手順に従ってください。プロジェクトのルートフォルダーに移動します。
```
cd "My custom functions add-in"
```
プロジェクトをビルドします。
```
npm run build
```
Node.js で実行しているローカル Web サーバーを開始します。 Excel でカスタム関数アドインを試すことができます。アドインの作業ウィンドウを開くように求められる場合がありますが、これは省略可能です。カスタム関数はアドインの作業ウィンドウを開かなくても実行できます。

Web 版 Excel
Windows または Mac 上の Excel

アドインを Web 版 Excel で試すには、次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動します。 "{url}" を、アクセス許可を持っている OneDrive または SharePoint ライブラリ上の Excel ドキュメントの URL に置き換えます。

注:

Mac で開発している場合は、 {url} を単一引用符で囲みます。 Windows ではこれを行 わないでください 。

npm run start:web -- --document {url}

次に例を示します。

npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

ドキュメントにアドインがサイドロードされない場合は、「アドインを手動でサイドロードしてOffice on the webする」の手順に従って手動でサイドロードします。

注:

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

Windows または Mac の Excel でアドインをテストするには、次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動し、アドインが読み込まれたときに Excel が開きます。

npm run start:desktop

注:

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

既製のカスタム関数を試す

Yeoman ジェネレーター使用して作成したカスタム関数プロジェクトには既製のカスタム関数がいくつか含まれており、これらは ./src/functions/functions.js ファイル内で定義されています。カスタム関数はすべて CONTOSO 名前空間に属するということは、プロジェクトのルートディレクトリの ./manifest.xml ファイルで指定されています。

Excel ブックで次の手順を実行し、ADD カスタム関数を試してみてください。

セルを 1 つ選択し、「=CONTOSO」と入力します。 CONTOSO 名前空間にあるすべての関数がオートコンプリートメニューに一覧表示されます。
セル内に「=CONTOSO.ADD(10,200)」という値を入力して Enter キーを押し、入力パラメーターとして数値「10」と「200」を指定して、CONTOSO.ADD 関数を実行します。

ADD カスタム関数によって、入力パラメーターとして指定した 2 つの数字の合計が計算されます。「=CONTOSO.ADD(10,200)」と入力して Enter キーを押すと、210 という結果が生成されるはずです。

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

Web 版 Excel
Excel on Windows または Mac

Excel で[ ホーム>アドイン]、[ その他のアドイン] の順に選択します。
[ MY ADD-INS ] タブで、[ マイアドインの管理 ] を選択し、[ マイアドインのアップロード] を選択します。
[参照...] を選択し、Yeoman ジェネレーターによって作成されたプロジェクトのルートディレクトリに移動します。
manifest.xml ファイルを選択し、[開く] を選択し、[アップロード] を選択します。
新しい関数をお試しください。セル B1 で、テキスト =CONTOSO.GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") を入力し、Enter キーを押します。セル B1 の結果は Excel-Custom-Functions Github リポジトリに与えられた現在の星の数です。

ローカル Web サーバーを停止してアドインをアンインストールする場合は、該当する手順に従います。

サーバーを停止するには、次のコマンドを実行します。 npm startを使用した場合は、次のコマンドによってアドインもアンインストールされます。
```
npm stop
```
アドインを手動でサイドロードした場合は、「サイドロードされたアドインを削除する」を参照してください。

次の手順

これで、カスタム関数が Excel アドイン内に正常に作成されました。次は、ストリーミングデータ機能を使用してより複雑なアドインを作成してください。カスタム関数を使用した Excel アドインのチュートリアルの次の手順を確認するには、次のリンクをクリックしてください。

Excel カスタム関数アドインのチュートリアル

トラブルシューティング

「開発環境のセットアップ」の手順に従って、環境が Office 開発の準備ができていることを確認します。
一部のサンプルコードでは、ES6 JavaScript を使用しています。これは、Trident (インターネットエクスプローラー 11) ブラウザーエンジンを使用する古いバージョンの Office と互換性がありません。アドインでこれらのプラットフォームをサポートする方法については、「古い Microsoft Webview と Office バージョンをサポートする」を参照してください。開発に使用する Microsoft 365 サブスクリプションがまだない場合は、Microsoft 365 開発者プログラムを通じてMicrosoft 365 E5開発者サブスクリプションを受ける資格があります。詳細については、FAQ を参照してください。または、 1 か月間の無料試用版にサインアップするか、 Microsoft 365 プランを購入することもできます。

Yo Office が実行する自動 npm install ステップが失敗する可能性があります。 npm startを実行しようとしたときにエラーが表示された場合は、コマンドプロンプトで新しく作成したプロジェクトフォルダーに移動し、npm installを手動で実行します。 Yo Office の詳細については、「 Yeoman ジェネレーターを使用して Office アドインプロジェクトを作成する」を参照してください。

クイックスタートを複数回実行すると、問題が発生する場合があります。 Office キャッシュに同じ名前を持つ関数のインスタンスが既に存在する場合、アドインのサイドロード時にエラーが発生します。これを防ぐには、npm run startを実行する前に Office キャッシュをクリアし、アドインを再起動する前にnpm stopを実行してください。

次の方法で共有