Message Channel APIによる連携アプリケーションの開発
Sheetコンポーネントは、SalesforceプラットフォームのLightning Message Serviceの仕組みを通じて、配置されたLightningページ上の他のLightningコンポーネントおよびVisualforceページと相互に連携できます。これにより、Sheetコンポーネント内でのユーザのアクションに連動してページ内の要素を更新したり、逆にページのアクションにしたがってSheetコンポーネントの内容を更新するアプリケーションを作成することが可能です。
イベントの発火とサブスクリプション
Sheetコンポーネントでのアクションの内容は、外部のプログラムへイベントとして通知することができます。カスタムのプログラムではこのイベントが発行されるMessage Channelをサブスクライブすることにより、Sheetでの動作と連動できます。
Lightning Webコンポーネントの場合、Sheetコンポーネントのイベントをサブスクライブするコードは以下のようになります。
import { LightningElement, wire } from "lwc";
import {
subscribe,
unsubscribe,
APPLICATION_SCOPE,
MessageContext
} from "lightning/messageService";
// シート内のセルにフォーカスした際のイベントを取得するMessage Channel
import MC_FOCUS_CELL from "@salesforce/messageChannel/msmxSheet__focusCell__c";
// イベントをサブスクライブするコンポーネント
export default class MyComponent extends LightningElement {
@wire(MessageContext)
messageContext;
subscr = null;
connectedCallback() {
// Message Channelのサブスクライブ
// 詳細はSalesforceのLightning Webコンポーネント開発のドキュメントを参照
this.subscr = subscribe(
this.messageContext,
MC_FOCUS_CELL,
(msg) => this.handleFocusCell(msg),
{ scope: APPLICATION_SCOPE }
);
}
disconnectedCallback() {
// Message Channelのアンサブスクライブ
if (this.subscr) {
unsubscribe(this.subscr);
}
this.subscr = null;
}
handleFocusCell(message) {
// do something important
console.log(message.cell.recordId);
}
}
Visualforceページの場合、Sheetコンポーネントのイベントをサブスクライブするコードは以下のようになります。
<apex:page>
<div>
<p>Subscribe to SampleMessageChannel </p>
<button onclick="startSubscription()">Subscribe</button>
<p>Unsubscribe from subscription</p>
<button onclick="stopSubscription()">Unsubscribe</button>
<br/>
<br/>
<p>Received message:</p>
<textarea id="messageReceived" rows="10" />
</div>
<script>
// シート内のセルにフォーカスした際のイベントを取得するMessage Channel
var MC_FOCUS_CELL = "{!$MessageChannel.msmxSheet__focusCell__c}";
var subscr = null;
function handleFocusCell(message) {
console.log(message.cell.recordId);
document.querySelector("#messageReceived").value = JSON.stringify(message, null, 2);
}
function startSubscription() {
// Message Channelのサブスクライブ
// 詳細はSalesforceのVisualforceページ開発のドキュメントを参照
subscr = sforce.one.subscribe(MC_FOCUS_CELL, handleFocusCell, { scope: "APPLICATION" });
}
function stopSubscription() {
// Message Channelのアンサブスクライブ
if (subscr) {
sforce.one.unsubscribe(subscr);
subscr = null;
}
}
</script>
</apex:page>イベントの種別と対応するMessage Channel
Mashmatrix Sheetでは以下のイベントとそのMessage Channelが現在サポートされています。
レコード選択 (Select Records)
シートのレコード選択が変更されたときに通知されるイベント
Message Channel名
msmxSheet__selectRecords__c
イベントメッセージに含まれるデータ
componentId - Sheetコンポーネントを表すページ内で一意のID。Sheetコンポーネントのプロパティ設定の値が設定されます。
bookId - レコード選択イベントが発生したブックのIDを表します
sheetId - レコード選択イベントが発生したシートのIDを表します
records - 選択されたレコードをリスト形式で返します
recordIds - 選択されたレコードのIDをリスト形式で返します
ロード完了 (Load Complete)
シートのレコードロードが完了したときに通知されるイベント
Message Channel名
msmxSheet__loadComplete__c
イベントメッセージに含まれるデータ
componentId - Sheetコンポーネントを表すページ内で一意のID。Sheetコンポーネントのプロパティ設定の値が設定されます。
bookId - レコードロードが完了したブックのIDを表します
sheetId - レコードロードが完了したシートのIDを表します
records - ロードされたすべてのレコード情報をリスト形式で返します
recordIds - ロードされたすべてのレコードのIDをリスト形式で返します
セルのフォーカス (Focus Cell)
シート内のセルがクリックなどによってフォーカスされたときに通知されるイベント
Message Channel名
msmxSheet__focusCell__c
イベントメッセージに含まれるデータ
componentId - Sheetコンポーネントを表すページ内で一意のID。Sheetコンポーネントのプロパティ設定の値が設定されます。
bookId - フォーカスされたセルが所属するブックのIDを表します
sheetId - フォーカスされたセルが所属するシートのIDを表します
cell - フォーカスされたセルの情報が格納されています
recordId - セルに表示されているレコードのID
rowIndex - セルの行インデックス位置（全ページ中）
colIndex - セルの列インデックス位置
columnName - セルの列名
value - セル内に表示されている値
record - フォーカスされたセルがレコード内のセルの場合、そのレコードの情報が格納されます
カスタムイベントの発行 (Fire Custom Event)
シート内のセルに設定されたカスタムイベントアクションリンクのクリック時、およびカスタムイベントを発行するアクションボタンのクリック時に通知されるイベント
Message Channel名
msmxSheet__fireCustomEvent__c
イベントメッセージに含まれるデータ
componentId - Sheetコンポーネントを表すページ内で一意のID。Sheetコンポーネントのプロパティ設定の値が設定されます。
bookId - カスタムイベントが発行されたブックのIDを表します
sheetId - カスタムイベントが発行されたシートのIDを表します
eventName - アクションボタン/リンクの設定で設定されたイベント名が格納されます
records - （アクションボタンによるカスタムイベントの場合）シート内で選択されているレコードの情報をリスト形式で返します
recordIds - （アクションボタンによるカスタムイベントの場合）シート内で選択されているレコードのIDをリスト形式で返します
record - （アクションリンクによるカスタムイベントの場合）クリックしたリンクを含むレコードの情報が格納されます
recordId - （アクションリンクによるカスタムイベントの場合）クリックしたリンクを含むレコードのIDが格納されます
パラメーターの設定
Lightningページ内に配置されているSheetコンポーネントに対して、外部からパラメータを設定して送信することが可能です。パラメータを利用するには、Sheetコンポーネント内のシートにおいて、フィルタ内の参照値として同名のパラメータ値を参照している必要があります。
イベントのサブスクリプションの場合と同様にMessage Channelを利用しますが、カスタムのプログラムはこのMessage Channelに対してメッセージをパブリッシュすることによってパラメータを設定します。
Lightning Webコンポーネントの場合、Sheetコンポーネントへパラメータを設定するコードは以下のようになります。
import { LightningElement, wire } from "lwc";
import { publish, MessageContext } from "lightning/messageService";
import MC_SET_PARAMETERS from "@salesforce/messageChannel/msmxSheet__setParameters__c";
export default class PublishExample extends LightningElement {
@wire(MessageContext)
messageContext;
handleSubmit() {
publish(this.messageContext, MC_SET_PARAMETERS, {
parameters: {
accountName: "Acme"
}
});
}
}Visualforceページの場合、Sheetコンポーネントへパラメータを設定するコードは以下のようになります。
<apex:page>
<div>
<input type="text" id="acccountName" value="Acme" />
<p>Publish to MessageChannel </p>
<button onclick="publishMessage()">Publish</button>
</div>
<script>
// Sheetに対してパラメータ設定を伝えるMessage Channel
var MC_SET_PARAMETERS = "{!$MessageChannel.msmxSheet__setParameters__c}";
function publishMessage(message) {
sforce.one.publish(MC_SET_PARAMETERS, {
parameters: {
accountName: document.querySelector("#acccountName").value,
}
});
}
</script>
</apex:page>パラメータ設定用Message Channelの仕様
Message Channel名
msmxSheet__setParameters__c
イベントメッセージに含めるデータ
componentId - パラメータを設定するSheetコンポーネントを表すID。Sheetコンポーネントのプロパティ設定で指定した値を設定します。指定のない場合はページ内のすべてのSheetコンポーネントに対してパラメータを設定します。
parameters - パラメータを指定する任意のJSON形式のオブジェクト。
{ "パラメータ名": "パラメータ値", ... }の形式となりますpartial - パラメータの値をすべて置き換えるのではなく、部分的なアップデートを行う場合に
trueを指定しますforceLoad - アクティブなシートを強制的に再読み込みするように促したいときに
trueを指定します
コマンドの実行
Lightningページ内に配置されているSheetコンポーネントに対して、外部から操作コマンドを送信することが可能です。
パラメータ設定の場合と同様にMessage Channelに対してメッセージをパブリッシュすることによってコマンドを実行します。
Lightning Webコンポーネントの場合、Sheetコンポーネントへコマンドを送信するコードは以下のようになります。
import { LightningElement, wire } from "lwc";
import { publish, MessageContext } from "lightning/messageService";
import MC_EXECUTE_COMMAND from "@salesforce/messageChannel/msmxSheet__executeCommand__c";
export default class CommandExample extends LightningElement {
@wire(MessageContext)
messageContext;
@api
bookId;
sheetId = 's1';
handleFocusSheet() {
publish(this.messageContext, MC_EXECUTE_COMMAND, {
command: "focusSheet",
arguments: {
bookId: this.bookId,
sheetId: this.sheetId
}
});
}
}Visualforceページの場合、Sheetコンポーネントへパラメータを設定するコードは以下のようになります。
<apex:page>
<div>
<p>Click to change focus</p>
<a onclick="focusSheet('s1')">Sheet #1</a>
<a onclick="focusSheet('s2')">Sheet #2</a>
</div>
<script>
// Sheetに対してパラメータ設定を伝えるMessage Channel
var bookId = 'your book id is here';
var MC_EXECUTE_COMMAND = "{!$MessageChannel.msmxSheet__executeCommand__c}";
function focusSheet(sheetId) {
sforce.one.publish(MC_EXECUTE_COMMAND, {
command: "focusSheet",
arguments: {
bookId: bookId,
sheetId: sheetId
}
});
}
</script>
</apex:page>コマンド実行用Message Channelの仕様
Message Channel名
msmxSheet__executeCommand__c
イベントメッセージに含めるデータ
componentId - コマンドを実行する対象となるSheetコンポーネントを表すID。Sheetコンポーネントのプロパティ設定で指定した値を設定します。指定のない場合はページ内のすべてのSheetコンポーネントに対してコマンドの実行が要求されます。
command - 実行するコマンド名。
arguments - コマンドに渡す引数。JSON形式のオブジェクトで渡されるが、必要とされる情報は実行するコマンドにより異なる。
{ "引数名": "引数値", ... }の形式となります。
実行可能なコマンドの種別
Mashmatrix Sheetでは以下のコマンドが現在サポートされています。
シートのフォーカス
指定したシートをフォーカスします。対象のシートが非アクティブ（タブの前面にない / 単一表示の対象ではない）である場合、アクティブの状態となり前面に表示されます。指定したシートが非表示状態である場合や存在しない場合には何も実行しません。
コマンド名
focusSheet
コマンド引数
bookId - フォーカスするシートを含むブックのブックID。
sheetId - フォーカスするシートのシートID。
レコードの保存
指定したシートの編集中のレコードデータを保存します。編集中のレコードが存在しない場合には何も実行しません。
コマンド名
saveRecords
コマンド引数
bookId - レコード保存するシートを含むブックのブックID。
sheetId - レコード保存するシートのシートID。
Last updated