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> を返す |
Permission が必要な API
| メソッド | Permission | 内容 |
|---|---|---|
clipboard.readText() / writeText(text) | clipboard | システムのテキストクリップボード |
shell.openExternal(url) | shell:openExternal | http・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 で判定します。権限と通信のエラー表と実行できるサンプルを参照してください。