card.dart 7.09 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// 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 12
/// A material design card: a panel with slightly rounded corners and an
/// elevation shadow.
13 14 15
///
/// 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.
16
///
17 18 19 20 21 22
/// 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)
///
23
/// {@tool dartpad --template=stateless_widget_scaffold}
24
///
25 26
/// This sample shows creation of a [Card] widget that shows album information
/// and two actions.
27 28
///
/// ```dart
29 30 31 32 33 34 35 36 37 38
/// 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.'),
39
///           ),
40 41
///           Row(
///             mainAxisAlignment: MainAxisAlignment.end,
42
///             children: <Widget>[
43
///               TextButton(
44 45 46
///                 child: const Text('BUY TICKETS'),
///                 onPressed: () { /* ... */ },
///               ),
47 48
///               const SizedBox(width: 8),
///               TextButton(
49 50 51
///                 child: const Text('LISTEN'),
///                 onPressed: () { /* ... */ },
///               ),
52
///               const SizedBox(width: 8),
53
///             ],
54 55 56
///           ),
///         ],
///       ),
57
///     ),
58 59
///   );
/// }
60
/// ```
61
/// {@end-tool}
62
///
63 64 65
/// 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.
///
66
/// {@tool dartpad --template=stateless_widget_scaffold}
67 68 69 70 71 72
///
/// 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
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
/// 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'),
///         ),
///       ),
///     ),
///   );
/// }
90 91 92 93
/// ```
///
/// {@end-tool}
///
94 95
/// See also:
///
96
///  * [ListTile], to display icons and text in a card.
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
  const Card({
105
    Key? key,
106
    this.color,
107
    this.shadowColor,
108
    this.elevation,
Hans Muller's avatar
Hans Muller committed
109
    this.shape,
110
    this.borderOnForeground = true,
111 112
    this.margin,
    this.clipBehavior,
113
    this.child,
114
    this.semanticContainer = true,
115
  }) : assert(elevation == null || elevation >= 0.0),
116
       assert(borderOnForeground != null),
117
       super(key: key);
118

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

127 128 129
  /// The color to paint the shadow below the card.
  ///
  /// If null then the ambient [CardTheme]'s shadowColor is used.
130 131
  /// If that's null too, then the overall theme's [ThemeData.shadowColor]
  /// (default black) is used.
132
  final Color? shadowColor;
133

134 135
  /// The z-coordinate at which to place this card. This controls the size of
  /// the shadow below the card.
136
  ///
Hans Muller's avatar
Hans Muller committed
137 138
  /// Defines the card's [Material.elevation].
  ///
139 140
  /// If this property is null then [CardTheme.elevation] of
  /// [ThemeData.cardTheme] is used. If that's null, the default value is 1.0.
141
  final double? elevation;
142

Hans Muller's avatar
Hans Muller committed
143 144 145 146
  /// The shape of the card's [Material].
  ///
  /// Defines the card's [Material.shape].
  ///
147 148 149
  /// If this property is null then [CardTheme.shape] of [ThemeData.cardTheme]
  /// is used. If that's null then the shape will be a [RoundedRectangleBorder]
  /// with a circular corner radius of 4.0.
150
  final ShapeBorder? shape;
Hans Muller's avatar
Hans Muller committed
151

152 153 154 155 156 157
  /// 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;

158
  /// {@macro flutter.widgets.Clip}
159
  ///
160 161
  /// If this property is null then [CardTheme.clipBehavior] of
  /// [ThemeData.cardTheme] is used. If that's null then the behavior will be [Clip.none].
162
  final Clip? clipBehavior;
163

164 165 166 167
  /// The empty space that surrounds the card.
  ///
  /// Defines the card's outer [Container.margin].
  ///
168 169 170
  /// If this property is null then [CardTheme.margin] of
  /// [ThemeData.cardTheme] is used. If that's null, the default margin is 4.0
  /// logical pixels on all sides: `EdgeInsets.all(4.0)`.
171
  final EdgeInsetsGeometry? margin;
172

173 174 175
  /// Whether this widget represents a single semantic container, or if false
  /// a collection of individual semantic nodes.
  ///
176
  /// Defaults to true.
177 178 179 180 181 182 183 184 185
  ///
  /// 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
186 187 188
  /// The widget below this widget in the tree.
  ///
  /// {@macro flutter.widgets.child}
189
  final Widget? child;
Hans Muller's avatar
Hans Muller committed
190

191 192
  static const double _defaultElevation = 1.0;

193
  @override
194
  Widget build(BuildContext context) {
195
    final ThemeData theme = Theme.of(context)!;
196 197
    final CardTheme cardTheme = CardTheme.of(context);

198
    return Semantics(
199
      container: semanticContainer,
200
      child: Container(
201
        margin: margin ?? cardTheme.margin ?? const EdgeInsets.all(4.0),
202
        child: Material(
203
          type: MaterialType.card,
204 205
          shadowColor: shadowColor ?? cardTheme.shadowColor ?? theme.shadowColor,
          color: color ?? cardTheme.color ?? theme.cardColor,
206 207
          elevation: elevation ?? cardTheme.elevation ?? _defaultElevation,
          shape: shape ?? cardTheme.shape ?? const RoundedRectangleBorder(
208
            borderRadius: BorderRadius.all(Radius.circular(4.0)),
Hans Muller's avatar
Hans Muller committed
209
          ),
210
          borderOnForeground: borderOnForeground,
211
          clipBehavior: clipBehavior ?? cardTheme.clipBehavior ?? Clip.none,
212 213 214 215
          child: Semantics(
            explicitChildNodes: !semanticContainer,
            child: child,
          ),
Hans Muller's avatar
Hans Muller committed
216
        ),
217
      ),
218 219 220
    );
  }
}