card.dart 6.81 KB
Newer Older
1 2 3 4
// Copyright 2015 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/widgets.dart';
6

7
import 'card_theme.dart';
8
import 'material.dart';
Hans Muller's avatar
Hans Muller committed
9
import 'theme.dart';
10

11
/// A material design card. A card has slightly rounded corners and a shadow.
12 13 14
///
/// A card is a sheet of [Material] used to represent some related information,
/// for example an album, a geographical location, a meal, contact details, etc.
15
///
16 17 18 19 20 21
/// This is what it looks like when run:
///
/// ![A card with a slight shadow, consisting of two rows, one with an icon and
/// some text describing a musical, and the other with buttons for buying
/// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png)
///
22
/// {@tool snippet --template=stateless_widget_scaffold}
23
///
24 25
/// This sample shows creation of a [Card] widget that shows album information
/// and two actions.
26 27
///
/// ```dart
28 29 30 31 32 33 34 35 36 37
/// Widget build(BuildContext context) {
///   return Center(
///     child: Card(
///       child: Column(
///         mainAxisSize: MainAxisSize.min,
///         children: <Widget>[
///           const ListTile(
///             leading: Icon(Icons.album),
///             title: Text('The Enchanted Nightingale'),
///             subtitle: Text('Music by Julie Gable. Lyrics by Sidney Stein.'),
38
///           ),
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
///           ButtonTheme.bar( // make buttons use the appropriate styles for cards
///             child: ButtonBar(
///               children: <Widget>[
///                 FlatButton(
///                   child: const Text('BUY TICKETS'),
///                   onPressed: () { /* ... */ },
///                 ),
///                 FlatButton(
///                   child: const Text('LISTEN'),
///                   onPressed: () { /* ... */ },
///                 ),
///               ],
///             ),
///           ),
///         ],
///       ),
55
///     ),
56 57
///   );
/// }
58
/// ```
59
/// {@end-tool}
60
///
61 62 63
/// Sometimes the primary action area of a card is the card itself. Cards can be
/// one large touch target that shows a detail screen when tapped.
///
64
/// {@tool snippet --template=stateless_widget_scaffold}
65 66 67 68 69 70
///
/// This sample shows creation of a [Card] widget that can be tapped. When
/// tapped this [Card]'s [InkWell] displays an "ink splash" that fills the
/// entire card.
///
/// ```dart
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
/// Widget build(BuildContext context) {
///   return Center(
///     child: Card(
///       child: InkWell(
///         splashColor: Colors.blue.withAlpha(30),
///         onTap: () {
///           print('Card tapped.');
///         },
///         child: Container(
///           width: 300,
///           height: 100,
///           child: Text('A card that can be tapped'),
///         ),
///       ),
///     ),
///   );
/// }
88 89 90 91
/// ```
///
/// {@end-tool}
///
92 93
/// See also:
///
94
///  * [ListTile], to display icons and text in a card.
95
///  * [ButtonBar], to display buttons at the bottom of a card. Typically these
96
///    would be styled using a [ButtonTheme] created with [new ButtonTheme.bar].
97
///  * [showDialog], to display a modal card.
98
///  * <https://material.io/design/components/cards.html>
99
class Card extends StatelessWidget {
100
  /// Creates a material design card.
101
  ///
102 103
  /// The [elevation] must be null or non-negative. The [borderOnForeground]
  /// must not be null.
104 105
  const Card({
    Key key,
106
    this.color,
107
    this.elevation,
Hans Muller's avatar
Hans Muller committed
108
    this.shape,
109
    this.borderOnForeground = true,
110 111
    this.margin,
    this.clipBehavior,
112
    this.child,
113
    this.semanticContainer = true,
114
  }) : assert(elevation == null || elevation >= 0.0),
115
       assert(borderOnForeground != null),
116
       super(key: key);
117

Hans Muller's avatar
Hans Muller committed
118
  /// The card's background color.
119
  ///
Hans Muller's avatar
Hans Muller committed
120 121
  /// Defines the card's [Material.color].
  ///
122 123
  /// If this property is null then [ThemeData.cardTheme.color] is used,
  /// if that's null then [ThemeData.cardColor] is used.
124 125
  final Color color;

126 127
  /// The z-coordinate at which to place this card. This controls the size of
  /// the shadow below the card.
128
  ///
Hans Muller's avatar
Hans Muller committed
129 130
  /// Defines the card's [Material.elevation].
  ///
131 132
  /// If this property is null then [ThemeData.cardTheme.elevation] is used,
  /// if that's null, the default value is 1.0.
133
  final double elevation;
134

Hans Muller's avatar
Hans Muller committed
135 136 137 138
  /// The shape of the card's [Material].
  ///
  /// Defines the card's [Material.shape].
  ///
139 140 141
  /// If this property is null then [ThemeData.cardTheme.shape] is used.
  /// If that's null then the shape will be a [RoundedRectangleBorder] with a
  /// circular corner radius of 4.0.
Hans Muller's avatar
Hans Muller committed
142 143
  final ShapeBorder shape;

144 145 146 147 148 149
  /// Whether to paint the [shape] border in front of the [child].
  ///
  /// The default value is true.
  /// If false, the border will be painted behind the [child].
  final bool borderOnForeground;

150
  /// {@macro flutter.widgets.Clip}
151 152
  /// If this property is null then [ThemeData.cardTheme.clipBehavior] is used.
  /// If that's null then the behavior will be [Clip.none].
153 154
  final Clip clipBehavior;

155 156 157 158
  /// The empty space that surrounds the card.
  ///
  /// Defines the card's outer [Container.margin].
  ///
159 160
  /// If this property is null then [ThemeData.cardTheme.margin] is used,
  /// if that's null, the default margin is 4.0 logical pixels on all sides:
161 162 163
  /// `EdgeInsets.all(4.0)`.
  final EdgeInsetsGeometry margin;

164 165 166
  /// Whether this widget represents a single semantic container, or if false
  /// a collection of individual semantic nodes.
  ///
167
  /// Defaults to true.
168 169 170 171 172 173 174 175 176
  ///
  /// Setting this flag to true will attempt to merge all child semantics into
  /// this node. Setting this flag to false will force all child semantic nodes
  /// to be explicit.
  ///
  /// This flag should be false if the card contains multiple different types
  /// of content.
  final bool semanticContainer;

Hans Muller's avatar
Hans Muller committed
177 178 179 180 181
  /// The widget below this widget in the tree.
  ///
  /// {@macro flutter.widgets.child}
  final Widget child;

182 183 184
  static const double _defaultElevation = 1.0;
  static const Clip _defaultClipBehavior = Clip.none;

185
  @override
186
  Widget build(BuildContext context) {
187 188
    final CardTheme cardTheme = CardTheme.of(context);

189
    return Semantics(
190
      container: semanticContainer,
191
      child: Container(
192
        margin: margin ?? cardTheme.margin ?? const EdgeInsets.all(4.0),
193
        child: Material(
194
          type: MaterialType.card,
195 196 197
          color: color ?? cardTheme.color ?? Theme.of(context).cardColor,
          elevation: elevation ?? cardTheme.elevation ?? _defaultElevation,
          shape: shape ?? cardTheme.shape ?? const RoundedRectangleBorder(
198
            borderRadius: BorderRadius.all(Radius.circular(4.0)),
Hans Muller's avatar
Hans Muller committed
199
          ),
200
          borderOnForeground: borderOnForeground,
201
          clipBehavior: clipBehavior ?? cardTheme.clipBehavior ?? _defaultClipBehavior,
202 203 204 205
          child: Semantics(
            explicitChildNodes: !semanticContainer,
            child: child,
          ),
Hans Muller's avatar
Hans Muller committed
206
        ),
207
      ),
208 209 210
    );
  }
}