4.4. アクションアイテムを実装する¶
この章では、アクションアイテムの実装方法について解説します。
4.4.1. アクションアイテム本体のファイルの実装¶
4.4.1.1. アクションアイテム本体のクラスの実装¶
まずは、アクションアイテム本体のファイルを実装していきます。
{VSCODE_HOME}/src/public/actions に、アクションアイテム本体を実装するファイル(.tsファイル)を作成します。
ここでは、MyShowAlertActionItem.ts というファイル名で作成しています。
このファイルに、IUIContainerActionItemCore インタフェースを実装した、アクションアイテムのクラスを定義します。
// パラメータの型を定義します。
type ParameterDefinition = {
// TODO
};
export class MyShowAlertActionItem implements IUIContainerActionItemCore {
// アクションアイテム名を返却するメソッドです。
// { アクションアイテムのクラス名 } .name のように、アクションアイテムのクラス名を返却してください。
// アクションアイテム名が他のアクションアイテム名と重複すると、正常に動作しない恐れがあります。
public get actionTypeName(): string {
return MyShowAlertActionItem.name;
}
// アクションアイテムの説明ラベルのメッセージキーを返却するメソッドです。
public get messageKey(): string {
return 'CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem';
}
// アクションアイテムのパラメータの定義を返却するメソッドです。
public get parameterDefinition(): ParameterDefinition {
// TODO
return {};
}
// アクションアイテムが実行されたときの処理を記述します。
public async run(
context: IUIContainerActionContext,
container: IUIContainer,
component: IUIComponent,
parameters: IUIContainerActionParameterAccessor<ParameterDefinition>
): Promise<void> {
// TODO
}
}
4.4.2. run メソッドを実装する¶
アクションアイテム本体の run メソッド内でアクションアイテムが実行されたときの処理を記述します。
例として、 window.alert を実行する場合の実装を以下に示します。
// アクションアイテムが実行されたときの処理を記述します。
public async run(
context: IUIContainerActionContext,
container: IUIContainer,
component: IUIComponent,
parameters: IUIContainerActionParameterAccessor<ParameterDefinition>
): Promise<void> {
window.alert('any messages');
}
4.4.3. パラメータの利用方法¶
アクションアイテムを作成する際は、任意のパラメータを付与することも可能です。
window.alert の引数にメッセージを指定可能にするため、アクションアイテムのパラメータを追加で実装します。
以下の手順で実装します。
ParameterDefinition型を定義し、その中で、必要なプロパティを UIContainerActionParameterDefinitionType 型で宣言します。
例えば message1、message2 というプロパティが必要な場合、まずは以下のように宣言します。// パラメータの型を定義します。 type ParameterDefinition = { // message1 と message2 のパラメータを持ちます。 message1: UIContainerActionParameterDefinitionType; message2: UIContainerActionParameterDefinitionType; };アクションアイテム本体のクラスの parameterDefinition メソッド内で、パラメータの定義を返却します。
ParameterDefinition に従ってプロパティの定義を記述します。// アクションアイテムのパラメータの定義を返却するメソッドです。 public get parameterDefinition(): ParameterDefinition { // ParameterDefinition 型で返却する必要があります。 return { message1: { type: 'literal', // 固定文字列で指定したい場合 messageKey: 'CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem.message1', // パラメータのラベル }, message2: { type: 'variable-all', // 変数でしたい場合 messageKey: 'CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem.message2', // パラメータのラベル }, }; }コラム
parameterDefinition メソッドの返り値について
parameterDefinition メソッドの返り値は、ParameterDefinition 型(UIContainerActionParameterDefinitionType 型のプロパティを持つオブジェクト)にする必要があります。UIContainerActionParameterDefinitionType の実装は以下の通りです。parameterDefinition メソッドでは、この形式に従って必要な定義を記述してください。? がついている定義は省略可能です。type UIContainerActionParameterDefinitionType = { /** パラメータ定義タイプ */ readonly type: UIContainerActionParameterCandidateType; /** パラメータ名を示すメッセージキー */ readonly messageKey: string; /** パラメータの選択候補 */ readonly candidate?: { readonly displayName: string; readonly value: string; }[]; }; type UIContainerActionParameterCandidateType = | 'variable-input' /** 定数・入力 */ | 'variable-output' /** 変数 */ | 'variable-all' /** 変数・定数・入力 */ | 'literal' /** 直接入力 */ | 'label-target' /** ラベル定義 */ | 'label' /** アクション内ラベル */ | 'action' /** アクション(自分を除く) */ | 'page' /** コンテナページ */ | 'table-select' /** テーブル */ | 'checkbox' /** チェックボックス */ | 'javascript' /** JavaScript エディタ */ | 'hidden'; /** 隠しパラメータ */run メソッド内で window.alert の引数にメッセージを指定可能にするため、アクションアイテムのパラメータを追加で実装します。
// アクションアイテムが実行されたときの処理を記述します。 public async run( context: IUIContainerActionContext, container: IUIContainer, component: IUIComponent, parameters: IUIContainerActionParameterAccessor<ParameterDefinition> ): Promise<void> { // アクションアイテムのパラメータを文字列で取得します。 const message1 = parameters.getParameter('message1').toArgument(container).toString(); const message2 = parameters.getParameter('message2').toArgument(container).toString(); window.alert(message1 + '\n' + message2); }
4.4.4. 実装したクラスの登録¶
アクションアイテム本体のクラスを登録する処理を {VSCODE_HOME}/src/index.ts に実装します。
UIContainerActionItemRepository クラスのメソッドを利用します。
import {MyShowAlertActionItem} from './public/actions/MyShowAlertActionItem';
// アクションアイテムのリポジトリは以下のように取得します。
const actionItemRepository = window.imHichee.UIContainerActionItemRepository;
// アクションアイテムのカテゴリを登録します。
// 新たにカテゴリを追加したい場合には UIContainerActionItemRepository.registerCategory() を使用して、カテゴリを追加してください。
// 一つ目の引数 id にはカテゴリのID(任意)、二つ目の引数にはアクションアイテムの登録オプションを指定可能です。
// sortNumber でカテゴリを表示させる際の優先順位を指定可能です。
// カテゴリは sortNumber を基準に昇順で表示されます。
actionItemRepository.registerCategory('programming-sample', {sortNumber: 120});
// 作成したアクションアイテムをカテゴリに登録します。
// categoryId には登録先のカテゴリ名、sortNumber はカテゴリ内でアクションアイテムを表示させる際の優先順位を指定できます。
// sortNumber を基準に昇順で表示されます。
actionItemRepository.registerClass(MyShowAlertActionItem, {
categoryId: 'programming-sample',
sortNumber: 0,
});
4.4.5. プロパティファイルの実装¶
アクションアイテムのラベル、新たに追加したカテゴリの名称、ヘルプを画面上に表示するために、プロパティファイルを実装する必要があります。
必要な言語に応じて、{VSCODE_HOME}/src/public/messages 配下にプロパティファイルを作成します。
日中英の3ロケール(言語)に対応する場合は、以下の4ファイルが必要です。不要なロケールはプロパティファイルを作成する必要はありません。
- caption_ja.properties
日本語のプロパティファイルです。
- caption_en.properties
英語のプロパティファイルです。
- caption_zh_CN.properties
中国語のプロパティファイルです。
- caption.properties
対応するロケールのプロパティが欠落している場合に参照されるプロパティファイルです。
それぞれのプロパティは以下のように記述します。
- アクションアイテムのラベル:CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.{アクションアイテム本体のクラスに利用したメッセージ}={表示したいラベルの内容}
- アクションアイテムのカテゴリ名:CAP.Z.IWP.HICHEE.ACTION.ITEM.CATEGORY.NAME.{index.ts内で指定したカテゴリID}={表示したいカテゴリ名}
- アクションアイテムのヘルプ:CAP.Z.IWP.HICHEE.ACTION.ITEM.DESCRIPTION.{アクションアイテムのクラス名}={表示したいヘルプの内容}
日本語のプロパティファイルを記述する際の例を以下に示します。(先頭に#をつけて、コメントを記述することも可能です。)
# アクションアイテムの説明ラベル
CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem=アラートでメッセージを表示
# アクションアイテムのパラメータラベル
CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem.message1=メッセージ1
CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem.message2=メッセージ2
# アクションアイテム - カテゴリ名
CAP.Z.IWP.HICHEE.ACTION.ITEM.CATEGORY.NAME.programming-sample=プログラミングガイドサンプル
# アクションアイテム - ヘルプ
CAP.Z.IWP.HICHEE.ACTION.ITEM.DESCRIPTION.MySampleElement=サンプルアクションアイテムです。
なお、以下のようにアクションアイテムのラベルに {パラメータ名} を埋め込むことにより、「アラートでメッセージ○と○を表示」のように穴埋め形式でラベルを表示させることが可能です。
# アクションアイテムの説明ラベル
CAP.Z.IWP.HICHEE.ACTION.ITEM.LABEL.MyShowAlertActionItem=アラートでメッセージ{message1}と{message2}を表示
注意
アクションアイテムの命名について
アクションアイテムのクラス名が(IM-BloomMaker 標準のアクションアイテムも含めて)複数のアクションアイテムで重複すると、正常に動作しないため、一意なクラス名を付けるようにしてください。
2020 Spring(Yorkshire) 時点の、既存のアクションアイテムのクラス名の一覧は、「付録) 2020 Spring(Yorkshire) 時点のアクションアイテムのクラス名一覧」を参照してください。
また、2020 Spring(Yorkshire) 以降のリリースで追加されるアクションアイテムに関しては、すべてクラス名の先頭に Im が付与されます。
独自のアクションアイテムを実装する際は、独自の接頭辞を付与するなどの方法で、クラス名の重複を回避してください。
アクションアイテムの作成に必要な作業は以上です。
「bundleの生成」に戻って残りの作業を行うことで、実装したアクションアイテムを利用できます。