form.dart 9.19 KB
Newer Older
1 2 3 4
// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:flutter/foundation.dart';
6

7
import 'framework.dart';
8
import 'routes.dart';
9

10 11 12 13 14 15 16 17 18
/// An optional container for grouping together multiple form field widgets
/// (e.g. [Input] widgets).
///
/// Each individual form field should be wrapped in a [FormField] widget, with
/// the [Form] widget as a common ancestor of all of those. Call methods on
/// [FormState] to save, reset, or validate each [FormField] that is a
/// descendant of this [Form]. To obtain the [FormState], you may use [Form.of]
/// with a context whose ancestor is the [Form], or pass a [GlobalKey] to the
/// [Form] constructor and call [GlobalKey.currentState].
19
class Form extends StatefulWidget {
20 21 22
  /// Creates a container for form fields.
  ///
  /// The [child] argument must not be null.
23 24
  Form({
    Key key,
25
    @required this.child,
26
    this.autovalidate: false,
27
    this.onWillPop,
28 29 30 31
  }) : super(key: key) {
    assert(child != null);
  }

Matt Perry's avatar
Matt Perry committed
32 33 34 35 36 37 38 39 40 41 42 43
  /// Returns the closest [FormState] which encloses the given context.
  ///
  /// Typical usage is as follows:
  ///
  /// ```dart
  /// FormState form = Form.of(context);
  /// form.save();
  /// ```
  static FormState of(BuildContext context) {
    _FormScope scope = context.inheritFromWidgetOfExactType(_FormScope);
    return scope?._formState;
  }
44 45 46 47

  /// Root of the widget hierarchy that contains this form.
  final Widget child;

48 49 50 51 52
  /// If true, form fields will validate and update their error text
  /// immediately after every change. Otherwise, you must call
  /// [FormState.validate] to validate.
  final bool autovalidate;

53 54 55 56 57 58 59
  /// Enables the form to veto attempts by the user to dismiss the [ModalRoute]
  /// that contains the form.
  ///
  /// If the callback returns a Future that resolves to false, the form's route
  /// will not be popped.
  WillPopCallback onWillPop;

60
  @override
Matt Perry's avatar
Matt Perry committed
61
  FormState createState() => new FormState();
62 63
}

Matt Perry's avatar
Matt Perry committed
64 65 66
class FormState extends State<Form> {
  int _generation = 0;
  Set<FormFieldState<dynamic>> _fields = new Set<FormFieldState<dynamic>>();
67

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
  @override
  void dependenciesChanged() {
    super.dependenciesChanged();
    final ModalRoute<dynamic> route = ModalRoute.of(context);
    if (route != null && config.onWillPop != null) {
      // Avoid adding our callback twice by removing it first.
      route.removeScopedWillPopCallback(config.onWillPop);
      route.addScopedWillPopCallback(config.onWillPop);
    }
  }

  @override
  void didUpdateConfig(Form oldConfig) {
    final ModalRoute<dynamic> route = ModalRoute.of(context);
    if (config.onWillPop != oldConfig.onWillPop && route != null) {
      if (oldConfig.onWillPop != null)
        route.removeScopedWillPopCallback(oldConfig.onWillPop);
      if (config.onWillPop != null)
        route.addScopedWillPopCallback(config.onWillPop);
    }
  }

  // Called when a form field has changed. This will cause all form fields
  // to rebuild, useful if form fields have interdependencies.
Matt Perry's avatar
Matt Perry committed
92
  void _fieldDidChange() {
93
    setState(() {
Matt Perry's avatar
Matt Perry committed
94
      ++_generation;
95 96 97
    });
  }

Matt Perry's avatar
Matt Perry committed
98 99 100 101 102 103 104 105
  void _register(FormFieldState<dynamic> field) {
    _fields.add(field);
  }

  void _unregister(FormFieldState<dynamic> field) {
    _fields.remove(field);
  }

106 107
  @override
  Widget build(BuildContext context) {
108 109
    if (config.autovalidate)
      _validate();
Matt Perry's avatar
Matt Perry committed
110
    return new _FormScope(
111
      formState: this,
Matt Perry's avatar
Matt Perry committed
112
      generation: _generation,
113 114 115 116
      child: config.child
    );
  }

117
  /// Saves every [FormField] that is a descendant of this [Form].
Matt Perry's avatar
Matt Perry committed
118 119 120 121
  void save() {
    for (FormFieldState<dynamic> field in _fields)
      field.save();
  }
122

123
  /// Resets every [FormField] that is a descendant of this [Form] back to its
Matt Perry's avatar
Matt Perry committed
124 125 126 127 128 129
  /// initialState.
  void reset() {
    for (FormFieldState<dynamic> field in _fields)
      field.reset();
    _fieldDidChange();
  }
130

131 132 133 134 135 136 137 138 139 140 141 142
  /// Validates every [FormField] that is a descendant of this [Form], and
  /// returns true iff there are no errors.
  bool validate() {
    _fieldDidChange();
    return _validate();
  }

  bool _validate() {
    bool hasError = false;
    for (FormFieldState<dynamic> field in _fields)
      hasError = !field.validate() || hasError;
    return !hasError;
Matt Perry's avatar
Matt Perry committed
143
  }
144 145
}

Matt Perry's avatar
Matt Perry committed
146 147
class _FormScope extends InheritedWidget {
  _FormScope({
148 149
    Key key,
    Widget child,
Matt Perry's avatar
Matt Perry committed
150
    FormState formState,
151
    int generation
152
  }) : _formState = formState,
153 154 155
       _generation = generation,
       super(key: key, child: child);

Matt Perry's avatar
Matt Perry committed
156
  final FormState _formState;
157 158 159 160 161

