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:

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.

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:

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:

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).

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:

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 try–catch.

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:

Waiting for multiple futures

Sometimes your algorithm needs to invoke many asynchronous functions and wait for them all to complete before continuing. Use the Future.wait()static method to manage multiple Futures and wait for them to complete:

Stream

Stream objects appear throughout Dart APIs, representing sequences of data. For example, HTML events such as button clicks are delivered using streams. You can also read a file as a stream.

Using an asynchronous for loop

Sometimes you can use an asynchronous for loop (await for) instead of using the Stream API.

Consider the following function. It uses Stream’s listen() method to subscribe to a list of files, passing in a function literal that searches each file or directory.

The equivalent code with await expressions, including an asynchronous for loop (await for), looks more like synchronous code:

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

Listening for stream data

To get each value as it arrives, either use await for or subscribe to the stream using the listen() method:

In this example, the onClick property is a Stream object provided by the “submitInfo” button.

If you care about only one event, you can get it using a property such as first, last, or single. To test the event before handling it, use a method such as firstWhere(), lastWhere(), or singleWhere().

If you care about a subset of events, you can use methods such as skip(), skipWhile(), take(), takeWhile(), and where().

Transforming stream data

Often, you need to change the format of a stream’s data before you can use it. Use the transform() method to produce a stream with a different type of data:

This example uses two transformers. First it uses utf8.decoder to transform the stream of integers into a stream of strings. Then it uses a LineSplitter to transform the stream of strings into a stream of separate lines. These transformers are from the dart:convert library (see the dart:convert section).

Handling errors and completion

How you specify error and completion handling code depends on whether you use an asynchronous for loop (await for) or the Stream API.

If you use an asynchronous for loop, then use try-catch to handle errors. Code that executes after the stream is closed goes after the asynchronous for loop.

If you use the Stream API, then handle errors by registering an onError listener. Run code after the stream is closed by registering an onDone listener.

More information

For some examples of using Future and Stream in command-line apps, see the dart:io tour. Also see these articles, codelabs, and tutorials:

• Asynchronous programming: futures, async, await
• Futures and error handling
• Asynchronous programming: streams
• Creating streams in Dart
• Dart asynchronous programming: Isolates and event loops

dart:math – math and random

The dart:math library (API reference) provides common functionality such as sine and cosine, maximum and minimum, and constants such as piand e. Most of the functionality in the Math library is implemented as top-level functions.

To use this library in your app, import dart:math.

Trigonometry

The Math library provides basic trigonometric functions:

Maximum and minimum

The Math library provides max() and min() methods:

Math constants

Find your favorite constants—pi, e, and more—in the Math library:

Random numbers

Generate random numbers with the Random class. You can optionally provide a seed to the Random constructor.

You can even generate random booleans:

More information

Refer to the Math API reference for a full list of methods. Also see the API reference for num, int, and double.

dart:convert – decoding and encoding JSON, UTF-8, and more

The dart:convert library (API reference) has converters for JSON and UTF-8, as well as support for creating additional converters. JSON is a simple text format for representing structured objects and collections. UTF-8 is a common variable-width encoding that can represent every character in the Unicode character set.

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

Decoding and encoding JSON

Decode a JSON-encoded string into a Dart object with jsonDecode():

Encode a supported Dart object into a JSON-formatted string with jsonEncode():

Only objects of type int, double, String, bool, null, List, or Map (with string keys) are directly encodable into JSON. List and Map objects are encoded recursively.

You have two options for encoding objects that aren’t directly encodable. The first is to invoke encode() with a second argument: a function that returns an object that is directly encodable. Your second option is to omit the second argument, in which case the encoder calls the object’s toJson()method.

For more examples and links to JSON-related packages, see Using JSON.

Decoding and encoding UTF-8 characters

Use utf8.decode() to decode UTF8-encoded bytes to a Dart string:

To convert a stream of UTF-8 characters into a Dart string, specify utf8.decoder to the Stream transform() method:

Use utf8.encode() to encode a Dart string as a list of UTF8-encoded bytes:

Other functionality

The dart:convert library also has converters for ASCII and ISO-8859-1 (Latin1). For details, see the API reference for the dart:convert library.

dart:html – browser-based apps

Use the dart:html library to program the browser, manipulate objects and elements in the DOM, and access HTML5 APIs. DOM stands for Document Object Model, which describes the hierarchy of an HTML page.

Other common uses of dart:html are manipulating styles (CSS), getting data using HTTP requests, and exchanging data using WebSockets. HTML5 (and dart:html) has many additional APIs that this section doesn’t cover. Only web apps can use dart:html, not command-line apps.

To use the HTML library in your web app, import dart:html:

Manipulating the DOM

To use the DOM, you need to know about windows, documents, elements, and nodes.

A Window object represents the actual window of the web browser. Each Window has a Document object, which points to the document that’s currently loaded. The Window object also has accessors to various APIs such as IndexedDB (for storing data), requestAnimationFrame (for animations), and more. In tabbed browsers, each tab has its own Window object.

