如何建立一個dart package

推薦一個做者的package，一個方便flutter初學者使用編寫計算器的庫。
點擊獲取

建立packages

dart生態使用pakcage來分享ku或者工具。下面咱們來看一下最多見的庫的package的建立。

庫的組成

下面的示意圖展現了最簡單的庫結構：

庫的最基本組成：

pubspec文件

dart應用也是使用這個文件，這個文件中沒有特殊的標識符說明當前的項目是package仍是app。

lib 文件夾

如咱們所想，庫代碼放在lib文件夾中。給文件夾是公開可訪問的。你能夠重建一個子目錄，一般來講，實現代碼放在lib/src文件夾下。src文件夾應該認爲是私有的。其餘package不該該直接從src文件夾中import。你能夠export src文件夾中的文件。

提示 當聲明瞭`library`指令，會依據路徑和文件名生成惟一的tag。所以咱們通常應該忽略這個聲明，除非你打算生成library-level等級的文檔。

構建一個library package

獨立的小的庫組成的library pacage是最容易維護，擴展，測試的。
大多數的例子，每一個類應該是個小的library，除非某些類之間有緊密的關係。

提示你也許據說過`part`指令，它容許你把ku分寫道幾個小的dart文件中。在建立小的ku時，建議不要使用part指令。

在lib文件夾下建立一個主要的庫文件，形式如lib/<package-name>.dart,用來導出全部的公共接口。這樣用戶就能夠經過一個文件導入全部的功能。

lib文件夾也許包括其餘的接口文件，像是一些no-src的，例如也許你的庫是跨平臺的，你建立了分開的入口。好比依賴dart:io或者dart:html的。一些庫作了import前綴，用來指明不一樣的導入需求（當主庫不能適應使用環境時）。

我來看下現實中的庫的組織結構。shelf庫提供了建立webserver的簡單方法，它提供了經常使用的dart package結構。

主庫shelf.dart的處處內容。

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/handlers/logger.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/pipeline.dart';
export 'src/request.dart';
export 'src/response.dart';
export 'src/server.dart';
export 'src/server_handler.dart';

shelf庫也包含一個小的庫：shelf_io。這個用來處理來自dart:io的HttpRequest對象。

web app提示:爲了編譯時的性能，建議把是下代碼放到`lib/src`文件夾下，也要避免使用`package:package_name/src..`這類導入方法。

import 庫文件

當導入一個庫文件，你可使用package:指令加上文件uri路徑。

import 'package:utilities/utilities.dart';

當文件都在lib文件夾中/外時可使用相對路徑導入。
然而又是你必須使用package:引入一個文件，無論它始在lib內仍是外。若是有疑問就用package:,它都能勝任。

下面視圖，說明引入lib/foo/a.dart的不一樣方式。

提示:圖中使用的`import'../foo/a/dart';可使用`import 'package:my_package/foo/a.dart`。

條件引入

若是你的庫支持多個平臺，那麼你可能須要考慮按條件引入和導出庫文件。一般的狀況是支持web和本地平臺。

想要有條件的引入和導出，你須要檢查dart:*的存在。整個例子根據不一樣的存在導出文件。

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation

代碼作的事：

• 一個應用可以使dart:io，導出src/hw_io.dart.
• 一個應用使用dart:html，導出src/hw_html.dart.
• 其餘的導出dart:hw_one.dart。

條件導出和上面的代碼基本同樣，可是使用的是import指令。

提示 條件導出和引入只是檢查庫是否在當前平臺可用，而不是實際導入或使用。

全部的條件導出不行hi是新建同樣的api，例如這裏的dart:io實現。

import 'dart:io';

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

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

這裏有一個默認實現，這是一部分拋出錯誤的代碼。

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);
}

添加其餘的文件

一個設計良好的package是易測試的。咱們建議你使用test package編寫測試文件。把測試代碼放到test文件夾（頂級目錄）中。

若是你編寫了命令行工具想要別人使用，那麼把它們放到bin文件夾中，這是慣例。實現使用pub global active運行命令行工具。把命令放到pubspec的executables字段域下面，這樣容許用戶直接運行，而不須要調用pub global run，來運行。

在你的項目裏添加example頂級文件夾，對於怎麼使用你的庫是有用的。

開發時使用的工具或者命令行文件而不是最終給用戶使用的，放到tool文件夾中。

發佈到pub.dev網址你須要添加的其餘文件包括README.md以及CHANGELOG.md。其餘內容能夠查看pub package layout conventions。

文檔

你可使用dartdoc工具生成文檔。文檔使用文檔註釋——///來解析。

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

能夠經過shelf document來查看生成的文檔示例。

提示 想要生成時包含任何ligrary-level的文檔，你須要聲明library指令。

發佈開源庫

若是你的庫是開源的，咱們建議把它分享到pub.dev網站。發佈和更新你的代碼使用pub publish命令。它會上傳你的代碼而後生成或者更新頁面。查看示例shelf package。或者查看發佈這一張，瞭解如何準備和發佈你的package。

pub.dev網站不僅是保存你的package，並且會生成和host你的package api文檔。最新生成的文檔會在package的About tab。更多示例查看shelf package的API docs。更多的版本查看pacage頁面的Version tab。

爲了使你的package文檔看起來不錯，跟隨下面作。

• 發佈前，運行dartdoc工具來生成文檔。
• 發佈後檢查Version tab，保證成功生成。
• 若是文檔沒有生成，查看Version tab，查看文檔導出。