JSプラグインの作り方 *

なでしこ3には、JavaScriptで開発する「JSプラグイン]」となでしこ自身で開発する「NAKO3プラグイン」の二種類があります。

また、ブラウザ版のプラグインの作り方と、PC版(Node.js)のプラグインの作り方で、JavaScriptならではの異なる点があります。

ブラウザ版 - JSプラグインの使い方 *

ブラウザ版のJSプラグインを利用するには、(1)「取り込む構文」を使う方法と、(2)HTMLの<script>タグを使う方法の二種類があります。

# --- (1) なでしこのプログラム内で「取り込む」文を使う
!「xxx.js」を取り込む

# --- (2) HTMLファイル内で<script>タグを記述する
<script src="xxx.js"></script>

プラグイン側の実装 - (1)取り込む文を使う場合 *

プラグインの実体は、JavaScriptのオブジェクトです。取り込む文でプラグインを取り込む場合、必ずオブジェクトをエクスポートするように設定してください。なでしこv3.3以降、なでしこは、ESModuleを採用しています。ESModuleでは「export default { ... }」のように記述します。

// ESModule方式
export default {
  '関数名': { 定義 },
  '定数名': { 定義 },
}

プラグイン側の実装 - (2)HTMLで<script>タグを使う場合 *

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) { ... }
  }
  ...
}

クリアメソッド *

以下のようなエントリを用意しておくと、プログラム終了時(あるいはクリア時)にプラグインごとプログラムが実行されます。

{
  '!クリア': {
    type: 'func',
    josi: [],
    fn: function (sys) { ... }
  }
  ...
}

プラグイン側からシステム変数へのアクセス *

関数を定義したとき、プラグイン関数側からシステムにアクセスしなければならない場合があります。 以下は引数のない関数を定義した例ですが、必ず必要とされる引数の末尾に実行したシステムのthisを保持するオブジェクトが渡されます。このオブジェクトを参照することで、システム変数にアクセスできます。

{
  type: 'func',
  josi: [],
  fn: function (sys) {
    console.log(sys)
  }
}

詳細は以下を参照 *

より詳しい機能については、以下を参照してください。

プラグインをnpmで公開しよう *

なでしこは、Node.jsのエコシステム上で動作するように配慮されています。
そのため、自分の作ったプラグインをnpm上で公開すると、みんなに使ってもらいやすくなります。

Konawiki3 v.3.2.3