adobe/bracketsの拡張機能を記述する方法

Using modules

• あなたの拡張機能のフォルダ・ツリーから、モジュールを読み込むために、あなたの拡張機能のルート・フォルダへの相対パスと一緒にrequire()を使用します。
• Bracketコアから、モジュールを読み込むために、Bracket srcルートへの相対パスと一緒にbrackets.getModule()を使用します。
• あなたは、（まだ）他の拡張機能から、モジュールを読み込むことができません。

また、あなたは、拡張機能の中にパッケージ化された、他のファイルを使用することができます。－例えば、下記の「CSSファイルの読み込み」を参照してください。

Adding menu items & keyboard shortcuts

コードサンプルについては、簡単な「Hello World」拡張機能(原文リンク)を参照してください。

新しい動作については、まず、CommandManager.register()を通して、あなたの動作を実装するコマンドを登録します。 これは、あなたのハンドラ関数にCommand id (string)を実際にマッピングします。 他の拡張機能との衝突を避けるために、あなたのコマンドのID（例えばmyorg.myextension.mycommand）のためのパッケージ形式の命名を使用してください。 （また、以下を参照してください：コマンド・アーキテクチャの高レベルの概要）。

メニュー項目の追加： AppMenuBar定数と一緒に、Menus.getMenu()を呼び出すことで、最上位のメニューを手に入れます。 （現在、FILE_MENU、EDIT_MENU、VIEW_MENU、NAVIGATE_MENUまたはHELP_MENU）。 続いて、theMenu.addMenuItem()を通じてメニュー項目を追加します。 それをあなたのCommand idにリンクします。それが作成されたとき、メニュー項目のラベルは、あなたが、コマンドに与えた文字列名です。

便利にするために、また、addMenuItem()は、同時に、あなたのCommandのためのキーボード・ショートカットを作成できます。

コンテキスト・メニューの項目を追加します。： ContextMenuIds定数と一緒にMenus.getContextMenu()を呼び出すことで、コンテキストメニューを取得します。 （現在、EDITOR_MENU、INLINE_EDITOR_MENU、PROJECT_MENUまたはWORKING_SET_MENU）。 続いて、theContextMenu.addMenuItem()によって、メニュー項目を追加します。正確に、あなたのCommand idに、一番上のレベルのメニュー項目などを結合します。

メニューの仕切りの追加する： 先ほど説明したように、メニューの仕切りの追加する最上位やコンテキストメニューを取得します。 続いて、theMenu.addMenuDivider()を通じて、メニューの仕切りを追加します。 それは、現在、メニューの最後の位置に既定の設定になっています。 あなたは、それに対応して仕切りを配置する位置パラメータの最初と最後に、それを配置する利用可能な選択肢を持っています。 さらに、あなたは、前後に、位置パラメータを設定することができます。Command idに渡します。そして、それに対応して仕切りを配置します。

キーボード・ショートカットを追加する： いずれのメニュー項目にも関連していない、キーボード・ショートカットを追加するには、 直接、ショートカットをあなたのCommand idにリンクするKeyBindingManager.addBinding()を呼び出します。 利用できるショートカットを参照するために、そして、あなたが使用するショートカットをリストに追加するために、Bracketのショートカット・ページを必ず使用します。

キーボード・イベントを拒否するために、そして、Bracketの他の部分は、それを操作できます。 すでに、あなたが、それを返す時に、拒否されている$.Promiseを返すあなたのCommandハンドラを作成します。 （これは、カーソルが特定の場所にあるとき、あなたが、Enterのような編集キーだけを上書きすることを望む場合に役に立ちます。 そして、その他の場合、既定の動作を提供します。;あるいは、常に、コード・エディタでキーを上書きします。 しかし、より簡単なテキストフィールドで既定の動作を提供します。）。（メモ：Sprint 18以降を必要とします）

Adding new UI elements

エディタの下のパネルを追加します。：CSSクラスの .bottom-panelを使用します。;例えば、JSLintのbottom-panel.htmlを参照してください。 PanelManager.createBottomPanel("yourExtension.name", $(panelHtml))を使用して、ステータス・バー上に、あなたのパネルを追加します。 あなたは、いくつかの拡張機能に、Resizer.makeResizable()と手動でパネルのDOMの挿入を見るかもしれません。 しかし、この練習は、PanelManagerの導入以来、段階的に廃止されています。