With the Document object, you can create and manipulate Element objects within the document. Note that the document itself is an element and can be manipulated.

The DOM models a tree of Nodes. These nodes are often elements, but they can also be attributes, text, comments, and other DOM types. Except for the root node, which has no parent, each node in the DOM has one parent and might have many children.

Finding elements

To manipulate an element, you first need an object that represents it. You can get this object using a query.

Find one or more elements using the top-level functions querySelector() and querySelectorAll(). You can query by ID, class, tag, name, or any combination of these. The CSS Selector Specification guide defines the formats of the selectors such as using a # prefix to specify IDs and a period (.) for classes.

The querySelector() function returns the first element that matches the selector, while querySelectorAll()returns a collection of elements that match the selector.

Manipulating elements

You can use properties to change the state of an element. Node and its subtype Element define the properties that all elements have. For example, all elements have classes, hidden, id, style, and title properties that you can use to set state. Subclasses of Element define additional properties, such as the href property of AnchorElement.

Consider this example of specifying an anchor element in HTML:

This <a> tag specifies an element with an href attribute and a text node (accessible via a text property) that contains the string “linktext”. To change the URL that the link goes to, you can use AnchorElement’s href property:

Often you need to set properties on multiple elements. For example, the following code sets the hidden property of all elements that have a class of “mac”, “win”, or “linux”. Setting the hidden property to true has the same effect as adding display:none to the CSS.

When the right property isn’t available or convenient, you can use Element’s attributes property. This property is a Map<String, String>, where the keys are attribute names. For a list of attribute names and their meanings, see the MDN Attributes page. Here’s an example of setting an attribute’s value:

Creating elements

You can add to existing HTML pages by creating new elements and attaching them to the DOM. Here’s an example of creating a paragraph (<p>) element:

You can also create an element by parsing HTML text. Any child elements are also parsed and created.

Note that elem2 is a ParagraphElement in the preceding example.

Attach the newly created element to the document by assigning a parent to the element. You can add an element to any existing element’s children. In the following example, body is an element, and its child elements are accessible (as a List<Element>) from the children property.

Adding, replacing, and removing nodes

Recall that elements are just a kind of node. You can find all the children of a node using the nodes property of Node, which returns a List<Node> (as opposed to children, which omits non-Element nodes). Once you have this list, you can use the usual List methods and operators to manipulate the children of the node.

To add a node as the last child of its parent, use the List add() method:

To replace a node, use the Node replaceWith() method:

To remove a node, use the Node remove() method:

Manipulating CSS styles

CSS, or cascading style sheets, defines the presentation styles of DOM elements. You can change the appearance of an element by attaching ID and class attributes to it.

Each element has a classes field, which is a list. Add and remove CSS classes simply by adding and removing strings from this collection. For example, the following sample adds the warning class to an element:

It’s often very efficient to find an element by ID. You can dynamically set an element ID with the id property:

You can reduce the redundant text in this example by using method cascades:

While using IDs and classes to associate an element with a set of styles is best practice, sometimes you want to attach a specific style directly to the element:

Handling events

To respond to external events such as clicks, changes of focus, and selections, add an event listener. You can add an event listener to any element on the page. Event dispatch and propagation is a complicated subject; research the details if you’re new to web programming.

Add an event handler using element.onEvent.listen(function), where Event is the event name and function is the event handler.

For example, here’s how you can handle clicks on a button:

Events can propagate up and down through the DOM tree. To discover which element originally fired the event, use e.target:

To see all the events for which you can register an event listener, look for “onEventType” properties in the API docs for Element and its subclasses. Some common events include:

• change
• blur
• keyDown
• keyUp
• mouseDown
• mouseUp

Using HTTP resources with HttpRequest

Formerly known as XMLHttpRequest, the HttpRequest class gives you access to HTTP resources from within your browser-based app. Traditionally, AJAX-style apps make heavy use of HttpRequest. Use HttpRequest to dynamically load JSON data or any other resource from a web server. You can also dynamically send data to a web server.

Getting data from the server

The HttpRequest static method getString() is an easy way to get data from a web server. Use await with the getString() call to ensure that you have the data before continuing execution.

Use try-catch to specify an error handler:

If you need access to the HttpRequest, not just the text data it retrieves, you can use the request() static method instead of getString(). Here’s an example of reading XML data:

You can also use the full API to handle more interesting cases. For example, you can set arbitrary headers.

The general flow for using the full API of HttpRequest is as follows:

1. Create the HttpRequest object.
2. Open the URL with either GET or POST.
3. Attach event handlers.
4. Send the request.

For example:

Sending data to the server

HttpRequest can send data to the server using the HTTP method POST. For example, you might want to dynamically submit data to a form handler. Sending JSON data to a RESTful web service is another common example.

