LogoNotyra Docs
プラグイン

API リファレンス

Plugin API の全拡張ポイントとメソッド

import { notyra } from '@notyra/plugin-api' で、そのプラグイン専用の API を取得します。pluginId はマニフェストの name、apiVersion は Notyra のバージョンです。modules はホストの React・ReactDOM・CodeMirror・Lezer の共有インスタンスです。型定義の正本は本体の src/shared/plugin/api.ts で、独立した @notyra/plugin-api リポジトリ から同じ版を配布します。

登録する API

次の登録メソッドは Disposable を返します。dispose() は何度呼んでも安全で、停止時にもホストが残りの登録を解除します。停止後の登録は pluginNotActive になります。

メソッド内容
styles.add(css)このウィンドウに CSS を追加。ホストはプラグインごとの style 要素で管理
sidePanel.registerView({ id, title, icon, render })サイドパネルのビューを登録。icon は SVG 文字列。render(container) は後始末関数を返せる
markdown.registerRemarkPlugin(pluggable)組み込み remark 処理の後に Markdown AST を処理
markdown.registerRehypePlugin(pluggable)組み込みの画像・Mermaid 処理後、構文強調の前に HTML AST を処理
editor.registerExtension(extension)既存の CodeMirror 拡張の末尾に追加。登録時に構成可能か検証
commands.register({ id, title, run })コマンドを登録。run() は同期・非同期のどちらも可
toolbar.addButton({ command, icon, tooltip })登録済みコマンドを呼ぶツールバーボタン
keymaps.add({ key, command })CodeMirror 記法のキー。Mod は macOS で Meta、それ以外で Ctrl
events.onActiveNoteChange(listener)アクティブノートの切り替え・本文変更を購読。権限不要
settings.onDidChange(listener)このプラグインの設定変更を購読

ビューとコマンドのローカル ID は ${pluginId}:${id} に変換されます。組み込みのキーが最優先で、プラグイン間では読み込み順で先の登録が優先されます。コマンドを登録しただけでは一般のコマンド一覧 UI は追加されません。ツールバー・キー・自分のパネル、または commands.execute(id) から実行してください。

Markdown の pluggable は関数または [関数, ...引数] です。同じステージ内では読み込み順、各プラグイン内では登録順になります。プレビューと PDF/HTML エクスポートで同じ拡張を使います。例外を出したプラグインの Markdown 拡張はセッション中除外され、プレビューは直前の表示を維持します。例外だけを理由に即時再生成はせず、次の編集などから除外が反映されます。

ノート通知・設定・実行

type ActiveNoteEvent = {
  type: 'switched' | 'changed'
  note: { path: string; title: string; rootFolder: string; body: string } | null
  windowKind: 'main' | 'note'
}

本文の読み込みが終わった時点で切り替え通知が届き、本文変更は短くデバウンスされます。後から購読したプラグインにも、現在のノートが switched として通知されます。ノート未選択は note: null です。

メソッド戻り値・動作
settings.get<T>(key)宣言した設定の値。未保存・型不一致なら既定値
settings.getAll()宣言した設定だけを含む値のオブジェクト
settings.onDidChange(listener)値のオブジェクトを受け取る購読。保存は設定画面で行う
editor.scrollToLine(line)1始まり。範囲外は先頭・末尾に丸める。エディタがなければ false
commands.execute(id)登録したコマンドを実行し Promise<void> を返す

完全な使用例はテンプレートと ToCにあります。

Permission が必要な API

メソッドPermission内容
clipboard.readText() / writeText(text)clipboardシステムのテキストクリップボード
shell.openExternal(url)shell:openExternalhttp・https・mailto を標準アプリで開く
network.fetch(url, init?)network同意済み宛先への HTTP/HTTPS。下記参照
notes.listRootFolders()notes:read登録済みルートの絶対パス配列
notes.list(rootFolder)notes:readルート内のノートのメタデータ配列
notes.read(path)notes:read{ path, body, frontMatter }
notes.create(input)notes:write新規作成し、実際の保存パスを返す
notes.update(path, { body, frontMatter })notes:write本文と Front Matter を更新
notes.rename(path, newTitle)notes:writeタイトルとファイル名を変更し、保存パスを返す。既存名への変更は拒否
notes.move(rootFolder, path, targetFolder)notes:write移動先パスを返す。同名があれば最小の未使用連番を付ける
notes.delete(path)notes:writeプラグイン名・ノート名を示すユーザー確認後に削除。キャンセルは deleteRejected

notes.create の入力は { rootFolder, title, folder?, body?, frontMatter? } です。folder と移動先の targetFolder は指定ルートからの相対パスです。すべてのノート操作は登録済みルート内に限られ、ルート外は outOfScope。作成・移動は <base>.md または <base>-N.md を使い、既存ファイルを上書きしません。notes:write は notes:read を含まないので、ルートの一覧を得るサンプルでは両方を宣言します。

network.fetch の init は { method?, headers?: Record<string,string>, body?: string | ArrayBuffer | Uint8Array }。応答は status、ok、url、headers と非同期の text()・json<T>()・arrayBuffer() を持ちます。通常のブラウザー fetch の全オプションに対応するものではありません。

呼び出しは Promise を await し、失敗は error.kind で判定します。権限と通信のエラー表と実行できるサンプルを参照してください。