Skip to content
This repository has been archived by the owner on Mar 29, 2019. It is now read-only.

Latest commit

 

History

History
263 lines (214 loc) · 14 KB

extension-manifest.md

File metadata and controls

263 lines (214 loc) · 14 KB
title MetaDescription commitid status
Extension Manifest - package.json
At the core of Visual Studio Code's extensibility model is an extension (plug-in) manifest file where your extension declares its extension type(s), activation rules and runtime resources.
1f68e5e21c25890c3261c4f7c6203c8bb8a4ffe3
old

全てのVisual Studio Code拡張機能には、拡張機能フォルダのルートにマニフェストファイルpackage.jsonが必要です。

Fields

Name Required Type Details
name Y string 拡張機能の名称です。スペースなしの小文字でなければなりません。
version Y string SemVerに従います。
publisher Y string 拡張機能の公開者名です。
engines Y object 拡張機能とVS Codeバージョンの互換性です。vs codeを含む最小バージョンを指定します。*を指定することはできません。例: ^0.10.5を指定したなら^0.10.5以降に互換性があることを示します。
license string npm's documentationを参照してください。ルートにLICENSEファイルを配置した場合は値を"SEE LICENSE IN <filename>"にすることを推奨します。
displayName string Marketplaceで使用する拡張機能の表示名です。
description string 短くまとめた拡張機能の説明です。
categories string[] 拡張機能のカテゴリーを指定します。値は[Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, Other, Extension Packs]を利用可能です。
keywords array 検索に役立つKeywordsを指定します。
galleryBanner object アイコンに合うようにMarketplaceのフォーマット(主にバナー)を指定します。詳細は下記を参照してください。
preview boolean MarketplaceのラベルにPreviewフラグを設定します。
main string 拡張機能のエントリーポイントを指定します。
contributes object 拡張機能のコントリビューションを指定するオブジェクトです。
activationEvents array 拡張機能をロードするタイミングを指定します。
badges array Marketplaceのサイドバーに表示するバッジの配列です。例: バッジの画像URLを示すurl、バッジのリンク先hrefとdescription
markdown string MarketplaceのMarkdownレンタリングエンジンを制御します。github(既定)かstandardのいずれかを指定します。
dependencies object 拡張機能に必要なランタイムNode.js依存関係を指定します。npm's dependenciesと同じです。
devDependencies object 拡張機能に必要なデベロップメントNode.js依存関係を指定します。npm's devDependenciesと同じです。
extensionDependencies array 拡張機能IDの配列を指定します。VS Code内に指定した拡張機能がなければこれらをインストールします。このIDは常に${publisher}.${name}です。例: vscode.csharp (編集メモ:Extension Packで主に使用します。
scripts object npm's scriptsと同じですがextra VS Code specific fieldsを使用できます。
icon string 128x128pxアイコンへのファイルパスを指定します。

またnpm's package.json referenceを確認してください。

Example

次に完全なpackage.jsonを示します。

{
    "name": "spell",
    "displayName": "Spelling and Grammar Checker",
    "description": "Detect mistakes as you type and suggest fixes - great for Markdown.",
    "icon": "images/spellIcon.svg",
    "version": "0.0.19",
    "publisher": "seanmcbreen",
    "galleryBanner": {
        "color": "#0000FF",
        "theme": "dark"
    },
    "license": "SEE LICENSE IN LICENSE.md",
    "bugs": {
        "url": "https://github.com/Microsoft/vscode-spell-check/issues",
        "email": "smcbreen@microsoft.com"
    },
    "homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
    "repository": {
        "type": "git",
        "url": "https://github.com/Microsoft/vscode-spell-check.git"
    },
    "categories": [
        "Linters", "Languages", "Other"
    ],
    "engines": {
        "vscode": "^1.0.0"
    },
    "main": "./out/extension",
    "activationEvents": [
        "onLanguage:markdown"
    ],
    "contributes": {
        "commands": [
            {
                "command": "Spell.suggestFix",
                "title": "Spell Checker Suggestions"
            }
        ],
        "keybindings": [
            {
                "command": "Spell.suggestFix",
                "key": "Alt+."
            }
        ]
    },
    "badges": [
        {
            "url": "https://david-dm.org/Microsoft/vscode-spell-check.svg",
            "href": "https://david-dm.org/Microsoft/vscode-spell-check",
            "description": "Dependency Status"
        }
    ],
    "scripts": {
        "vscode:prepublish": "tsc -p ./",
        "compile": "tsc -watch -p ./"
    },
    "dependencies": {
        "teacher": "^0.0.1"
    },
    "devDependencies": {
        "vscode": "^1.0.0"
    }
}

Marketplace Presentation Tips

ここではVS Code Marketplaceの見栄えをよくするヒントと推奨事項を説明しています。

常に最新のvsceを使用できるようにnpm install -g vsceを使用してください。

拡張機能のルートフォルダにREADME.mdファイルを置くことで、その内容をMarketplaceの拡張機能ページ本文に含めます。REAMDE.md内では相対パスの画像リンクを使用可能です。

次に例を示します:

  1. Spell-Checker
  2. MD Tools

適切な表示名と説明を入力します。これはMarketplaceと製品の表示において重要です。これら文字列はVS Codeのテキスト検索にも使用されるため、関連するワードを使用することで多くに役立ちます。

    "displayName": "Spelling and Grammar Checker",
    "description": "Detect mistakes as you type and suggest fixes - great for Markdown.",

アイコンと対比的なバナーの色は、Marketplaceのヘッダーを綺麗にします。theme属性にはフォントの色darkかlightを指定できます。

    "icon": "images/spellIcon.svg",
    "galleryBanner": {
        "color": "#5c2d91",
        "theme": "dark"
    },

あなたが設定できるオプションリンク(bugs, homepage, repository)があります。これはMarketplaceのResourcesセクション下に表示します。

    "license": "SEE LICENSE IN LICENSE.md",
    "bugs": {
        "url": "https://github.com/Microsoft/vscode-spell-check/issues"
    },
    "homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
    "repository": {
        "type": "git",
        "url": "https://github.com/Microsoft/vscode-spell-check.git"
    }
Marketplace Resources link package.json attribute
Issues bugs:url
Repository repository:url
Homepage homepage
License license

拡張機能のためにcategoryを指定します。同じcategory内の拡張機能は、Marketplaceで見つけやすいようにタグ分けされます。

Note: あなたの拡張機能にあった値を指定してください。使用できる値は次の通りです。[Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, Other]

    "categories": [
        "Linters", "Languages", "Other"
    ],

Tip: Extension Manifest Editorを使うと、Marketplaceに公開されたときのREADME.mdとpackage.jsonのメタデータがどのように見えるかをプレビューできます。

Combining Extension Contributions

yo codeジェネレーターを使うとTextMateテーマ、カラライザー、スニペットを簡単にパッケージ化して新しい拡張機能を作成できます。これを実行したとき、ジェネレータはオプションに沿ってそれぞれ完全な独立型の拡張機能パッケージを作成します。しかし、複数のコントリビューションを組み合わせた拡張機能のほうが便利です。たとえば、新しい言語のサポートを追加する場合は、ユーザーにカラライザーとスニペット、さらにはデバッグサポートの両方の言語定義を提供したいと考えると思います。

拡張機能のコントリビューションを結合するには、既存の拡張マニフェストpackage.jsonを編集して、新しいコントリビューションと関連ファイルを追加するだけです。

次は、LaTexの言語定義(言語識別とファイル拡張)、カラライザー(grammar)、スニペットを含む拡張マニフェストです。

{
    "name": "language-latex",
    "description": "LaTex Language Support",
    "version": "0.0.1",
    "publisher": "someone",
    "engines": {
        "vscode": "0.10.x"
    },
    "categories": [
        "Languages",
        "Snippets"
    ],
    "contributes": {
        "languages": [{
            "id": "latex",
            "aliases": ["LaTeX", "latex"],
            "extensions": [".tex"]
        }],
        "grammars": [{
            "language": "latex",
            "scopeName": "text.tex.latex",
            "path": "./syntaxes/latex.tmLanguage"
        }],
        "snippets": [{
            "language": "latex",
            "path": "./snippets/snippets.json"
        }]
    }
}

categories属性がMarketplace上で見つけやすいように、LanguagesとSnippetsの両方を含んでいることに注目してください。

Tip: マージしたコントリビューションが同じ識別子を使用していることを確認してください。上記の例では、言語識別子に"latex"を使用しています。これによりVS Codeは、カラライザー (grammar) とスニペットがLaTeX言語用であり、LaTeXファイルを編集するときにアクティブになることを知ることができます。

Extension Packs

また'Extension Packs'で別の拡張機能を含めることが可能です。Extension Packは、拡張機能を一緒にインストールできるセットのことです。これにより、お気に入りの拡張機能をほかのユーザーと共有したり、PHP開発のような特定シナリオ用の拡張機能セットを作成して、開発の準備を早める手助けできます。

Extension Packは他のコントリビューションを含めることができます。これはpackage.jsonファイル内のextensionDependencies属性を使って表現します。

次の例ではPHP用のExtension Packにデバッガ、言語サービスおよびフォーマッタを含みます:

  "extensionDependencies": [
      "felixfbecker.php-debug",
      "felixfbecker.php-intellisense",
      "Kasik96.format-php"
  ]

これによりExtension Packをインストールすると、VS Codeはその拡張機能の依存関係もインストールするようになりました。

なおExtension PackはExtension Packsのカテゴリーに分類する必要があります。

  "categories": [
      "Extension Packs"
  ],

Extension Packにはyo code Yeoman generatorを使用できます。オプションでVS Codeインスタンスに現在インストールされている拡張機能をパックに含めることも可能です。このように、お気に入りの拡張機能でExtension Packを簡単に作成し、Marketplaceに公開して他のユーザーと共有することができます。

便利なNodeモジュール

VS Code拡張機能の作成に役立つNode.jsモジュールがnpmjsにあります。これらを拡張機能のdependenciesに含めることができます。

次のステップ

VS Codeの拡張モデルの詳細については次のトピックを試してください: