ドキュメント

開発者向けに、WP Notepad の保存形式・フック・REST API・オプションをまとめています。

保存先と保存キー

メモは閲覧者のブラウザの localStorage に保存されます。キーは設置形態ごとに次のとおりです。

設置形態保存キー
クラシックウィジェット{widget_id}-textarea
ショートコードid 属性の値(省略時は自動採番)
ブロックwpnotepad-block-{notepadKey}
タブ(2つ目以降){基本キー}-tab-{N}

マルチサイトのサブサイトでは、上記のキーの前にサイトごとの接頭辞 site{ID}-- が付きます(wpnotepad_key_prefix フィルターで変更可)。メインサイトと単一サイトは接頭辞なしです。

保存形式

メモはタイムスタンプ付きの JSON エンベロープで保存されます(v2.0.0 以降)。旧バージョンが保存した素の文字列も透過的に読み込まれます。

{ "v": 2, "time": 1750000000000, "value": "メモの内容", "u": "…" }
  • time はエポックミリ秒。保存期限(TTL)の判定とデバイス間同期の競合解決(後勝ち)に使用します。
  • テキストエリアの data-ttl(日数)が設定されている場合、now - time が超過したメモは読み込み時に自動削除されます。
  • u は同期が有効なサイトでログイン中に書いたメモにだけ付く所有者タグ(ユーザーごとの不透明な値)です。同期が有効なサイトでは、ほかの所有者のメモは表示も同期もされません。
  • クリアしたメモは空の値(時刻付き)として残り、ほかの端末の古い内容で復活しないようにしています。

フィルター

フィルター説明
wpnotepad_widget_textareaウィジェットが出力するメモ帳のマークアップ全体(タブバー・テキストエリア・ツールバー・ステータス)を受け取り、加工できます
wpnotepad_widget_descriptionウィジェットの説明文(Description)の出力を加工できます
wpnotepad_key_prefix保存キーの接頭辞(既定: サブサイトは site{ID}--、それ以外は空)。英数字・_・- のみ有効
wpnotepad_import_max_bytes「インポート」で読み込めるファイルの最大サイズ(バイト)。引数 int $bytes(既定 2097152 = 2 MB)、戻り値は整数。超えるファイルは読み込む前に断ります。0 で無制限(2.9.0 以降)
wpnotepad_user_can_syncログイン中のユーザーがデバイス間同期を使えるか。引数 bool $can(既定 true)・int $user_id、戻り値は真偽値。同期が有効でログイン中のときだけ呼ばれます。false を返したユーザーはゲストと同じくブラウザ保存のみになり、REST API は 403 を返します。既定ではログイン中の全ユーザー(マルチサイトでは、そのサイトのメンバーでないネットワークのユーザーも含む)が対象です。除外する前に同期したメモはサーバーに残ります(個人データの消去・一括削除で削除できます)(2.9.0 以降)
/**
 * ウィジェットのメモ帳マークアップを加工する例
 *
 * @param string $markup メモ帳のマークアップ全体。
 */
add_filter( 'wpnotepad_widget_textarea', function ( $markup ) {
	return '<div class="my-notepad-wrap">' . $markup . '</div>';
} );
/**
 * 同期を編集者以上に絞り、インポートの上限を 1 MB にする例
 *
 * @param bool $can     同期を許可するか(既定 true)。
 * @param int  $user_id ユーザー ID。
 */
add_filter( 'wpnotepad_user_can_sync', function ( $can, $user_id ) {
	return $can && user_can( $user_id, 'edit_others_posts' );
}, 10, 2 );

add_filter( 'wpnotepad_import_max_bytes', function () {
	return 1048576;
} );

REST API(デバイス間同期)

オプトインのデバイス間同期は、名前空間 wp-notepad/v1 の REST API を使用します。同期が有効かつログイン済みの場合のみ利用でき(Cookie 認証 + X-WP-Nonce ヘッダー)、それ以外は 401 / 403 を返します。wpnotepad_user_can_sync で除外されたユーザーにも 403 を返します。

エンドポイントメソッド説明
/wp-json/wp-notepad/v1/notesGETログインユーザーの全メモを取得。ヘッダー X-WPNotepad-Erased-At で最後に消去・一括削除された時刻を返す
/wp-json/wp-notepad/v1/notesPOSTメモを保存(key / value 必須、time 任意)。空の値はクリア済み(tombstone)として保存
/wp-json/wp-notepad/v1/notes/{key}DELETE指定キーのメモを削除
  • キーは [A-Za-z0-9_-]{1,191}(違反は 400)。値は 10 万文字まで(超過分は切り捨て)。
  • 保存済みより古い time の書き込みは無視(saved: false)。未来の time はサーバーの現在時刻に丸めます。消去・一括削除より前の時刻の書き込みも受け付けません。
  • 1 ユーザーあたりメモ 200 件(409)、合計 1 MB(413)、クリア済みを含む 500 行(超える新規キーは最も古いクリア済みから削除)。
  • サーバー側は 1 メモ = 1 ユーザーメタ(rwc_wpnotepad_note:{key})に保存します。旧形式(rwc_wpnotepad_notes の配列)は初回アクセス時に自動移行します。
  • フロントは window.wpNotepad を参照します(syncSite・keyPrefix・importMaxBytes・i18n、同期できるユーザーのときのみ restUrl / nonce / user)。

ブロック

ブロック(rwc/wpnotepad)はサーバー側で描画するダイナミックブロックです(2.2.0 以降)。属性はブロックコメントに保存され、マークアップはウィジェット・ショートコードと共通のテンプレートから生成されます。以前のバージョンで保存した静的なブロックは、再保存までは保存済みの HTML をそのまま表示し、エディターで開いたときに自動で移行します。

オプション・メタデータ

名前種類説明
rwc_wpnotepad_sync_enabledオプションデバイス間同期の有効・無効(既定: 無効)。「設定 → WP Notepad」で切り替え
rwc_wpnotepad_note:{key}ユーザーメタ同期済みメモ(value / time)
rwc_wpnotepad_erased_atユーザーメタ個人データ消去の時刻(それ以前の書き込みを拒否)
rwc_wpnotepad_purged_atネットワークオプション「同期済みメモをすべて削除」の時刻
rwc_wpnotepad_prefix_sinceネットワークオプションマルチサイトの保存キー接頭辞の適用開始時刻(旧メモの引き継ぎ判定用)

プライバシー

  • 同期済みメモは WordPress の個人データのエクスポート/消去(「ツール」メニュー)に対応しています。クリア済みのメモはエクスポートされません。
  • プライバシーポリシーの文案を「設定 → プライバシー」のガイドに追加します。
  • 同期が無効な間、またはゲストのメモは、サーバーに一切送信されません。

アンインストール

プラグインを削除すると、同期設定(全サイト)、すべてのユーザーの同期済みメモ、消去・一括削除の記録を削除します。閲覧者のメモはブラウザ側(LocalStorage)にあるため、サイト側からは削除されません。rwc_wpnotepad_prefix_since(個人データを含まない時刻 1 件)は、再インストール時にサブサイトがメインサイトのメモを取り込まないよう意図的に残します。

ソースコード

タイトルとURLをコピーしました