1. 主页
  2. 文档
  3. Dart 2 中文文档
  4. 核心库
  5. 导览

导览

核心库导览

This page shows you how to use the major features in Dart’s core libraries. It’s just an overview, and by no means comprehensive. Whenever you need more details about a class, consult the Dart API reference.

dart:core
Built-in types, collections, and other core functionality. This library is automatically imported into every Dart program.
dart:async
Support for asynchronous programming, with classes such as Future and Stream.
dart:math
Mathematical constants and functions, plus a random number generator.
dart:convert
Encoders and decoders for converting between different data representations, including JSON and UTF-8.
dart:html
DOM and other APIs for browser-based apps.
dart:io
I/O for programs that can use the Dart VM, including Flutter apps, servers, and command-line scripts.

This page is just an overview; it covers only a few dart:* libraries and no third-party libraries.

Other places to find library information are the Pub site and the Dart web developer library guide. You can find API documentation for all dart:* libraries in the Dart API reference or, if you’re using Flutter, the Flutter API reference.

dart:core – 数值、集合、字符串及更多

The dart:core library (API reference) provides a small but critical set of built-in functionality. This library is automatically imported into every Dart program.

Printing to the console

The top-level print() method takes a single argument (any Object) and displays that object’s string value (as returned by toString()) in the console.

For more information on basic strings and toString(), see Strings in the language tour.

Numbers

The dart:core library defines the num, int, and double classes, which have some basic utilities for working with numbers.

You can convert a string into an integer or double with the parse() methods of int and double, respectively:

Or use the parse() method of num, which creates an integer if possible and otherwise a double:

To specify the base of an integer, add a radix parameter:

Use the toString() method to convert an int or double to a string. To specify the number of digits to the right of the decimal, use toStringAsFixed(). To specify the number of significant digits in the string, use toStringAsPrecision():

For more information, see the API documentation for int, double, and num. Also see the dart:math section.

Strings and regular expressions

A string in Dart is an immutable sequence of UTF-16 code units. The language tour has more information about strings. You can use regular expressions (RegExp objects) to search within strings and to replace parts of strings.

The String class defines such methods as split()contains()startsWith()endsWith(), and more.

Searching inside a string

You can find particular locations within a string, as well as check whether a string begins with or ends with a particular pattern. For example:

从字符串中提取数据

You can get the individual characters from a string as Strings or ints, respectively. To be precise, you actually get individual UTF-16 code units; high-numbered characters such as the treble clef symbol (‘\u{1D11E}’) are two code units apiece.

You can also extract a substring or split a string into a list of substrings:

转换为大写或小写

You can easily convert strings to their uppercase and lowercase variants:

Note: These methods don’t work for every language. For example, the Turkish alphabet’s dotless I is converted incorrectly.

Trimming and empty strings

Remove all leading and trailing white space with trim(). To check whether a string is empty (length is zero), use isEmpty.

Replacing part of a string

Strings are immutable objects, which means you can create them but you can’t change them. If you look closely at the String API reference, you’ll notice that none of the methods actually changes the state of a String. For example, the method replaceAll() returns a new String without changing the original String:

构建字符串

To programmatically generate a string, you can use StringBuffer. A StringBuffer doesn’t generate a new String object until toString() is called. The writeAll() method has an optional second parameter that lets you specify a separator—in this case, a space.

正则表达式

The RegExp class provides the same capabilities as JavaScript regular expressions. Use regular expressions for efficient searching and pattern matching of strings.

You can work directly with the RegExp class, too. The Match class provides access to a regular expression match.

More information

Refer to the String API reference for a full list of methods. Also see the API reference for StringBuffer, Pattern, RegExp, and Match.

集合

Dart ships with a core collections API, which includes classes for lists, sets, and maps.

列表

As the language tour shows, you can use literals to create and initialize lists. Alternatively, use one of the List constructors. The List class also defines several methods for adding items to and removing items from lists.

Use indexOf() to find the index of an object in a list:

Sort a list using the sort() method. You can provide a sorting function that compares two objects. This sorting function must return < 0 for smaller, 0 for the same, and > 0 for bigger. The following example uses compareTo(), which is defined by Comparable and implemented by String.

Lists are parameterized types, so you can specify the type that a list should contain:

Refer to the List API reference for a full list of methods.

A set in Dart is an unordered collection of unique items. Because a set is unordered, you can’t get a set’s items by index (position).

Use contains() and containsAll() to check whether one or more objects are in a set:

An intersection is a set whose items are in two other sets.

Refer to the Set API reference for a full list of methods.

Maps

A map, commonly known as a dictionary or hash, is an unordered collection of key-value pairs. Maps associate a key to some value for easy retrieval. Unlike in JavaScript, Dart objects are not maps.

You can declare a map using a terse literal syntax, or you can use a traditional constructor:

You add, get, and set map items using the bracket syntax. Use remove() to remove a key and its value from a map.

You can retrieve all the values or all the keys from a map:

To check whether a map contains a key, use containsKey(). Because map values can be null, you cannot rely on simply getting the value for the key and checking for null to determine the existence of a key.

Use the putIfAbsent() method when you want to assign a value to a key if and only if the key does not already exist in a map. You must provide a function that returns the value.

Refer to the Map API reference for a full list of methods.

Common collection methods

List, Set, and Map share common functionality found in many collections. Some of this common functionality is defined by the Iterable class, which List and Set implement.

Note: Although Map doesn’t implement Iterable, you can get Iterables from it using the Map keys and values properties.

Use isEmpty or isNotEmpty to check whether a list, set, or map has items:

