パッケージの作成

Dartエコシステムでは、ライブラリやツールなどのソフトウェアを共有するためにパッケージを使用します。このページでは、標準的な共有パッケージを作成する方法を説明します。

パッケージの初期ディレクトリと構造を作成するには、dart create コマンドと package テンプレートを使用します。

dart create -t package <PACKAGE_NAME>

次の図は、パッケージの最もシンプルなレイアウトを示しています。

ライブラリの最小要件は次のとおりです。

pubspecファイル

ライブラリの pubspec.yaml ファイルは、アプリケーションパッケージの場合と同じです。パッケージがライブラリであることを示す特別な指定はありません。

libディレクトリ

予想どおり、ライブラリコードは lib ディレクトリの下に配置され、他のパッケージからアクセス可能です。必要に応じて、lib の下に任意の階層を作成できます。慣例により、実装コードは lib/src の下に配置されます。lib/src の下のコードはプライベートと見なされ、他のパッケージは src/... をインポートする必要はありません。lib/src の下の API を公開するには、lib の直下にあるファイルから lib/src ファイルをエクスポートできます。

パッケージは、*ミニライブラリ*と呼ばれる、小さく個別のライブラリを作成すると、保守、拡張、テストが最も容易になります。ほとんどの場合、2 つのクラスが密接に結合している状況を除き、各クラスは独自のミニライブラリに配置する必要があります。

lib の直下に「メイン」ライブラリファイル、lib/<package-name>.dart を作成し、すべての公開 API をエクスポートします。これにより、ユーザーは単一のファイルをインポートするだけで、ライブラリのすべての機能を利用できるようになります。

lib ディレクトリには、インポート可能なその他の非 src ライブラリも含まれる場合があります。たとえば、メインライブラリがクロスプラットフォームで動作するが、dart:io または dart:js_interop に依存する個別のライブラリを作成する場合などです。一部のパッケージには、メインライブラリではない場合に、プレフィックスを付けてインポートすることを意図した個別のライブラリがあります。

実際のパッケージの編成を見てみましょう: shelf。 shelf パッケージは、Dart を使用して Web サーバーを簡単に作成する方法を提供し、Dart パッケージで一般的に使用される構造でレイアウトされています。

lib の直下にあるメインライブラリファイル shelf.dart は、lib/src のいくつかのファイルから API をエクスポートします。意図した以上の API を公開しないようにし、開発者にパッケージの公開 API 全体の概要を把握してもらうために、shelf.dart は show を使用してエクスポートするシンボルを正確に指定します。

export 'src/cascade.dart' show Cascade;
export 'src/handler.dart' show Handler;
export 'src/hijack_exception.dart' show HijackException;
export 'src/middleware.dart' show Middleware, createMiddleware;
export 'src/middleware/add_chunked_encoding.dart' show addChunkedEncoding;
export 'src/middleware/logger.dart' show logRequests;
export 'src/middleware_extensions.dart' show MiddlewareExtensions;
export 'src/pipeline.dart' show Pipeline;
export 'src/request.dart' show Request;
export 'src/response.dart' show Response;
export 'src/server.dart' show Server;
export 'src/server_handler.dart' show ServerHandler;

shelf パッケージには、ミニライブラリ shelf_io も含まれています。このアダプターは dart:io の HttpRequest オブジェクトを処理します。

別のパッケージのライブラリファイルをインポートする場合は、package: ディレクティブを使用してそのファイルの URI を指定します。

import 'package:utilities/utilities.dart';

独自のパッケージからライブラリファイルをインポートする場合は、両方のファイルが lib 内にある場合、または両方のファイルが lib 外にある場合は、相対パスを使用します。インポートされるファイルが lib にあり、インポート元が lib 外にある場合は、package: を使用します。

次のグラフィックは、lib と web の両方から lib/foo/a.dart をインポートする方法を示しています。

ライブラリが複数のプラットフォームをサポートしている場合、ライブラリファイルを条件付きでインポートまたはエクスポートする必要がある場合があります。一般的なユースケースは、Web とネイティブの両方のプラットフォームをサポートするライブラリです。

条件付きでインポートまたはエクスポートするには、dart:* ライブラリの存在を確認する必要があります。ここでは、dart:io と dart:js_interop の存在を確認する条件付きエクスポートコードの例を示します。

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation

そのコードが行っていることは次のとおりです。

• dart:io を使用できるアプリ（たとえば、コマンドラインアプリ）では、src/hw_io.dart をエクスポートします。
• dart:js_interop を使用できるアプリ（Web アプリ）では、src/hw_web.dart をエクスポートします。
• それ以外の場合は、src/hw_none.dart をエクスポートします。

ファイルを条件付きでインポートするには、上記のコードと同じコードを使用しますが、export を import に変更します。

条件付きでエクスポートされたすべてのライブラリは、同じ API を実装する必要があります。たとえば、dart:io の実装は次のようになります。

import 'dart:io';

void alarm([String? text]) {
  stderr.writeln(text ?? message);
}

String get message => 'Hello World from the VM!';

そして、デフォルトの実装は次のようになります。これは UnsupportedError をスローするスタブを使用します。

void alarm([String? text]) => throw UnsupportedError('hw_none alarm');

String get message => throw UnsupportedError('hw_none message');

どのプラットフォームでも、条件付きエクスポートコードを持つライブラリをインポートできます。

import 'package:hw_mp/hw_mp.dart';

void main() {
  print(message);
}

適切に設計されたパッケージはテストが容易です。test パッケージを使用してテストを作成し、テストコードをパッケージのトップにある test ディレクトリに配置することを推奨します。

一般公開を目的としたコマンドラインツールを作成した場合は、公開されている bin ディレクトリに配置します。dart pub global activate を使用して、コマンドラインからツールを実行できるようにします。pubspec の executables セクションにツールをリストすると、ユーザーは dart pub global run を呼び出すことなく直接実行できます。

ライブラリの使用方法の例を含めることは役立ちます。これは、パッケージのトップにある example ディレクトリに配置します。

開発中に作成された、一般公開されないツールや実行可能ファイルは、tool ディレクトリに配置します。

ライブラリを pub.dev サイトに公開するために必要なその他のファイル（README.md や CHANGELOG.md など）については、「パッケージの公開」で説明しています。パッケージディレクトリの構成方法については、「pubパッケージレイアウト規則」を参照してください。

dart doc ツールを使用して、ライブラリの API ドキュメントを生成できます。dart doc は、/// 構文を使用するドキュメントコメントを探してソースを解析します。

/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

生成されたドキュメントの例については、shelf ドキュメントを参照してください。

生成されたドキュメントにライブラリレベルのドキュメントを含めるには、library ディレクティブを追加し、コメントを直接その上に付けます。ライブラリのドキュメント作成の理由と方法については、「Effective Dart: Documentation」を参照してください。

ライブラリがオープンソースの場合は、pub.dev サイトで共有することを推奨します。ライブラリを公開または更新するには、pub publish を使用します。これは、パッケージをアップロードし、そのページを作成または更新します。例として、shelf パッケージのページを参照してください。パッケージを公開する準備をする方法の詳細については、「パッケージの公開」を参照してください。

pub.dev サイトは、パッケージをホストするだけでなく、パッケージの API リファレンスドキュメントを生成してホストします。最新の生成されたドキュメントへのリンクは、パッケージの **About** ボックスにあります。たとえば、shelf パッケージのAPI ドキュメントを参照してください。以前のバージョンのドキュメントへのリンクは、パッケージページの **Versions** タブにあります。

パッケージの API ドキュメントが pub.dev サイトで見栄えがするように、次の手順に従ってください。

• パッケージを公開する前に、dart doc ツールを実行して、ドキュメントが正常に生成され、期待どおりに見えることを確認してください。
• パッケージを公開した後、**Versions** タブを確認して、ドキュメントが正常に生成されたことを確認してください。
• ドキュメントがまったく生成されなかった場合は、**Versions** タブで **failed** をクリックして dart doc の出力を表示してください。

パッケージについてさらに学ぶには、次のリソースを使用してください。

• ライブラリとインポートでは、ライブラリファイルの使用について説明しています。
• 特に パッケージレイアウト規則 は、パッケージのドキュメントで役立ちます。
• コミットしないものでは、ソースコードリポジトリにコミットすべきでないものについて説明しています。
• dart-lang 組織の新しいパッケージは、ベストプラクティスを示す傾向があります。これらの例を検討してください: dart_style、 path、 shelf、 source_gen、および test。