非公式の技術－DOM作業を通して、直接、UI要素を追加します。しかし、あなたを、不確実な基盤に配置します。 コードは、Bracketは、UIを発展させる更新として、これを破壊します。 最も良い練習として、これらのコード・スニペットを使用します。それは、可能な限り与えられるリスクと同じぐらいうまく動作します。：

ツールバー・アイコンを追加する： (unofficial)は、$myIcon.appendTo($("#main-toolbar .buttons"))を使用します。

上部のpanel/toolbarを追加します。： (unofficial)は、$myPanel.insertBefore("#editor-holder")を使用します。

UIデザイン： 機能拡張UIガイドラインに従ってください。

CSSファイルを読み込みます： ExtensionUtils.loadStyleSheet()を使用します。それは、追跡するために使用することができるPromiseをあなたに返します。 CSSが、完了した読み込みであるとき、誤って、中心的なBracket UIを破壊するのを回避するために、CSSクラスをあなたのUIのルートに配置します。 そして、例えばli { ... } use .myExtension li { ... }.の代わりにあなたのすべてのCSS規則が派生したセレクタに含まれていることを確認してください。

Extending specific Brackets features

一覧にあるそれぞれのAPIについては、詳細は、ドキュメンテーションを参照してください。

クイック編集（インライン編集）： 拡張機能を作成するために、それは、EditorManager.registerInlineEditProvider()を使用して、Ctrl+E（インライン・カラー・ピッカーのような）上で反応します。 複数の「プロバイダー」のすべてが、与えられたコンテキストで応答するようにしたい場合、しかしながら、最初のものが優先されます。 －まだ、プロバイダーを通して、優先順位や循環の概念が、ありません。

簡単なドキュメント： クイック編集と同様に、しかし、その代わりにEditorManager.registerInlineDocsProvider()と一緒に、あなたのプロバイダーを登録します。

クイック検索の定義： 「@」接頭辞が存在するとき、QuickOpen.addQuickOpenPlugin().Registerを使用して、 固有の言語idとmatch()からtrueを返すだけのための、新しい言語のための簡単な記号ナビゲーションを提供します。 （簡単な例のためのCSSサポートを参照してください）。

クイックオープン： 新しい全体の検索機能（クイックオープンのような）を追加するには、空のlanguageIds配列と一緒に、QuickOpen.addQuickOpenPlugin()を使用します。 新しいものを選択し、対応するmatch()のための独自の接頭辞、 そして、あなたのユーザー定義した接頭辞と一緒にQuickOpen.beginSearch()を起動する新しいコマンドを登録します。 （簡単な例のためのファイルのナビゲーション・ショートカット拡張機能を参照してください）。

コードヒント： 拡張機能を作成するために、CodeHintManager.registerHintProvider()を使用して、コード・ヒント・ポップアップを表示します。 クイック編集と異なり、これらのプロバイダーは、競合を解決するために、様々な優先順位を持つことができます。;より具体的なプロバイダが優先されます。 －しかし、クイック編集と同様に、「勝利する」プロバイダーだけが、表示されます。

定義へ移動： 拡張機能を作成するために、EditorManager.registerJumpToDefProvider()を使用して、Ctrl-J（定義へ移動）上で反応します。 クイック編集と同様に、最初のプロバイダは、勝利する指定されたカーソル位置に応答します。

構文の色分け： 拡張機能は、LanguageManager.defineLanguage()を通じて、新しいコードに色をつける「modes」を追加することができます。詳細は言語サポートを参考にしてください。

リンティング： 与えられた言語のためのlinting/inspectionを提供するために、CodeInspection.register()を使用します。 組み込みのJSLint機能のように、プロバイダーは、ファイルが開かれる、あるいは、保存されるたびに、呼び出されます。 そして、その結果は、エディタの下のパネルに表示されます。（しかしながら、プロバイダーは、将来に、更に頻繁に実行されるかもしれません）。 現在、言語ごとに、1つのプロバイダーだけが受け入れられます。それにもかかわらず、拡張機能は、JavaScriptのための既定のJSLintプロバイダーを置き換えることができます。

ファイル・ツリー： project/ProjectManagerモジュールのためのドキュメンテーションを調べます。 Bracket 0.44以降では、あなたが、ツリーを装飾するために呼び出すことができる（addIconProviderとaddClassesProvider）関数が、あります。