To apply a function to each item in a list, set, or map, you can use forEach():

When you invoke forEach() on a map, your function must take two arguments (the key and value):

Iterables provide the map() method, which gives you all the results in a single object:

Note: The object returned by map() is an Iterable that’s lazily evaluated: your function isn’t called until you ask for an item from the returned object.

To force your function to be called immediately on each item, use map().toList() or map().toSet():

Use Iterable’s where() method to get all the items that match a condition. Use Iterable’s any() and every() methods to check whether some or all items match a condition.

For a full list of methods, refer to the Iterable API reference, as well as those for List, Set, and Map.

URIs

The Uri class provides functions to encode and decode strings for use in URIs (which you might know as URLs). These functions handle characters that are special for URIs, such as & and =. The Uri class also parses and exposes the components of a URI—host, port, scheme, and so on.

Encoding and decoding fully qualified URIs

To encode and decode characters except those with special meaning in a URI (such as /:&#), use the encodeFull() and decodeFull()methods. These methods are good for encoding or decoding a fully qualified URI, leaving intact special URI characters.

Notice how only the space between some and message was encoded.

Encoding and decoding URI components

To encode and decode all of a string’s characters that have special meaning in a URI, including (but not limited to) /&, and :, use the encodeComponent() and decodeComponent() methods.

Notice how every special character is encoded. For example, / is encoded to %2F.

Parsing URIs

If you have a Uri object or a URI string, you can get its parts using Uri fields such as path. To create a Uri from a string, use the parse() static method:

See the Uri API reference for more URI components that you can get.

Building URIs

You can build up a URI from individual parts using the Uri() constructor:

Dates and times

A DateTime object is a point in time. The time zone is either UTC or the local time zone.

You can create DateTime objects using several constructors:

The millisecondsSinceEpoch property of a date returns the number of milliseconds since the “Unix epoch”—January 1, 1970, UTC:

Use the Duration class to calculate the difference between two dates and to shift a date forward or backward:

Warning: Using a Duration to shift a DateTime by days can be problematic, due to clock shifts (to daylight saving time, for example). Use UTC dates if you must shift days.

For a full list of methods, refer to the API reference for DateTime and Duration.

Utility classes

The core library contains various utility classes, useful for sorting, mapping values, and iterating.

Comparing objects

Implement the Comparable interface to indicate that an object can be compared to another object, usually for sorting. The compareTo() method returns < 0 for smaller, 0 for the same, and > 0 for bigger.

Implementing map keys

Each object in Dart automatically provides an integer hash code, and thus can be used as a key in a map. However, you can override the hashCodegetter to generate a custom hash code. If you do, you might also want to override the == operator. Objects that are equal (via ==) must have identical hash codes. A hash code doesn’t have to be unique, but it should be well distributed.

Iteration

The Iterable and Iterator classes support for-in loops. Extend (if possible) or implement Iterable whenever you create a class that can provide Iterators for use in for-in loops. Implement Iterator to define the actual iteration ability.

Exceptions

The Dart core library defines many common exceptions and errors. Exceptions are considered conditions that you can plan ahead for and catch. Errors are conditions that you don’t expect or plan for.

A couple of the most common errors are:

NoSuchMethodError
Thrown when a receiving object (which might be null) does not implement a method.
ArgumentError
Can be thrown by a method that encounters an unexpected argument.

Throwing an application-specific exception is a common way to indicate that an error has occurred. You can define a custom exception by implementing the Exception interface:

For more information, see Exceptions (in the language tour) and the Exception API reference.

dart:async – asynchronous programming

Asynchronous programming often uses callback functions, but Dart provides alternatives: Future and Stream objects. A Future is like a promise for a result to be provided sometime in the future. A Stream is a way to get a sequence of values, such as events. Future, Stream, and more are in the dart:async library (API reference).

Note: You don’t always need to use the Future or Stream APIs directly. The Dart language supports asynchronous coding using keywords such as async and await. See the asynchronous programming codelab for details.

The dart:async library works in both web apps and command-line apps. To use it, import dart:async:

Future

Future objects appear throughout the Dart libraries, often as the object returned by an asynchronous method. When a future completes, its value is ready to use.

Using await

Before you directly use the Future API, consider using await instead. Code that uses await expressions can be easier to understand than code that uses the Future API.

Consider the following function. It uses Future’s then() method to execute three asynchronous functions in a row, waiting for each one to complete before executing the next one.

The equivalent code with await expressions looks more like synchronous code:

An async function can catch exceptions from Futures. For example:

Important: Async functions return Futures. If you don’t want your function to return a future, then use a different solution. For example, you might call an async function from your function.

For more information on using await and related Dart language features, see the asynchronous programming codelab.

Basic usage

You can use then() to schedule code that runs when the future completes. For example, HttpRequest.getString() returns a Future, since HTTP requests can take a while. Using then() lets you run some code when that Future has completed and the promised string value is available:

Use catchError() to handle any errors or exceptions that a Future object might throw.

The then().catchError() pattern is the asynchronous version of trycatch.

Important: Be sure to invoke catchError() on the result of then()—not on the result of the original Future. Otherwise, the catchError() can handle errors only from the original Future’s computation, but not from the handler registered by then().

Chaining multiple asynchronous methods

The then() method returns a Future, providing a useful way to run multiple asynchronous functions in a certain order. If the callback registered with then() returns a Future, then() returns an equivalent Future. If the callback returns a value of any other type, then() creates a new Future that completes with the value.

In the preceding example, the methods run in the following order:

  1. costlyQuery()
  2. expensiveWork()
  3. lengthyComputation()

Here is the same code written using await: