パッケージの作成

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 にあり、インポーターが外部にある場合は、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: ドキュメントを参照してください。

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

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

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

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

パッケージの詳細については、以下のリソースを参照してください。

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

特に記載がない限り、このサイトのドキュメントはDart 3.5.3を反映しています。最終更新日：2024年7月3日。ソースを表示または問題を報告する。