card.dart 8.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
/// A Material Design card: a panel with slightly rounded corners and an
12
/// 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}
24 25
/// This sample shows creation of a [Card] widget that shows album information
/// and two actions.
26
///
27
/// ** See code in examples/api/lib/material/card/card.0.dart **
28
/// {@end-tool}
29
///
30 31 32
/// 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.
///
33
/// {@tool dartpad}
34 35 36 37
/// 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.
///
38
/// ** See code in examples/api/lib/material/card/card.1.dart **
39 40
/// {@end-tool}
///
41 42 43 44 45 46 47 48 49 50
/// Material Design 3 introduced new types of cards. These can
/// be produced by configuring the [Card] widget's properties.
/// [Card] widget.
/// {@tool dartpad}
/// This sample shows creation of [Card] widgets for elevated, filled and
/// outlined types, as described in: https://m3.material.io/components/cards/overview
///
/// ** See code in examples/api/lib/material/card/card.2.dart **
/// {@end-tool}
///
51 52
/// See also:
///
53
///  * [ListTile], to display icons and text in a card.
54
///  * [showDialog], to display a modal card.
55
///  * <https://material.io/design/components/cards.html>
56
///  * <https://m3.material.io/components/cards>
57
class Card extends StatelessWidget {
58
  /// Creates a Material Design card.
59
  ///
60 61
  /// The [elevation] must be null or non-negative. The [borderOnForeground]
  /// must not be null.
62
  const Card({
63
    super.key,
64
    this.color,
65
    this.shadowColor,
66
    this.surfaceTintColor,
67
    this.elevation,
Hans Muller's avatar
Hans Muller committed
68
    this.shape,
69
    this.borderOnForeground = true,
70 71
    this.margin,
    this.clipBehavior,
72
    this.child,
73
    this.semanticContainer = true,
74
  }) : assert(elevation == null || elevation >= 0.0),
75
       assert(borderOnForeground != null);
76

Hans Muller's avatar
Hans Muller committed
77
  /// The card's background color.
78
  ///
Hans Muller's avatar
Hans Muller committed
79 80
  /// Defines the card's [Material.color].
  ///
81 82
  /// If this property is null then [CardTheme.color] of [ThemeData.cardTheme]
  /// is used. If that's null then [ThemeData.cardColor] is used.
83
  final Color? color;
84

85 86 87
  /// The color to paint the shadow below the card.
  ///
  /// If null then the ambient [CardTheme]'s shadowColor is used.
88 89
  /// If that's null too, then the overall theme's [ThemeData.shadowColor]
  /// (default black) is used.
90
  final Color? shadowColor;
91

92 93
  /// The color used as an overlay on [color] to indicate elevation.
  ///
94 95
  /// If this is null, no overlay will be applied. Otherwise this color
  /// will be composited on top of [color] with an opacity related
96 97 98 99 100 101 102 103
  /// to [elevation] and used to paint the background of the card.
  ///
  /// The default is null.
  ///
  /// See [Material.surfaceTintColor] for more details on how this
  /// overlay is applied.
  final Color? surfaceTintColor;

104 105
  /// The z-coordinate at which to place this card. This controls the size of
  /// the shadow below the card.
106
  ///
Hans Muller's avatar
Hans Muller committed
107 108
  /// Defines the card's [Material.elevation].
  ///
109 110
  /// If this property is null then [CardTheme.elevation] of
  /// [ThemeData.cardTheme] is used. If that's null, the default value is 1.0.
111
  final double? elevation;
112

Hans Muller's avatar
Hans Muller committed
113 114 115 116
  /// The shape of the card's [Material].
  ///
  /// Defines the card's [Material.shape].
  ///
117 118 119
  /// 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.
120
  final ShapeBorder? shape;
Hans Muller's avatar
Hans Muller committed
121

122 123 124 125 126 127
  /// 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;

128
  /// {@macro flutter.material.Material.clipBehavior}
129
  ///
130 131
  /// If this property is null then [CardTheme.clipBehavior] of
  /// [ThemeData.cardTheme] is used. If that's null then the behavior will be [Clip.none].
132
  final Clip? clipBehavior;
133

134 135 136 137
  /// The empty space that surrounds the card.
  ///
  /// Defines the card's outer [Container.margin].
  ///
138 139 140
  /// 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)`.
141
  final EdgeInsetsGeometry? margin;
142

143 144 145
  /// Whether this widget represents a single semantic container, or if false
  /// a collection of individual semantic nodes.
  ///
146
  /// Defaults to true.
147 148 149 150 151 152 153 154 155
  ///
  /// 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
156 157
  /// The widget below this widget in the tree.
  ///
158
  /// {@macro flutter.widgets.ProxyWidget.child}
159
  final Widget? child;
Hans Muller's avatar
Hans Muller committed
160

161
  @override
162
  Widget build(BuildContext context) {
163
    final CardTheme cardTheme = CardTheme.of(context);
164
    final CardTheme defaults = Theme.of(context).useMaterial3 ? _TokenDefaultsM3(context) : _DefaultsM2(context);
165

166
    return Semantics(
167
      container: semanticContainer,
168
      child: Container(
169
        margin: margin ?? cardTheme.margin ?? defaults.margin!,
170
        child: Material(
171
          type: MaterialType.card,
172 173 174 175 176
          color: color ?? cardTheme.color ?? defaults.color,
          shadowColor: shadowColor ?? cardTheme.shadowColor ?? defaults.shadowColor,
          surfaceTintColor: surfaceTintColor ?? cardTheme.surfaceTintColor ?? defaults.surfaceTintColor,
          elevation: elevation ?? cardTheme.elevation ?? defaults.elevation!,
          shape: shape ?? cardTheme.shape ?? defaults.shape,
177
          borderOnForeground: borderOnForeground,
178
          clipBehavior: clipBehavior ?? cardTheme.clipBehavior ?? defaults.clipBehavior!,
179 180 181 182
          child: Semantics(
            explicitChildNodes: !semanticContainer,
            child: child,
          ),
Hans Muller's avatar
Hans Muller committed
183
        ),
184
      ),
185 186 187
    );
  }
}
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214