Accessing resources (e.g. images) in your extension

拡張機能は、（半-）任意のパスにインストールすることができます。例えば、あなたは、brackets/src/extensions/dev/fooディレクトリで拡張機能を開発するかもしれません。 ユーザーは、/Users//Library/Application Settings/Brackets/extensions/user/barにインストールされるかもしれません。

ありがたいことに、あなたの拡張機能のmain.jsファイルに渡される必要とされるコンテキストは、あなたが、パスを解決するために役立てることができます。 require.toUrlとあなたが、相対的に作成したいサイト・ルートへ（あなたのモジュールの）相対パスを呼び出します。

重要： あなたが、あなたのモジュールに渡された、必要なオブジェクトを使用していることを確認してください。グローバルではありませんが、オブジェクトが必要です。

例えば、あなたが、あなたの拡張機能の最上位のfooフォルダで、awesome.jpgを持っている場合、あなたは、require.toUrl('./awesome.jpg')を行うことができます。 そして、あなたが、それと/Users//Library/Application Settings/Brackets/extensions/user/bar/awesome.jpgを呼び出すとき、 あなたのユーザーが、それを呼び出すとき、それは、/extensions/dev/foo/awesome.jpgのような何かを返します。 あなたが、ＵＲＬに与えるパスは、あなたの拡張機能の最上位のフォルダの相対パスである必要があります。（はい、サブディレクトリが動作します）、 そして、あなたが、戻って取得するURLは、サイト・ルートの相対パスです。（すなわち、それは「/」で始まります）。

Working with Preferences

あなたの拡張機能は、Bracketの環境設定にアクセスすることができます。 そして、独自の環境設定を定義します。あなたの拡張機能に固有の環境設定については、 あなたは、環境設定の全てが持っている接頭辞を確認する必要があります。 そのため、それらは、他のどんな環境設定も破壊しません。

詳細については、完全な環境設定のシステムドキュメンテーション(原文リンク)を参照してください。 しかし、ここに、あなたが、知っている必要があるAPIの中心部品を取り扱う例があります。：

var PreferencesManager = brackets.getModule("preferences/PreferencesManager"),
    prefs = PreferencesManager.getExtensionPrefs("myextensionname");

// First, we define our preference so that Brackets knows about it.
// Eventually there may be some automatic UI for this.
// Name of preference, type and the default value are the main things to define.
// This is actually going to create a preference called "myextensionname.enabled".

// まず、私たちは、私たちの設定を定義するため、Bracketは、それについて、知っています。
// 最終的に、このために、いくつかの自動UIが、あるかもしれません。
// 設定の名前、型と既定の値は、定義する主なものです。
// これは、実際に「myextensionname.enabled」と呼ばれる設定を作成しようとしています。

prefs.definePreference("enabled", "boolean", true);

// Set up a listener that is called whenever the preference changes
// You don't need to listen for changes if you can just look up the current value of
// the pref when you're performing some operation.

// 設定が変更されるたびに、呼び出されるリスナーを設定します。
// あなたが、いくつかの操作を実行しているとき、
// あなたが、実際に、prefの現在の値を調べることができる場合、あなたは、変更を聞き取る必要はありません。

prefs.on("change", function () {

    // This gets the current value of "enabled" where current means for the
    // file being edited right now.

// これは、「enabled」の現在の値を取得します。ここで、ファイルの現在の手段は、今、編集されています。

    doSomethingWith(prefs.get("enabled"));
});

// This will set the "enabled" pref in the same spot in which the user has set it.
// Generally, this will be in the user's brackets.json file in their app info directory.

// これは、ユーザーが、それに設定した同じ場所で「enabled」なprefを設定します。
// 通常、これは、それらのアプリケーション情報ディレクトリ内のユーザーのbrackets.jsonファイルの中にあります。

prefs.set("enabled", false);

// Then save the change

// 続いて、変更を保存します。

prefs.save();

Accessing Node APIs

Bracketには、組み込みのNode.js(原文リンク)サーバが含まれています。それは、サイドプロセスとして実行されます。あなたの拡張機能は、ノード内で実行されるコードを含むことができます。－ 役に立つノードのAPIにアクセスし、そして、役に立つNPMライブラリを引き出します。詳細に付いては、Bracketのノード・インスタンスの実行コード(原文リンク)を、お読みください。