tampermonkey

Tampermonkey ユーザースクリプトの開発

ユーザースクリプトは、ウェブページを変更し、タスクを自動化するブラウザースクリプトです。

クイックスタートテンプレート

JavaScript（GM. API を使わないシンプルなスクリプト）*

// ==UserScript==
// @name         My Script Name                    // <- CUSTOMISE: Unique script name
// @namespace    https://example.com/scripts/      // <- CUSTOMISE: Your unique namespace
// @version      1.0.0                             // <- INCREMENT on updates
// @description  Brief description of the script   // <- CUSTOMISE: What it does
// @author       Your Name                         // <- CUSTOMISE: Your name
// @match        https://example.com/*             // <- CUSTOMISE: Target URL pattern
// @grant        none                              // <- ADD permissions as needed
// @run-at       document-idle                     // <- ADJUST timing if needed
// ==/UserScript==

(function() {
    'use strict';
    // Your code here
})();

モダン（async/await — GM. API を使う場合に推奨）*

// ==UserScript==
// @name         My Script Name
// @namespace    https://example.com/scripts/
// @version      1.0.0
// @description  Brief description of the script
// @author       Your Name
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.setValue
// @run-at       document-idle
// ==/UserScript==

(async () => {
    'use strict';
    // Async entry point - use await with GM.* APIs
    const setting = await GM.getValue('myKey', 'default');
    console.log('Script loaded, setting:', setting);
})();

TypeScript： 完全な型安全性を得るには、@types/tampermonkey を追加してください。typescript.md を参照してください。

---

必須ヘッダータグ

タグ	必須	目的	例
@name	はい	スクリプト名（:locale による国際化に対応）	@name My Script
@namespace	推奨	一意な識別子の名前空間	@namespace https://yoursite.com/
@version	はい*	更新用のバージョン（*自動更新には必須）	@version 1.2.3
@description	推奨	スクリプトの機能	@description Enhances page layout
@match	はい**	実行対象の URL（**または @include）	@match https://example.com/*
@grant	状況に応じて	API の権限（GM_* API を使わない場合は none を指定）	@grant GM_setValue
@run-at	任意	スクリプトを挿入するタイミング（デフォルト：document-idle）	@run-at document-start
@run-in	任意	通常タブ、シークレットタブ、または Firefox コンテナーへの適用を制限（v5.3+）	@run-in normal-tabs

ヘッダーの完全なドキュメントについては、 header-reference.md を参照してください。

---

URL マッチングのクイックリファレンス

// Exact domain                  // @match https://example.com/*
// All subdomains                // @match https://*.example.com/*
// HTTP and HTTPS                // @match *://example.com/*
// Exclude paths (with @match)   // @exclude https://example.com/admin/*

高度なパターン（正規表現、@include、特定のパス）については、 url-matching.md を参照してください。

---

@grant 権限のクイックリファレンス

必要な操作	指定する権限
データを永続的に保存する	@grant GM_setValue + @grant GM_getValue
オリジンをまたぐリクエストを送信する	@grant GM_xmlhttpRequest + @connect domain
カスタム CSS を追加する	@grant GM_addStyle
ページの window にアクセスする	@grant unsafeWindow
通知を表示する	@grant GM_notification
メニューコマンドを追加する	@grant GM_registerMenuCommand
URL の変更を検出する（SPA）	@grant window.onurlchange
設定を一括で読み書きする（v5.3+）	@grant GM.getValues + @grant GM.setValues
タブの音声をミュート／ミュート解除する	@grant GM_audio

// Disable sandbox (no GM_* except GM_info)
// @grant none

// Cross-origin requests require @connect
// @grant GM_xmlhttpRequest
// @connect api.example.com
// @connect *.googleapis.com

権限ガイドの完全版については、 header-reference.md を参照してください。

---

@run-at の挿入タイミング

値	スクリプトの実行タイミング	用途
document-start	DOM が存在する前	リソースをブロックする、グローバル変数を早期に変更する
document-body	body が存在するとき	DOM を早期に操作する
document-end	DOMContentLoaded 時	多くのスクリプト — DOM の準備完了後
document-idle	DOMContentLoaded 後（デフォルト）	安全なデフォルト
context-menu	右クリックメニューを表示したとき	ユーザーが実行するアクション

---

一般的なパターン

以下のパターンは頻繁に使用されます。概要を以下に示します。コード例を含む完全な実装については、patterns.mdを参照してください。

• 要素の出現を待機 - CSS セレクターに一致する要素が DOM に現れたときに解決される、タイムアウトを設定可能な Promise ベースの MutationObserver
• SPA の URL 変更検出 - window.onurlchange の許可、または History API のインターセプトを使用して、シングルページアプリでのナビゲーションを検出します
• クロスオリジンリクエスト - @connect によるドメインの許可リストを設定し、GM_xmlhttpRequest を使って外部 API からデータを取得します。http-requests.mdも参照してください
• カスタムスタイルの追加 - GM_addStyle で CSS を挿入し、ページのスタイルを変更したり、要素を非表示にしたりします。api-dom-ui.mdも参照してください
• 設定の永続化 - GM_setValue／GM_getValue でユーザー設定を保存し、GM_registerMenuCommand で切り替え機能を追加します。api-storage.mdも参照してください
• DOM の変更監視 - MutationObserver を使って動的に追加されたコンテンツを監視します（デバウンス版も含まれます）
• 要素の操作 - HTML の挿入、要素の削除や非表示、ページ全体のテキスト置換を行います
• キーボードショートカット - シンプルなハンドラーと、修飾キーをサポートするショートカットマネージャー
• データ抽出 - 表のデータを配列／オブジェクトに抽出し、ページのリンクを収集してフィルタリングします
• エラー処理 - try/catch 用の安全なラッパーと、指数バックオフによる非同期リトライ
• TypeScript ユーザースクリプト - @types/tampermonkey を使った型安全なスクリプト。typescript.mdを参照してください

