# JavaScript API

`msmxSheet:SheetView`コンポーネントをVisualforceページに配置することで、ページ内に `MsmxSheet` JavaScriptオブジェクトがグローバルに公開されます。このオブジェクトからAPI呼び出しを行うことで、Sheetの動作および描画を動的に制御することが可能です。

## APIメソッド

### setApplicationParameter(params, options) <a href="#api-setapplicationparameter" id="api-setapplicationparameter"></a>

Sheetアプリケーションに対してアプリケーションパラメータを設定します。アプリケーションパラメータはフィルタの値指定の際に参照値として指定が可能です。フィルタに該当するパラメータの参照値が設定されている場合、フィルタの値は参照しているパラメータの値に置き換えられ、自動的にシート表示がリフレッシュされます。

テキスト型やID型のフィルタ、および高度なフィルタ設定では、アプリケーションパラメータの値を参照値として指定し、フィルタの値として利用することができます。詳しくは[「フィルタでの参照値の利用」](https://docs.mashmatrix.com/mashmatrix-sheet/ja/functions_about_displaying_data/filter#using-reference-value-in-filter)を参照してください。

```javascript
// パラメータ名と値のkey valueペアを引数に渡す
MsmxSheet.setApplicationParameter({
  Name: 'Salesforce',
  Type: ['Partner', 'Customer'] // パラメータが複数値を持つ場合は配列で渡します
});

// Typeパラメータを未設定に変更
MsmxSheet.setApplicationParameter({
  Name: 'Salesforce'
}, {
　forceLoad: true // 更新がない場合でもパラメータに依存しているシートのリフレッシュを行う
});
```

#### パラメータ

* **params** - (必須) アプリケーションパラメータ名と設定する値をKey-Valueペアで設定する
* **options** - (オプション) オプション。`forceLoad`フラグを設定することでリフレッシュを強制することが可能

### updateApplicationParameter(params, options) <a href="#api-updateapplicationparameter" id="api-updateapplicationparameter"></a>

Sheetアプリケーションに設定されているアプリケーションパラメータを更新します。 `setApplicationParameter`との違いは、指定されたパラメータ名の値のみを置き換え、それ以外のパラメータは設定されたままとなる点です。

```javascript
// 最初はアプリケーションパラメータ未設定の状態

MsmxSheet.updateApplicationParameter({
  Name: 'Mashmatrix'
});
// => { Name: 'Mashmatrix }

MsmxSheet.updateApplicationParameter({
  Type: ['Customer']
});
// => { Name: 'Mashmatrix, Type: ['Customer'] }

// 設定済みのパラメータ設定をクリアする場合はundefinedを設定する
MsmxSheet.updateApplicationParameter({
  Name: undefined
});
// => { Type: ['Customer'] }
```

#### パラメータ

* **params** - (必須) 更新対象となるアプリケーションパラメータ名とその値をKey-Valueペアで設定する
* **options** - (オプション) オプション。`forceLoad`フラグを設定することでリフレッシュを強制することが可能

### subscribeComponentEvent(compId, path, event, listener) <a href="#api-subscribecomponentevent" id="api-subscribecomponentevent"></a>

`msmxSheet:SheetView`コンポーネント内で表示されているシートから通知されるイベントを購読するリスナを設定します

```
<msmxSheet:SheetView
  id="comp-01"
  bookId="a002800001O6vOpAAJ"
  sheetID="s1"
  width="100%" height="400px"
/>
```

```javascript
// シートのレコードロード完了時のイベントを購読
MsmxSheet.subscribeComponentEvent(
  'comp-01',
  'a002800001O6vOpAAJ/s1',
  'loadComplete',
  function(res) {
    console.log(res.records); // ロードしたレコードの一覧
  }
);

// シートのレコード選択が変更されたときのイベントを購読
MsmxSheet.subscribeComponentEvent(
  'comp-01',
  'a002800001O6vOpAAJ/s1',
  'selectRecords',
  function(res) {
    console.log(res.records); // レコード選択チェックボックスで選択したレコードの一覧
  }
);
```

#### パラメータ

* **compId** - (必須) 対象とするコンポーネントのID (`msmxSheet:SheetView`のid属性で指定)
* **path** - (必須) Book IDとSheet IDを"/"で連結したもの
* **event** - (必須) 購読するイベント名
* **listener** - (必須) イベントが通知されるリスナー関数

### unsubscribeComponentEvent(compId, path, event, listener) <a href="#api-unsubscribecomponentevent" id="api-unsubscribecomponentevent"></a>

`msmxSheet:SheetView`コンポーネント内で表示されているシートから発火されるイベントの購読を解除します

#### パラメータ

* **compId** - (必須) 対象とするコンポーネントのID (`msmxSheet:SheetView`のid属性で指定)
* **path** - (必須) Book IDとSheet IDを"/"で連結したもの
* **event** - (必須) 購読しているイベント名
* **listener** - (オプション) 購読解除するリスナー関数。未指定の場合は該当するイベントに対するすべての既存購読が解除対象となる

## イベントの種類

### selectRecords

シートのレコード選択が変更されたときに通知されるイベント

#### イベントパラメータ

* **records** - 選択されたレコードをリスト形式で返します

### loadComplete

シートのレコードロードが完了したときに通知されるイベント

#### イベントパラメータ

* **records** - ロードしたレコードの一覧をリスト形式で返します

### focusCell

シート内のセルがクリックなどによってフォーカスされたときに通知されるイベント

#### イベントパラメータ

* **cell** - フォーカスされたセルの情報が格納されています
  * **recordId** - セルに表示されているレコードのID
  * **colIndex** - セルの列インデックス位置
  * **rowIndex** - セルの行インデックス位置（全ページ中）
  * **value** - セル内に表示されている値