昨年末のことですが、かの Google 情報の大御所『Gmailの使い方』の管理人様からメールが届いていました。なにごとかと思って開いてみると、

「Gmail Greasemonkey API について、例のGoogleガジェットAPIのような解説ページを書いてみる気はないですか？」

というご依頼でした。う〜む、確かに Gmail Greasemonkey API の日本語資料はあまり見かけないので、ネタとしてはとても面白い。しかし最大の問題は、私自身がこの API を使った事がないということ（＾＾；。しばし考えた後、以下のページにある公式リファレンスを翻訳してみようと思い立ちました。

http://code.google.com/p/gmail-greasemonkey/wiki/G...

これなら API の利用経験がなくても記事が書けますし、それなりに有用な資料になりそうです。これから Gmail 用 Greasemonkey スクリプトを作ってみようという方、参考にしていただければ幸いです。

※この翻訳は伊藤が独自に行ったものですので、内容に関しての保証はまったくありません。また、この内容に関してグーグル株式会社等に問い合わせるのはご遠慮ください。

概要

それでは、さっそくリファレンスの邦訳に・・・といきたいところですが、その前に Gmail Greasemonkey API が開発された背景など含めて、その概要を書いておこうと思います。この部分は公式リファレンスのものではなく、私の独自の見解ですのでご注意ください。

さて、まずは Greasemonkey についてです。これは Firefox 用の強力なエクステンションのひとつで、ユーザー側で用意した JavaScript を任意のサイトで実行する機能を提供するものです。これによって、サイトの機能をユーザー側で自由に拡張することができます。

そして、 Geek 御用達(?)の Web メールである Gmail 用にも、当然のごとく便利な Greasemonkey スクリプトが多数開発され、多くの支持を集めました。しかし、これらのスクリプトの多くが昨年行われた Gmail のバージョンアップで動作不能になってしまいました。これらのスクリプトはページの DOM 構造に大きく依存しており、ページデザインの変化に追従できなかったのが主な原因です。

この問題への対策として Google が新 Gmail に実装したのが、今回ご紹介する Gmail Greasemonkey API です。よく使用される DOM ノードへのアクセスが抽象化されているので、これを利用すれば DOM 構造の変化に強い Greasemonkey スクリプトが作れます。

ちょっと残念なのが、旧 Gmail 向けには API が提供されていないことです。従って、この API を使ったスクリプトは旧 Gmail では動作しません。また、現在のところ実験的な機能なので、仕様が変更される可能性は残っているようです。このあたり理解したうえでご利用ください。

それでは、以下、公式リファレンスの邦訳です。前書きの部分は上記の概要と同じような内容ですので、そこはとばしてリファレンス部分から翻訳しています。また、私はそれほど英語が得意というわけではありませんので、けっこう意訳してしまっている部分もあります。ご了承くださいませ。誤訳などのご指摘歓迎です。

gmonkey オブジェクト

Gmail Greasemonkey API は外部定義オブジェクト 'gmonkey' を通して利用します。皆さんの Greasemonkey スクリプトからは、 unsefeWindow.gmonkey を使ってアクセスすることになります。

この gmonkey オブジェクトは以下のメソッドをサポートしています :

gmonkey.load

void gmonkey.load(version, callbackFunc)

Gmail Greasemonkey API のモジュールをロードします。パフォーマンス上の理由から、このモジュールは明示的なリクエストがあるまでロードされません。

versionStr は "1.0" に固定です。現在はその他の文字列は認められません。 callbackFunc はひとつの引数（以下で説明する GmailAPI オブジェクト）をとる関数で、モジュールのロードが成功した直後に呼ばれます。

このメソッドは複数回呼び出しても安全です。もしこの API を必要とする Greasemonkey スクリプトが複数インストールされているなら、それぞれがこのメソッドを一回ずつ呼び出すべきです。

重要：モジュールは非同期的にロードされます。 callbackFunc 関数は API のロードが成功した後に呼び出されます。

gmonkey.isLoaded

boolean gmonkey.isLoaded(versionStr)

モジュールがロード済みかどうかをテストします。

versionStr は "1.0" に固定です。現在はその他の文字列は認められません。

gmonkey.info

string gmonkey.info(versionStr)

モジュールと詳細情報の所在に関する短い説明文を返します。

versionStr は "1.0" に固定です。現在はその他の文字列は認められません。

gmonkey.get

GmailAPI gmonkey.get(versionStr)

ロード済みのモジュールへのリファレンスを返します。

versionStr は "1.0" に固定です。現在はその他の文字列は認められません。

警告 : gmonkey.load の呼び出しによるモジュールのロードは非同期に行われます。従って、以下のコードは常に動作するとは限りません。

unsafeWindow.gmonkey.load("1.0");
var gmail = unsafeWindow.gmonkey.get("1.0");

このコードは（おそらく他の Greasemonkey スクリプトによって）モジュールがロード済みであれば動作します。しかし、これが最初のリクエストであった場合には、ほぼ確実に失敗するでしょう。もしモジュールがロード済みであることを確信できない場合は、 gmonkey.load を呼んでコールバック関数が呼ばれるのを待ってください。

