なでしこ3には、JavaScriptで開発する「JSプラグイン]」となでしこ自身で開発する「NAKO3プラグイン」の二種類があります。
また、ブラウザ版のプラグインの作り方と、PC版(Node.js)のプラグインの作り方で、JavaScriptならではの異なる点があります。
ブラウザ版のJSプラグインを利用するには、(1)「取り込む構文」を使う方法と、(2)HTMLの<script>タグを使う方法の二種類があります。
# --- (1) なでしこのプログラム内で「取り込む」文を使う !「xxx.js」を取り込む # --- (2) HTMLファイル内で<script>タグを記述する <script src="xxx.js"></script>
プラグインの実体は、JavaScriptのオブジェクトです。取り込む文でプラグインを取り込む場合、必ずオブジェクトをエクスポートするように設定してください。なでしこv3.3以降、なでしこは、ESModuleを採用しています。ESModuleでは「export default { ... }」のように記述します。
// ESModule方式
export default {
'関数名': { 定義 },
'定数名': { 定義 },
}
HTMLの<script>タグでプラグインを読み込む場合、以下のようにプラグインを記述します。プラグインを記述した後で、なでしこ本体(navigator.nako3)にプラグインを登録する処理が必要になります。
// CommonJS方式で自動登録を実装
const pluginObj = {
'関数名': { 定義 },
'定数名': { 定義 },
}
// --- なでしこ3の本体に関数を登録する ---
if (typeof (navigator) === 'object') {
navigator.nako3.addPluginObject("pluginHello", pluginObj)
} else {
module.exports = pluginObj
}
上記のObjectにて関数を定義するには、fnプロパティに行います。実際の関数の引数に加えて、システムを表すsysを定義します。
{
'関数名': { // @関数の説明 // @ヨミガナ
type: 'func', // 関数であれば func にする
josi: [['を', 'から'], ['まで']], // 助詞を配列で宣言する (可変長引数として扱いたい助詞は末尾で宣言する)
isVariableJosi: false, // 末尾の助詞を可変長引数として扱う場合 true にする
uses: [], // この関数から別の関数を呼ぶ場合に記述する // (TODO: #282)
asyncFn: false, // async関数定義かPromiseを返す関数を定義する場合 true にする (参照: #1154)
fn: function (aFrom, aTo, sys) { ... }, // 関数の実態
return_none: false // 戻り値を返すかどうか
},
...
}
typeプロパティに「var」(変数)や「const」(定数)を指定して、valueプロパティに値を指定します。
{
{ type: 'const', value: 100 }, // @ヨミガナ
{ type: 'const', value: 100 }, // @ヨミガナ
....
}
なお、コメントを記述した場合『npm run build:command』を実行すると自動的にコマンドマニュアルが生成されます。
以下のようなエントリを用意しておくと、プラグインを取り込み、初回実行するときに初期化メソッドが実行されます。 (ただし、プラグイン取り込み時に、 !{プラグイン名}:初期化 というメソッド名にリネームされます)
{
'初期化': {
type: 'func',
josi: [],
fn: function (sys) { ... }
}
...
}
なお、初期化メソッドのほかに、以下のようなメタ情報を定義する必要があります。
'meta': {
type: 'const',
value: {
pluginName: 'plugin_***', // プラグインの名前
description: '説明',
pluginVersion: '3.6.0', // プラグインのバージョン
nakoRuntime: ['wnako', 'cnako', 'phpnako'], // 対象ランタイム
nakoVersion: '3.6.0' // 最小要求なでしこバージョン
}
},
以下のようなエントリを用意しておくと、プログラム終了時（あるいはクリア時）にプラグインごとプログラムが実行されます。
{
'!クリア': {
type: 'func',
josi: [],
fn: function (sys) { ... }
}
...
}これを利用する事で、現在なでしこが実行されているかどうかを判定できます。
関数を定義したとき、プラグイン関数側からシステムにアクセスしなければならない場合があります。 以下は引数のない関数を定義した例ですが、必ず必要とされる引数の末尾に実行したシステムのthisを保持するオブジェクトが渡されます。このオブジェクトを参照することで、システム変数にアクセスできます。
{
type: 'func',
josi: [],
fn: function (sys) {
console.log(sys)
}
}
より詳しい機能については、以下を参照してください。
なでしこは、Node.jsのエコシステム上で動作するように配慮されています。
そのため、自分の作ったプラグインをnpm上で公開すると、みんなに使ってもらいやすくなります。
なでしこv3.6以降、なでしこ内部の変数管理の仕組みが変わりました。なでしこ内部の変数管理がObjectからMapに変更となり安全性が向上しました。
そのため、v3.5以前で可能だった次のような表現が使えなくなりました。
// 廃止されたシステム変数へのアクセス const value1 = sys.__v0["変数名"] sys.__v0["変数名"] = value1 const value2 = sys.__varslist[0]["変数名"] sys.__varslist[0][変数名] = value2
こうした表現が、以下のようなメソッドを介したアクセスに変更されました。
// 今後、利用可能なシステム変数へのアクセス
sys.__setSysVar("変数名", 値) ... なでしこ変数の設定
sys.__getSysVar("変数名") ... 変数の値の取得
他にも、プラグイン関数で使えるメソッドやプロパティの一覧が以下にまとめられました。