card.dart 6.53 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
///           ButtonBar(
///             children: <Widget>[
///               FlatButton(
///                 child: const Text('BUY TICKETS'),
///                 onPressed: () { /* ... */ },
///               ),
///               FlatButton(
///                 child: const Text('LISTEN'),
///                 onPressed: () { /* ... */ },
///               ),
///             ],
50 51 52
///           ),
///         ],
///       ),
53
///     ),
54 55
///   );
/// }
56
/// ```
57
/// {@end-tool}
58
///
59 60 61
/// 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.
///
62
/// {@tool snippet --template=stateless_widget_scaffold}
63 64 65 66 67 68
///
/// 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
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
/// 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'),
///         ),
///       ),
///     ),
///   );
/// }
86 87 88 89
/// ```
///
/// {@end-tool}
///
90 91
/// See also:
///
92
///  * [ListTile], to display icons and text in a card.
93
///  * [ButtonBar], to display buttons at the bottom of a card.
94
///  * [showDialog], to display a modal card.
95
///  * <https://material.io/design/components/cards.html>
96
class Card extends StatelessWidget {
97
  /// Creates a material design card.
98
  ///
99 100
  /// The [elevation] must be null or non-negative. The [borderOnForeground]
  /// must not be null.
101 102
  const Card({
    Key key,
103
    this.color,
104
    this.elevation,
Hans Muller's avatar
Hans Muller committed
105
    this.shape,
106
    this.borderOnForeground = true,
107 108
    this.margin,
    this.clipBehavior,
109
    this.child,
110
    this.semanticContainer = true,
111
  }) : assert(elevation == null || elevation >= 0.0),
112
       assert(borderOnForeground != null),
113
       super(key: key);
114

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

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

Hans Muller's avatar
Hans Muller committed
132 133 134 135
  /// The shape of the card's [Material].
  ///
  /// Defines the card's [Material.shape].
  ///
136 137 138
  /// 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
139 140
  final ShapeBorder shape;

141 142 143 144 145 146
  /// 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;

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

153 154 155 156
  /// The empty space that surrounds the card.
  ///
  /// Defines the card's outer [Container.margin].
  ///
157 158
  /// 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:
159 160 161
  /// `EdgeInsets.all(4.0)`.
  final EdgeInsetsGeometry margin;

162 163 164
  /// Whether this widget represents a single semantic container, or if false
  /// a collection of individual semantic nodes.
  ///
165
  /// Defaults to true.
166 167 168 169 170 171 172 173 174
  ///
  /// 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
175 176 177 178 179
  /// The widget below this widget in the tree.
  ///
  /// {@macro flutter.widgets.child}
  final Widget child;

180 181
  static const double _defaultElevation = 1.0;

182
  @override
183
  Widget build(BuildContext context) {
184 185
    final CardTheme cardTheme = CardTheme.of(context);

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