GmailAPI オブジェクト

このオブジェクトは gmonkey.load から呼び出されるコールバック関数に渡されますので、なんらかの方法で保存しておいてください。もしこのオブジェクトを見失い、かつモジュールが確実にロード済みである場合には、 gmonkey.get を呼び出してオブジェクトを取得できます。

GmailAPI オブジェクトは以下のメソッドをサポートしています :

gmail.getActiveViewType

string gmail.getActiveViewType()

現在のアクティブビュータイプを返します。 "tl" (スレッドリスト), "cv" (メール閲覧), "co" (メール作成), "ct" (連絡先), "s" (設定) のいずれかです。

gmail.registerViewChangeCallback

void gmail.registerViewChangeCallback(callbackFunc)

アクティブビューが変更されるたびに呼ばれる関数を登録します。例えば、もしユーザーが conversation thread を見るために Enter を押せば、 "cv" を引数として callbackFunc が呼ばれます。そしてユーザーがスレッドをアーカイブすれば、 "tl" を引数として callbackFunc が呼ばれます。

gmail.getNavPaneElement

Element gmail.getNavPaneElement()

左側にあるナビゲーション・ペインのルート DOM ノードを返します。

gmail.getMastheadElement

Element gmail.getMastheadElement()

masthead のルート DOM ノードを返します。（具体的にどの部分かは不明 ＾＾；）

gmail.getFooterElement

Element gmail.getFooterElement()

ページフッタのルート DOM ノードを返します。

gmail.getActiveViewElement

Element gmail.getActiveViewElement()

アクティブビューのルート DOM ノード（inbox のメッセージリストや、 conversation スレッドのメッセージ部分など）を返します。

gmail.getSystemLabelsElement

Element gmail.getSystemLabelsElement()

ラベル・ナビゲーション・ボックスのルート DOM ノードを返します。

gmail.getConvRhsElement

Element gmail.getconvRhsElement()

アクティブビューが conversation なら、右側のペインのルート DOM ノードを返します。それ以外なら null を返します。

gmail.addNavModule

GmailNavBox gmail.addNavModule(title, opt_content, opt_color)

左側のナビゲーション・ペインに折りたたみ可能なボックスを追加し、それを表す GmailNavBox オブジェクトを返します。

title はナビゲーション・ボックスのタイトルとして表示されます。 opt_content はナビゲーション・ボックス内に表示する HTML です（省略可能）。 opt_color はナビゲーション・ボックスのボーダーカラーで、 "#0f0f0f", "rgb(255,255,0)", or "PapayaWhip" といった CSS 形式で指定します（省略可能）。

GmailNavBox オブジェクト

navbox.setColor

void navbox.setColor(cssColorStr)

ナビゲーション・ボックスのボーダーカラーを設定します。

cssColorStr は有効な CSS 形式で指定します。

navbox.setContent

void navbox.setContent(htmlStr)

ボックスの全内容を htmlStr で置き換えます。

htmlStr は文字列です。 DOM ノードは指定できません。

navbox.appendChild

void navbox.appendChild(element)

DOM ノードをナビゲーション・ボックスに追加します。

element は DOM ノードで、子ノードが存在してもかまいません。

navbox.getElement

Element navbox.getElement()

ナビゲーション・ボックスのルート DOM ノードを返します。

navbox.getTitleElement

Element navbox.getTitleElement()

ナビゲーションボックスのタイトルのルート DOM ノードを返します。

タイトルを設定するには以下のようにします。

navbox.getTitleElement().innerHTML = titleStr;

navbox.getContentElement

Element navbox.getContentElement()

ナビゲーション・ボックスの内容のルート DOM ノードを返します。

以下の 2 つのコードスニペットは同じ動作になります。

navbox.setContent(htmlStr);

navbox.getContentElement().innerHTML = htmlStr;

補足

ここまでが公式リファレンスの邦訳です。基本的な機能は主要な DOM ノードを取得するだけなので、けっこう簡単に使えそうですよね。

ただ、リファレンスだけでは実際にこれらの API を使ったスクリプトをどう作ればいいか、イメージが湧かないかもしれません。そんなときの参考としては、以下のページにあるサンプルコードが役に立つと思います。

http://code.google.com/p/gmail-greasemonkey/wiki/A...

ナビゲーション・ボックスをひとつ追加し、そこに現在のビューモードを表示する Greasemonkey スクリプトです。コメントを除けばわずか 20 行程度のソースなので、 Gmail Greasemonkey API を使ったスクリプトの流れを理解するのに最適です。

以上、本日は Gmail Greasemonkey API のリファレンスを邦訳してお届けしました。これによって日本発の Gmail 用 Greasemonkey スクリプトが少しでも増えれば幸いです。（私も含めて ＾＾；） Gmail の拡張に興味はあったけど手を出していなかった皆さん、これを機にぜひ挑戦してみてください！