---

外部リソース

// @require - Load external scripts
// @require https://code.jquery.com/jquery-3.6.0.min.js#sha256-/xUj+3OJU...
// @require tampermonkey://vendor/jquery.js         // Built-in library

// @resource - Preload and inject external CSS
// @resource myCSS https://example.com/style.css    // Then: GM_addStyle(GM_getResourceText('myCSS'))
// @grant GM_getResourceText
// @grant GM_addStyle

---

TypeScript のサポート

型定義をインストールすると、IDE の完全な自動補完と型安全性を利用できます。

npm install --save-dev @types/tampermonkey

// ==UserScript==
// @name         My TypeScript Script
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.xmlHttpRequest
// @connect      api.example.com
// ==/UserScript==

(async () => {
    'use strict';
    const value = await GM.getValue<string>('key', 'default');
    const info: Tampermonkey.ScriptInfo = GM_info;
    console.log(info.script.name, value);
})();

バンドラー（esbuild、Vite、webpack）でビルドし、単一の .user.js 出力ファイルを作成します。tsconfig やバンドラー設定を含むプロジェクトのセットアップ全体については、typescript.mdを参照してください。

---

Tampermonkey でできないこと

ユーザースクリプトには制限があります。

• ローカルファイルへのアクセス - コンピューター上のファイルの読み書きはできません
• ページスクリプトより先に実行 - 分離サンドボックスモードでは、ページスクリプトが先に実行されます
• クロスオリジン iframe へのアクセス - ブラウザーのセキュリティによって阻止されます
• マシン間での永続化 - GM ストレージは各ブラウザー内に保存されます
• すべての CSP の回避 - 非常に厳格な CSP は回避できない場合があります
• 許可なしの挿入 - Chrome と Edge では、スクリプトを実行する前に、ユーザーが拡張機能の詳細ページで「Allow User Scripts」切り替えを有効にする必要があります（古いブラウザーでは Developer Mode を有効にします）。スクリプトからこれを要求したり、回避したりすることはできません。スクリプトが実行されない場合は、まずここを確認してください。common-pitfalls.mdの Pitfall 15 を参照してください

ほとんどの制限には回避策があります。common-pitfalls.mdを参照してください。

---

ユーザースクリプトを生成する場合

回答には必ず以下を含めてください。

1. 説明 - スクリプトの動作（1～2 文）
2. 完全なユーザースクリプト - すべてのヘッダーを含む完全なコードをコードブロックに記載
3. インストール方法 - 「Tampermonkey ダッシュボードにコピーして貼り付ける」または「.user.js として保存する」
4. カスタマイズできる箇所 - ユーザーが安全に変更できる項目（セレクター、タイムアウトなど）
5. 使用する権限 - 必要な @grant とその理由
6. ブラウザーの対応状況 - Chrome のみ、Firefox のみ、または共通

---

提供前のチェックリスト

ユーザースクリプトを返す前に、以下を確認してください。

重要（必ず確認）

• API キー、トークン、パスワードがハードコードされていない
• @match が具体的に指定されている（*://*/* ではない）
• 外部 URL がすべて HTTPS を使用している
• DOM に挿入する前にユーザー入力がサニタイズされている

推奨（確認すること）

• IIFE でラップされ、'use strict' が指定されている
• すべての @grant 文が必要である
• @connect にすべての外部ドメインが含まれている
• 非同期処理にエラー処理がある
• DOM 操作の前に null チェックがある

推奨事項

• @version がセマンティックバージョニング（X.Y.Z）に従っている
• Chrome と Firefox の両方で動作する
• コメントで、ひと目では分かりにくいコードを説明している

セキュリティチェックリストの全項目については、こちらを参照してください： security-checklist.md

---

リファレンスファイルガイド

ユーザーのニーズに応じて、必要なファイルを読み込んでください：

ファイル	読み込むタイミング
コア
header-reference.md	ヘッダーの構文 — すべての @tag と例
url-matching.md	@match、@include、@exclude のパターン
patterns.md	コードを含む一般的な実装パターン
sandbox-modes.md	セキュリティ／分離された実行コンテキスト
API
api-sync.md	GM_* 同期関数のリファレンス（コールバックベース）
api-async.md	GM.* Promise ベース API のリファレンス — 新しいスクリプトではこちらを優先してください
api-storage.md	GM_setValue、GM_getValue、リスナー
http-requests.md	クロスオリジンの GM_xmlhttpRequest
web-requests.md	GM_webRequest による傍受（Firefox）
api-cookies.md	GM_cookie の操作
api-dom-ui.md	addElement、addStyle、unsafeWindow
api-tabs.md	getTab、saveTab、openInTab
api-audio.md	タブのミュート／ミュート解除
品質
common-pitfalls.md	スクリプトの動作を妨げる要因と回避策
debugging.md	ユーザースクリプトのデバッグ方法
browser-compatibility.md	Chrome と Firefox の違い
security-checklist.md	提供前のセキュリティ検証
version-numbering.md	バージョン文字列の比較ルール
typescript.md	@types/tampermonkey を使った TypeScript プロジェクトのセットアップ、バンドラーの設定