mirror of
https://github.com/flutter/flutter.git
synced 2025-06-03 00:51:18 +00:00
262f12b4a9
This converts all remaining "## Sample code" segments into snippets, and fixes the snippet generator to handle multiple snippets in the same dartdoc block properly. I also generated, compiled, and ran each of the existing application samples, and fixed them up to be more useful and/or just run without errors. This PR fixes these problems with examples: 1. Switching tabs in a snippet now works if there is more than one snippet in a single dartdoc block. 2. Generation of snippet code now works if there is more than one snippet. 3. Contrast of text and links in the code sample block has been improved to recommended levels. 4. Added five new snippet templates, including a "freeform" template to make it possible to show examples that need to change the app instantiation. 5. Fixed several examples to run properly, a couple by adding the "Scaffold" widget to the template, a couple by just fixing their code. 6. Fixed visual look of some of the samples when they run by placing many samples inside of a Scaffold. 7. In order to make it easier to run locally, changed the sample analyzer to remove the contents of the supplied temp directory before running, since having files that hang around is problematic (only a problem when running locally with the `--temp` argument). 8. Added a `SampleCheckerException` class, and handle sample checking exceptions more gracefully. 9. Deprecated the old "## Sample code" designation, and added enforcement for the deprecation. 10. Removed unnecessary `new` from templates (although they never appeared in the samples thanks to dartfmt, but still). Fixes #26398 Fixes #27411
89 lines
3.6 KiB
Markdown
89 lines
3.6 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:
|
|
|
|
- [`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()` 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.
|
|
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 the `build` function in a
|
|
StatelessWidget. There is no need to include the @override before the build
|
|
funciton (the template adds this for you).
|
|
|
|
- [`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.
|
|
|
|
- [`stateless_widget_scaffold`](stateless_widget_scaffold.tmpl) : Similar to
|
|
`stateless_widget_material`, except that it wraps the stateless widget with a
|
|
Scaffold.
|