class _DefaultsM2 extends CardTheme {
  const _DefaultsM2(this.context)
    : super(
        clipBehavior: Clip.none,
        elevation: 1.0,
        margin: const EdgeInsets.all(4.0),
        shape: const RoundedRectangleBorder(
          borderRadius: BorderRadius.all(Radius.circular(4.0)),
        )
    );

  final BuildContext context;

  @override
  Color? get color => Theme.of(context).cardColor;

  @override
  Color? get shadowColor => Theme.of(context).shadowColor;
}

// BEGIN GENERATED TOKEN PROPERTIES

// Generated code to the end of this file. Do not edit by hand.
// These defaults are generated from the Material Design Token
// database by the script dev/tools/gen_defaults/bin/gen_defaults.dart.

215
// Generated version v0_101
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
class _TokenDefaultsM3 extends CardTheme {
  const _TokenDefaultsM3(this.context)
    : super(
        clipBehavior: Clip.none,
        elevation: 1.0,
        margin: const EdgeInsets.all(4.0),
        shape: const RoundedRectangleBorder(borderRadius: BorderRadius.only(topLeft: Radius.circular(12.0), topRight: Radius.circular(12.0), bottomLeft: Radius.circular(12.0), bottomRight: Radius.circular(12.0))),
      );

  final BuildContext context;

  @override
  Color? get color => Theme.of(context).colorScheme.surface;

  @override
  Color? get shadowColor => Theme.of(context).colorScheme.shadow;

  @override
  Color? get surfaceTintColor => Theme.of(context).colorScheme.surfaceTint;
}

// END GENERATED TOKEN PROPERTIES