Submitting data to a form handler requires you to provide name-value pairs as URI-encoded strings. (Information about the URI class is in the URIs section of the Dart Library Tour.) You must also set the Content-type header to application/x-www-form-urlencode if you wish to send data to a form handler.

Sending and receiving real-time data with WebSockets

A WebSocket allows your web app to exchange data with a server interactively—no polling necessary. A server creates the WebSocket and listens for requests on a URL that starts with ws://—for example, ws://127.0.0.1:1337/ws. The data transmitted over a WebSocket can be a string or a blob. Often, the data is a JSON-formatted string.

To use a WebSocket in your web app, first create a WebSocket object, passing the WebSocket URL as an argument:

Sending data

To send string data on the WebSocket, use the send() method:

Receiving data

To receive data on the WebSocket, register a listener for message events:

The message event handler receives a MessageEvent object. This object’s data field has the data from the server.

Handling WebSocket events

Your app can handle the following WebSocket events: open, close, error, and (as shown earlier) message. Here’s an example of a method that creates a WebSocket object and registers handlers for open, close, error, and message events:

More information

This section barely scratched the surface of using the dart:html library. For more information, see the documentation for dart:html. Dart has additional libraries for more specialized web APIs, such as web audio, IndexedDB, and WebGL.

For more information about Dart web libraries, see the web library overview.

dart:io – I/O for servers and command-line apps

The dart:io library provides APIs to deal with files, directories, processes, sockets, WebSockets, and HTTP clients and servers.

In general, the dart:io library implements and promotes an asynchronous API. Synchronous methods can easily block an application, making it difficult to scale. Therefore, most operations return results via Future or Stream objects, a pattern common with modern server platforms such as Node.js.

The few synchronous methods in the dart:io library are clearly marked with a Sync suffix on the method name. Synchronous methods aren’t covered here.

To use the dart:io library you must import it:

Files and directories

The I/O library enables command-line apps to read and write files and browse directories. You have two choices for reading the contents of a file: all at once, or streaming. Reading a file all at once requires enough memory to store all the contents of the file. If the file is very large or you want to process it while reading it, you should use a Stream, as described in Streaming file contents.

Reading a file as text

When reading a text file encoded using UTF-8, you can read the entire file contents with readAsString(). When the individual lines are important, you can use readAsLines(). In both cases, a Future object is returned that provides the contents of the file as one or more strings.

Reading a file as binary

The following code reads an entire file as bytes into a list of ints. The call to readAsBytes() returns a Future, which provides the result when it’s available.

Handling errors

To capture errors so they don’t result in uncaught exceptions, you can register a catchError handler on the Future, or (in an async function) use try-catch:

Streaming file contents

Use a Stream to read a file, a little at a time. You can use either the Stream API or await for, part of Dart’s asynchrony support.

Writing file contents

You can use an IOSink to write data to a file. Use the File openWrite() method to get an IOSink that you can write to. The default mode, FileMode.write, completely overwrites existing data in the file.

To add to the end of the file, use the optional mode parameter to specify FileMode.append:

To write binary data, use add(List<int> data).

Listing files in a directory

Finding all files and subdirectories for a directory is an asynchronous operation. The list() method returns a Stream that emits an object when a file or directory is encountered.

Other common functionality

The File and Directory classes contain other functionality, including but not limited to:

• Creating a file or directory: create() in File and Directory
• Deleting a file or directory: delete() in File and Directory
• Getting the length of a file: length() in File
• Getting random access to a file: open() in File

Refer to the API docs for File and Directory for a full list of methods.

HTTP clients and servers

The dart:io library provides classes that command-line apps can use for accessing HTTP resources, as well as running HTTP servers.

HTTP server

The HttpServer class provides the low-level functionality for building web servers. You can match request handlers, set headers, stream data, and more.

The following sample web server returns simple text information. This server listens on port 8888 and address 127.0.0.1 (localhost), responding to requests for the path /dart. For any other path, the response is status code 404 (page not found).

HTTP client

The HttpClient class helps you connect to HTTP resources from your Dart command-line or server-side application. You can set headers, use HTTP methods, and read and write data. The HttpClient class does not work in browser-based apps. When programming in the browser, use the dart:html HttpRequest class. Here’s an example of using HttpClient:

More information

This page showed how to use the major features of the dart:io library. Besides the APIs discussed in this section, the dart:io library also provides APIs for processes, sockets, and web sockets. For more information about server-side and command-line app development, see the server-side Dart overview.

For information on other dart:* libraries, see the library tour.

Summary

This page introduced you to the most commonly used functionality in Dart’s built-in libraries. It didn’t cover all the built-in libraries, however. Others that you might want to look into include dart:collection and dart:typed_data, as well as platform-specific libaries like the Dart web development libraries and the Flutter libraries.

You can get yet more libraries by using the pub package manager. The collection, crypto, http, intl, and test libraries are just a sampling of what you can install using pub.

To learn more about the Dart language, see the language tour.