mirror of
https://github.com/flutter/flutter.git
synced 2025-06-03 00:51:18 +00:00
117 lines
4.8 KiB
Markdown
117 lines
4.8 KiB
Markdown
## 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.:
|
|
|
|
```dart
|
|
/// {@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`](stateful_widget.tmpl) template contains
|
|
`{{code-imports}}`. To interpolate code into `{{code-imports}}`, you would
|
|
have to do add the following:
|
|
|
|
```dart
|
|
/// ```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 using as an argument to the snippets tool are as
|
|
follows:
|
|
|
|
- [`freeform`](freeform.tmpl) :
|
|
This is a simple template for which you provide everything. It has no code of
|
|
its own, just the sections for `imports`, `main`, and `preamble`. You must
|
|
provide the `main` section in order to have a `main()`.
|
|
|
|
- [`stateful_widget`](stateful_widget.tmpl) :
|
|
The default code block will be placed as the body of the `State` object of a
|
|
`StatefulWidget` subclass. Because the default code block is placed as the body
|
|
of a stateful widget, you will need to implement the `build()` method, and any
|
|
state variables. It also has a `preamble` 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 the
|
|
`build()` method, and any state variables. It also has an `imports`
|
|
section to import additional packages. Please only import things that are part
|
|
of flutter or part of default dependencies for a `flutter create` project.
|
|
It creates a `WidgetsApp` around the child stateful widget.
|
|
|
|
- [`stateless_widget`](stateless_widget.tmpl) : Identical to the
|
|
`stateful_widget` template, except that the default code block is
|
|
inserted as a method (which should be the `build` method) in a
|
|
`StatelessWidget`. The `@override` before the build method is added by
|
|
the template, so must be omitted from the sample code.
|
|
|
|
- [`stateful_widget_material`](stateful_widget_material.tmpl) : Similar to
|
|
`stateful_widget`, except that it imports the material library, and uses
|
|
a `MaterialApp` instead of `WidgetsApp`.
|
|
|
|
- [`stateless_widget_material`](stateless_widget_material.tmpl) : Similar to
|
|
`stateless_widget`, except that it imports the material library, and uses
|
|
a `MaterialApp` instead of `WidgetsApp`.
|
|
|
|
- [`stateful_widget_scaffold`](stateful_widget_scaffold.tmpl) : Similar to
|
|
`stateful_widget_material`, except that it wraps the stateful widget with a
|
|
`Scaffold`.
|
|
|
|
- [`stateful_widget_scaffold_center`](stateful_widget_scaffold_center.tmpl) : Similar to
|
|
`stateful_widget_scaffold`, except that it wraps the stateful widget with a
|
|
`Scaffold` _and_ a `Center`.
|
|
|
|
- [`stateful_widget_scaffold_center_freeform_state`](stateful_widget_scaffold_center_freeform_state.tmpl) :
|
|
Similar to `stateful_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`](stateless_widget_scaffold.tmpl) : Similar to
|
|
`stateless_widget_material`, except that it wraps the stateless widget with a
|
|
`Scaffold`.
|
|
|
|
- [`stateless_widget_scaffold_center`](stateless_widget_scaffold_center.tmpl) : Similar to
|
|
`stateless_widget_scaffold`, except that it wraps the stateless widget with a
|
|
`Scaffold` _and_ a `Center`.
|
|
|