mirror of
https://github.com/flutter/flutter.git
synced 2025-06-03 00:51:18 +00:00
95b0124785
Adds documentation for the stateless widget template, and adds an "imports" section to both templates.
66 lines
2.5 KiB
Markdown
66 lines
2.5 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.
|
|
|
|
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:
|
|
|
|
- [`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()` function, 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
|
|
function calls are not allowed in the preamble. 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.
|
|
|
|
- [`stateless_widget`](stateless_widget.tmpl) :
|
|
Identical to the `stateful_widget` template, except that the default code
|
|
block is inserted as the return value for a pre-existing `build` function in a
|
|
StatelessWidget, instead of being at the class level.
|