Creating Code Snippets
In general, creating application snippets can be accomplished with the following syntax inside of the dartdoc comment for a Flutter class/variable/enum/etc.:
/// {@tool snippet --template=stateful_widget}
/// Any text outside of the code blocks will be accumulated and placed at the
/// top of the snippet box as a description. Don't try and say "see the code
/// above" or "see the code below", since the location of the description may
/// change in the future. You can use dartdoc [Linking] in the description, and
/// __Markdown__ too.
///
/// ```dart preamble
/// class Foo extends StatelessWidget {
/// const Foo({this.value = ''});
///
/// String value;
///
/// @override
/// Widget build(BuildContext context) {
/// return Text(value);
/// }
/// }
/// ```
/// This will get tacked on to the end of the description above, and shown above
/// the snippet. These two code blocks will be separated by `///...` in the
/// short version of the snippet code sample.
/// ```dart
/// String myValue = 'Foo';
///
/// @override
/// Widget build(BuildContext) {
/// return const Foo(myValue);
/// }
/// ```
/// {@end-tool}
This will result in the template having the section that's inside "```dart" interpolated into the template's stateful widget's state object body.
For other sections of the template, the interpolation occurs by appending the string
that comes after code-
into the code block. For example, the
stateful_widget
template contains
{{code-imports}}
. To interpolate code into {{code-imports}}
, you would
have to do add the following:
/// ```dart imports
/// import 'package:flutter/rendering.dart';
/// ```
All code within a code block in a snippet needs to be able to be run through dartfmt without errors, so it needs to be valid code (This shouldn't be an additional burden, since all code will also be compiled to be sure it compiles).
Available Templates
The templates available for use as an argument to the snippets tool are as follows:
-
freeform
: This is a simple template for which you provide everything. It has no code of its own, just the sections forimports
,main
, andpreamble
. You must provide themain
section to have amain()
.
WidgetsApp Templates
These templates create a WidgetsApp
that encloses the snippet widget. These templates import
the widgets library.
-
stateful_widget
: The default code block will be placed as the body of theState
object of aStatefulWidget
subclass. Because the default code block is placed as the body of a stateful widget, you will need to implement thebuild()
method and any state variables. It also has apreamble
in addition to the default code block, which will be placed at the top level of the Dart file, so bare method calls are not allowed in the preamble. The default code block is placed as the body of a stateful widget, so you will need to implement thebuild()
method, and any state variables. It also has animports
section to import additional packages. Please only import things that are part of Flutter or part of default dependencies for aflutter create
project. -
stateful_widget_ticker
: Identical to thestateful_widget
template, with the addition of theTickerProviderStateMixin
class, enabling easy generation of animated samples. -
stateful_widget_restoration
: Similar to thestateful_widget
template, but the widget also importsRestorationMixin
and has arestorationId
field which it uses to implement therestorationId
getter on theState
. -
stateless_widget
: Identical to thestateful_widget
template, except that the default code block is inserted as a method (which should be thebuild
method) in aStatelessWidget
. The@override
before the build method is added by the template so must be omitted from the sample code.
MaterialApp Templates
These templates follow the same conventions as the WidgetsApp
templates above but use a
MaterialApp
instead. These templates import the material library.
-
stateful_widget_scaffold
: Adds aScaffold
widget as the home of the enclosingMaterialApp
to wrap the stateful widget snippet. TheScaffold
widget contains anAppBar
. -
stateful_widget_scaffold_center
: Similar tostateful_widget_scaffold
, except that it wraps the stateful widget with aCenter
. -
stateful_widget_scaffold_center_freeform_state
: Similar tostateful_widget_scaffold_center
except that the code block has to contain the entire state class defined as:class _MyStatefulWidgetState extends State<MyStatefulWidget>
-
stateless_widget_scaffold
: Similar tostateless_widget_material
, except that it wraps the stateless widget with aScaffold
. -
stateless_widget_scaffold_center
: Similar tostateless_widget_scaffold
, except that it wraps the stateless widget with aCenter
.
CupertinoApp Templates
These templates follow the same conventions as the WidgetsApp
templates above but use a
CupertinoApp
instead. These templates import the Cupertino library.
-
stateful_widget_cupertinoPageScaffold
: Similar tostateful_widget_cupertino
, except that it wraps the stateful widget with aCupertinoPageScaffold
. -
stateless_widget_cupertinoPageScaffold
: Similar tostateless_widget_cupertino
, except that it wraps the stateless widget with aCupertinoPageScaffold
.