  /// Incremented every time a form field has changed. This lets us know when
  /// to rebuild the form.
  final int _generation;

162 163
  /// The [Form] associated with this widget.
  Form get form => _formState.config;
164

Matt Perry's avatar
Matt Perry committed
165 166 167 168 169
  @override
  bool updateShouldNotify(_FormScope old) => _generation != old._generation;
}

/// Signature for validating a form field.
170 171
///
/// Used by [FormField.validator].
Matt Perry's avatar
Matt Perry committed
172 173 174
typedef String FormFieldValidator<T>(T value);

/// Signature for being notified when a form field changes value.
175 176
///
/// Used by [FormField.onSaved].
Matt Perry's avatar
Matt Perry committed
177 178 179
typedef void FormFieldSetter<T>(T newValue);

/// Signature for building the widget representing the form field.
180 181
///
/// Used by [FormField.builder].
Matt Perry's avatar
Matt Perry committed
182 183 184 185 186 187 188 189 190 191 192 193 194
typedef Widget FormFieldBuilder<T>(FormFieldState<T> field);

/// A single form field. This widget maintains the current state of the form
/// field, so that updates and validation errors are visually reflected in the
/// UI.
///
/// When used inside a [Form], you can use methods on [FormState] to query or
/// manipulate the form data as a whole. For example, calling [FormState.save]
/// will invoke each [FormField]'s [onSaved] callback in turn.
///
/// Use a [GlobalKey] with [FormField] if you want to retrieve its current
/// state, for example if you want one form field to depend on another.
///
195 196 197 198 199
/// A [Form] ancestor is not required. The [Form] simply makes it easier to
/// save, reset, or validate multiple fields at once. To use without a [Form],
/// pass a [GlobalKey] to the constructor and use [GlobalKey.currentState] to
/// save or reset the form field.
///
200 201 202 203
/// See also:
///
///  * [Form], which is the widget that aggregates the form fields.
///  * [TextField], which is a commonly used form field for entering text.
Matt Perry's avatar
Matt Perry committed
204 205 206 207 208 209 210
class FormField<T> extends StatefulWidget {
  FormField({
    Key key,
    @required this.builder,
    this.onSaved,
    this.validator,
    this.initialValue,
211
    this.autovalidate: false,
Matt Perry's avatar
Matt Perry committed
212 213
  }) : super(key: key) {
    assert(builder != null);
214 215
  }

Matt Perry's avatar
Matt Perry committed
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
  /// An optional method to call with the final value when the form is saved via
  /// Form.save().
  final FormFieldSetter<T> onSaved;

  /// An optional method that validates an input. Returns an error string to
  /// display if the input is invalid, or null otherwise.
  final FormFieldValidator<T> validator;

  /// Function that returns the widget representing this form field. It is
  /// passed the form field state as input, containing the current value and
  /// validation state of this field.
  final FormFieldBuilder<T> builder;

  /// An optional value to initialize the form field to, or null otherwise.
  final T initialValue;
231

232 233 234 235 236 237
  /// If true, this form fields will validate and update its error text
  /// immediately after every change. Otherwise, you must call
  /// [FormFieldState.validate] to validate. If part of a [Form] that
  /// autovalidates, this value will be ignored.
  final bool autovalidate;

238
  @override
Matt Perry's avatar
Matt Perry committed
239 240 241
  FormFieldState<T> createState() => new FormFieldState<T>();
}

242 243
/// The current state of a [FormField]. Passed to the [FormFieldBuilder] method
/// for use in constructing the form field's widget.
Matt Perry's avatar
Matt Perry committed
244 245 246 247 248 249 250
class FormFieldState<T> extends State<FormField<T>> {
  T _value;
  String _errorText;

  /// The current value of the form field.
  T get value => _value;

251 252 253
  /// The current validation error returned by the [FormField.validator]
  /// callback, or null if no errors have been triggered. This only updates when
  /// [validate] is called.
Matt Perry's avatar
Matt Perry committed
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
  String get errorText => _errorText;

  /// True if this field has any validation errors.
  bool get hasError => _errorText != null;

  /// Calls the [FormField]'s onSaved method with the current value.
  void save() {
    if (config.onSaved != null)
      config.onSaved(value);
  }

  /// Resets the field to its initial value.
  void reset() {
    setState(() {
      _value = config.initialValue;
      _errorText = null;
    });
  }

273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
  /// Calls [FormField.validator] to set the [errorText]. Returns true if there
  /// were no errors.
  bool validate() {
    setState(() {
      _validate();
    });
    return !hasError;
  }

  bool _validate() {
    if (config.validator != null)
      _errorText = config.validator(_value);
    return !hasError;
  }

Matt Perry's avatar
Matt Perry committed
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
  /// Updates this field's state to the new value. Useful for responding to
  /// child widget changes, e.g. [Slider]'s onChanged argument.
  void onChanged(T value) {
    setState(() {
      _value = value;
    });
    Form.of(context)?._fieldDidChange();
  }

  @override
  void initState() {
    super.initState();
    _value = config.initialValue;
  }

  @override
  void deactivate() {
    Form.of(context)?._unregister(this);
    super.deactivate();
  }

  @override
  Widget build(BuildContext context) {
311 312
    if (config.autovalidate)
      _validate();
Matt Perry's avatar
Matt Perry committed
313 314 315
    Form.of(context)?._register(this);
    return config.builder(this);
  }
316
}