カスタム アドイン#

バージョン 0.22.0 で追加.

カスタム アドインとは、ひな型のxlwingsアドインを基に RunPython 関数やUDF（Windows限定）およびExcelリボンの有無を選択して作成するアドインです。カスタム アドインはWindowsおよびmacOSの両方で利用できます。

カスタム アドインのメリットは、VBAエディター上で ツール > 参照設定 で参照設定を追加することなく、RunPython関数やUDFがすべてのワークブックで簡単に利用できるようになることです。また、xlsm ファイルではなく、通常の xlsx ファイルでも使えるようになります。以降、このチュートリアルはxlwingsおよびその設定方法を既知のものとして進めます。

クイックスタート#

最初にコマンド ラインで以下のコマンドを実行してください（アドインをリボンなしで作成するには --ribbon フラグを除きます）:

$ xlwings quickstart myproject --addin --ribbon

実行後、クイックスタート フォルダーと同じようにPythonファイルとExcelファイルが生成されますが、今回のExcelは xlam フォーマット（Excelアドイン）になっています。

  • ExcelアドインをダブルクリックしExcelで開いてください

  • 空白のワークブックを追加（Windowsは Ctrl+N 、macOSは Command+N）してください。

次のように MyAddin リボン タブが表示されます:

_images/custom_ribbon_addin.png

The add-in and VBA project are currently always called myaddin, no matter what name you chose in the quickstart command. We'll see towards the end of this tutorial how we can change that, but for now we'll stick to it.

xlwingsアドインと比べて、カスタム アドインはアドイン自体に含まれる設定シートで追加的な設定を行えます。このシートを使えば、アドインのデフォルト設定を簡単に定義することができます。

Alt+F11 (Windows) または Option+F11 (macOS)で、VBAエディターを開きます。以下のスクリーンショットを参考に、アドイン プロジェクト内の ThisWorkbook を選択し、 IsAddin プロパティーを True から False に変更します:

_images/custom_addin_vba_properties.png

これで _myaddin.conf シートが表示されるようになりました（繰り返しですが myaddin の名前の変更方法はこのチュートリアルの最後で説明します）:

  • シート名を _myaddin.conf から myaddin.conf に変更し、シートによる設定を有効化します。

  • Interpreter_Win/_Mac または Conda を設定します（xlwingsの設定をそのまま使うことになるでしょう）

作業が終われば、VBAエディターに戻り、 ThisWorkbook を再度選択し、 IsAddin を True に戻し、VBAエディター上でアドインを保存します。Excelに戻り、 My Addin リボン タブの Run ボタンをクリックします。Pythonインタープリターの設定が適切なら、アクティブ ワークブックの A1 セルに Hello xlwings! が出力されます。

リボン メニューの変更#

リボン メニューやBackstageビューのボタンやアイテムを変更するには、 Office RibbonX Editor をダウンロードしインストールします。Office RibbonX EditorはWindows版のみですが、作成したリボンはmacOSでも機能します。Office RibbonX Editorでアドインを開き、ボタン等を定義するXMLコードを編集します。使い方は こちら のチュートリアルをご参照ください。デモ用の Run ボタンが呼び出している関数は、VBAエディター内の RibbonMyAddin VBAモジュールにあります。

UDFのインポート#

UDFをカスタム アドインに取り込むには、 xlwings モジュールの最後の方にある ImportPythonUDFsToAddin サブプロシージャーを実行します（サブプロシージャー内をクリックし、 F5 を押します）。関数名、引数、デコレーターのいずれかを変更するたびに、このサブプロシージャーを実行します。作成時に予め実行しておくことで、アドインのエンド ユーザーは改めて実行せずに済みます。

アドインで配布するのがUDFのみならリボン メニューは不要です。 quickstart コマンドを --ribbon フラグなしで実行することもできます。

設定#

先述のとおり、設定はxlwingsと同様に機能します。ですから、ユーザーに myaddin.conf シートをワークブックに追加してもらいデフォルトの設定を上書きしたり、 myaddin.conf ファイルをユーザーのホーム ディレクトリーに配置したりすることもできます。詳しくは アドインおよび設定 をご覧ください。

インストール#

カスタム アドインを永続的にインストールするには、xlwings CLIを使います:

$ xlwings addin install --file C:\path\to\your\myproject.xlam

しかし、インストールした場合には、UDF用のPythonコードをアドインが見つけられるよう PYTHONPATH を調整する必要があります（または、PythonコードをPythonが探せる場所に配置します---詳細は後述のデプロイをご覧ください）。このコマンドはカスタム アドインを XLSTART フォルダーにコピーします。このフォルダーは特別なフォルダーで、Excel起動時にフォルダー内のすべてのファイルが自動的に読み込まれます。

カスタム アドインの名前を変更#

このパートはやや厄介です。アドインの名前を MyAddin から Demo に変更してみましょう:

  • xlwings VBAモジュールで、 Public Const PROJECT_NAME As String = "myaddin" を Public Const PROJECT_NAME As String = "demo" に変更します。この行は最初の方の Declare ステートメントの直後にあります。

  • myaddin.conf シートで設定を行っていれば、シート名を demo.conf に変更します。

  • VBAプロジェクトを右クリックし MyAddin のプロパティ を選択後、 プロジェクト名 を MyAddin から Demo に変更します。

  • リボンを使用する場合、VBAモジュール名を RibbonMyAddin から RibbonDemo に変更します。VBAエディターでモジュールを選択し、 プロパティ ウィンドウから行います、ウィンドウが無い場合は、F4 を押します。

  • 先述のOffice RibbonX Editorでアドインを開き、XMLコード内に現れるすべての MyAddin を Demo に置換します。

最後に、Windowsエクスプローラーでファイル名を myproject.xlam から変更します。ですが、きっと既に適切な名前でquickstartコマンドを実行していることでしょうから、これは必要ないでしょう（訳注： 名前を変えるくらいならquickstartコマンドで最初から作り直しましょう）。

デプロイ#

xlwings PROのインストーラーを作成機能を使えば、最も簡単にカスタム アドインをエンドユーザーに配布することができます。この機能はすべての面倒を見てくれるため、エンドユーザーはインストーラーを文字通りダブル クリックするだけで済みます（Pythonをあらかじめインストールしておくことも、アドインの手作業でのインストールや設定の調整も必要ありません）。

難易度は高いですが配布を無料で行うには、イントーラーを自分でビルドするか、エンドユーザーにPythonとアドインをインストールしPythonコードを適切なディレクトリーに配置させなければなりません。その際、通常は以下のような設定の微調整を行います。例えば myaddin.conf シートでは:

  • Interpreter_Win/_Mac: エンドユーザーが既にPythonを利用中なら、環境変数を使って動的に適切なパスに変換することができます。例えば、ユーザーがAnacondaをデフォルトの場所にインストールしている場合、次の設定を使うことができます:

    Conda Path: %USERPROFILE%\anaconda3
Conda Env: base
Interpreter_Mac: $HOME/opt/anaconda3/bin/python

  • PYTHONPATH: Pythonのコードを、アドインと同じ XLSTART フォルダーに置くことはできないため、 PYTHONPATH 設定を調整し、Pythonコードを置くフォルダーを準備する必要があります。例えば、共有ドライブに設定したり、環境変数を利用してユーザーのホーム ディレクトリーに MyAddin フォルダーを作成してそこに保存することもできます。 それ以外にも、Pythonが探せるフォルダーにPythonコードを置くこともできます。例えば、Pythonのディストリビューションの site-packages フォルダーです --- pip でインストール可能なPythonのパッケージを作れば、簡単にそのようなフォルダーに配置できます。