DecoratedBox

DecoratedBox 为子组件绘制装饰（背景、边框、圆角、阴影、渐变等）。

构造函数

DecoratedBox({
  Key? key,                                               // 组件标识
  required Decoration decoration,                          // 装饰（必填）
  DecorationPosition position = DecorationPosition.background, // 装饰位置：background=子组件后面，foreground=子组件前面
  required Widget child,                                   // 子组件（必填）
})

属性速查

属性	类型	默认值	说明
decoration	Decoration	必填	装饰
position	DecorationPosition	background	装饰绘制位置
child	Widget	必填	子组件

position 值说明

值	效果
DecorationPosition.background	装饰绘制在子组件后面（默认）
DecorationPosition.foreground	装饰绘制在子组件前面（蒙版效果）

BoxDecoration 详解

BoxDecoration 是最常用的 Decoration 子类。

构造函数

BoxDecoration({
  Color? color,                                            // 背景色
  DecorationImage? image,                                  // 背景图
  BoxBorder? border,                                      // 边框
  BorderRadius? borderRadius,                              // 圆角
  List<BoxShadow>? boxShadow,                             // 阴影
  Gradient? gradient,                                     // 渐变
  BlendMode? backgroundBlendMode,                         // 混合模式
  BoxShape shape = BoxShape.rectangle,                    // 形状（rectangle/circle）
})

属性速查

属性	类型	默认值	说明
color	Color?	null	背景色
image	DecorationImage?	null	背景图
border	BoxBorder?	null	边框
borderRadius	BorderRadius?	null	圆角
boxShadow	List<BoxShadow>?	null	阴影
gradient	Gradient?	null	渐变
backgroundBlendMode	BlendMode?	null	混合模式
shape	BoxShape	rectangle	形状

shape 值说明

值	效果
BoxShape.rectangle	矩形（默认）
BoxShape.circle	圆形

BoxShadow 属性速查

BoxShadow({
  Color color = const Color(0xFF000000),                   // 阴影颜色
  Offset offset = Offset.zero,                             // 偏移（x 右移，y 下移）
  double blurRadius = 0.0,                                 // 模糊半径（越大越模糊）
  double spreadRadius = 0.0,                               // 扩散半径（正值扩大，负值缩小）
})

属性	类型	默认值	说明
color	Color	黑色	阴影颜色
offset	Offset	zero	偏移量
blurRadius	double	0	模糊半径
spreadRadius	double	0	扩散半径

渐变类型速查

类型	说明	常用属性
LinearGradient	线性渐变	colors、begin、end、stops
RadialGradient	径向渐变	colors、center、radius
SweepGradient	扫描渐变	colors、center、startAngle、endAngle

快速示例

背景色

import 'package:flutter/material.dart';

class DecoratedBoxColorExample extends StatelessWidget {
  const DecoratedBoxColorExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('DecoratedBox 背景色')),
      body: Center(
        // ─── ★ DecoratedBox ──────────────
        child: DecoratedBox(
          decoration: BoxDecoration(color: Colors.blue),
          child: const Padding(
            padding: EdgeInsets.all(16),
            child: Text('蓝色背景'),
          ),
        ),
        // ─── ☆ DecoratedBox ──────────────
      ),
    );
  }
}

圆角

import 'package:flutter/material.dart';

class DecoratedBoxRadiusExample extends StatelessWidget {
  const DecoratedBoxRadiusExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('DecoratedBox 圆角')),
      body: Center(
        // ─── ★ borderRadius 圆角 ──────────────
        child: DecoratedBox(
          decoration: BoxDecoration(
            color: Colors.blue,
            borderRadius: BorderRadius.circular(12),
          ),
        // ─── ☆ borderRadius 圆角 ──────────────
          child: const Padding(
            padding: EdgeInsets.all(16),
            child: Text('圆角'),
          ),
        ),
      ),
    );
  }
}

### 边框

```dart
DecoratedBox(
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(8),
    border: Border.all(
      color: Colors.grey,
      width: 1,
      style: BorderStyle.solid,
    ),
    // border: Border(top: BorderSide(color: Colors.red, width: 2)),  // 仅顶部边框
  ),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('带边框'),
  ),
)

阴影

DecoratedBox(
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(12),
    boxShadow: [
      BoxShadow(
        color: Colors.black.withOpacity(0.1),  // 阴影颜色
        blurRadius: 10,                         // 模糊半径
        spreadRadius: 2,                        // 扩散半径
        offset: const Offset(0, 4),             // 偏移
      ),
    ],
  ),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('带阴影的卡片'),
  ),
)

渐变

// 线性渐变
DecoratedBox(
  decoration: BoxDecoration(
    gradient: LinearGradient(
      colors: [Colors.blue, Colors.purple],
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
      // stops: [0.3, 0.7],  // 颜色位置（0~1）
    ),
    borderRadius: BorderRadius.circular(12),
  ),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('线性渐变', style: TextStyle(color: Colors.white)),
  ),
)

// 径向渐变
DecoratedBox(
  decoration: BoxDecoration(
    gradient: RadialGradient(
      colors: [Colors.yellow, Colors.red],
      radius: 0.5,
    ),
    shape: BoxShape.circle,
  ),
  child: const SizedBox(width: 100, height: 100),
)

// 扫描渐变
DecoratedBox(
  decoration: BoxDecoration(
    gradient: SweepGradient(
      colors: [Colors.red, Colors.yellow, Colors.green, Colors.blue, Colors.red],
    ),
    shape: BoxShape.circle,
  ),
  child: const SizedBox(width: 100, height: 100),
)

背景图

DecoratedBox(
  decoration: const BoxDecoration(
    image: DecorationImage(
      image: NetworkImage('https://example.com/bg.jpg'),
      fit: BoxFit.cover,
    ),
  ),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('背景图'),
  ),
)

组合使用

Container(
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(16),
    border: Border.all(color: Colors.grey.withOpacity(0.2)),
    boxShadow: [
      BoxShadow(
        color: Colors.black.withOpacity(0.08),
        blurRadius: 12,
        offset: const Offset(0, 4),
      ),
    ],
  ),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('组合装饰'),
  ),
)

position 参数

// background（默认）—— 装饰绘制在子组件后面
DecoratedBox(
  decoration: BoxDecoration(color: Colors.blue),
  position: DecorationPosition.background,
  child: const Text('文字'),
)

// foreground —— 装饰绘制在子组件前面
DecoratedBox(
  decoration: BoxDecoration(color: Colors.black.withOpacity(0.5)),
  position: DecorationPosition.foreground,
  child: const Text('蒙版效果', style: TextStyle(color: Colors.white)),
)

Container vs DecoratedBox

特性	DecoratedBox	Container
装饰	✅	✅（内部就是 DecoratedBox）
内边距	❌ 需外层 Padding	✅ padding 属性
对齐	❌ 需外层 Align	✅ alignment 属性
尺寸	❌	✅ width/height/constraints
外边距	❌	✅ margin 属性
性能	更轻量	稍重（组合多种功能）

建议

只需要装饰时，用 DecoratedBox 更轻量。还需要 padding、alignment 等功能时，用 Container 更方便。