Compose 中 Modifier 详细讲解（完整版）

在 Jetpack Compose 中，Modifier 是最核心的概念之一。

你可以把它理解成：

Modifier = ViewGroup.LayoutParams + View属性 + 事件处理 + 动画扩展

传统 Android：

Button button = findViewById(...)button.setPadding(...)button.setBackground(...)button.setOnClickListener(...)

Compose：

Button(    modifier = Modifier        .padding(16.dp)        .background(Color.Red)        .clickable { })

所有外观、布局、事件、动画几乎都通过 Modifier 完成。

一、Modifier 本质

Modifier 本身是一个不可变链表。

例如：

Modifier    .padding(10.dp)    .background(Color.Red)    .clickable { }

实际上类似：

Modifier ├── Padding ├── Background └── Clickable

Compose 从前往后执行。

二、Modifier 为什么必须放前面

官方规范：

@Composablefun UserCard(    modifier: Modifier = Modifier)

永远放第一个参数。

正确：

@Composablefun UserCard(    modifier: Modifier = Modifier,    name: String)

使用：

UserCard(    modifier = Modifier.padding(20.dp),    name = "Tom")

这样组件才具备可复用性。

三、Layout（布局类 Modifier）

最常用。

1 fillMaxSize()

占满父布局

Box(    Modifier.fillMaxSize())

等价：

match_parent

2 fillMaxWidth()

Modifier.fillMaxWidth()

占满宽度。

3 fillMaxHeight()

Modifier.fillMaxHeight()

占满高度。

4 fillMaxWidth(percent)

Modifier.fillMaxWidth(0.5f)

占父布局50%。

5 size()

固定大小

Modifier.size(100.dp)

宽高都100dp。

6 width()

Modifier.width(200.dp)

7 height()

Modifier.height(80.dp)

8 requiredSize()

强制大小

Modifier.requiredSize(100.dp)

即使父布局限制也生效。

9 sizeIn()

范围限制

Modifier.sizeIn(    minWidth = 100.dp,    maxWidth = 300.dp)

四、Padding

padding()

最常见

Modifier.padding(16.dp)

四边同时。

单独指定

Modifier.padding(    start = 10.dp,    top = 20.dp)

水平垂直

Modifier.padding(    horizontal = 16.dp,    vertical = 8.dp)

五、位置控制

offset()

移动位置

Modifier.offset(    x = 20.dp,    y = 30.dp)

类似：

transform: translate()

注意：

不改变布局大小。

absoluteOffset()

忽略 RTL

Modifier.absoluteOffset(20.dp)

六、背景相关

background()

Modifier.background(Color.Red)

圆角：

Modifier.background(    Color.Blue,    RoundedCornerShape(10.dp))

border()

边框

Modifier.border(    2.dp,    Color.Red)

圆角边框：

Modifier.border(    2.dp,    Color.Red,    RoundedCornerShape(10.dp))

七、形状裁剪

clip()

Modifier.clip(    RoundedCornerShape(20.dp))

裁剪内容。

头像：

Image(    modifier = Modifier.clip(CircleShape))

八、透明度

alpha()

Modifier.alpha(0.5f)

范围：

0~1

九、旋转缩放

rotate()

Modifier.rotate(45f)

scale()

Modifier.scale(1.5f)

放大1.5倍。

graphicsLayer()

最强大的图形变换

Modifier.graphicsLayer {    rotationX = 30f    rotationY = 30f    scaleX = 1.5f    scaleY = 1.5f}

支持：

3D旋转
阴影
缩放
透明度

十、点击事件

clickable()

Modifier.clickable {    println("click")}

combinedClickable()

支持：

Modifier.combinedClickable(    onClick = {},    onLongClick = {},    onDoubleClick = {})

十一、滚动

verticalScroll()

val state = rememberScrollState()Column(    Modifier.verticalScroll(state))

horizontalScroll()

Row(    Modifier.horizontalScroll(state))

十二、拖拽手势

draggable()

Modifier.draggable(    state = rememberDraggableState {})

pointerInput()

最底层手势API

Modifier.pointerInput(Unit) {    detectTapGestures {    }}

可以实现：

点击
长按
双击
拖拽
缩放

十三、焦点

focusable()

Modifier.focusable()

focusRequester()

val requester = remember {    FocusRequester()}Modifier.focusRequester(requester)

十四、键盘

onKeyEvent()

Modifier.onKeyEvent {}

监听：

EnterEscF1方向键

十五、权重布局

weight()

Column / Row 专属

Row {    Box(        Modifier.weight(1f)    )    Box(        Modifier.weight(2f)    )}

结果：

1 : 2

十六、对齐

align()

Column：

Modifier.align(    Alignment.CenterHorizontally)

Box：

Modifier.align(    Alignment.Center)

十七、Z轴层级

zIndex()

Modifier.zIndex(100f)

数值越大越靠前。

十八、动画

animateContentSize()

Modifier.animateContentSize()

内容变化自动动画。

animateItem()

LazyColumn动画

Modifier.animateItem()

十九、阴影

shadow()

Modifier.shadow(    elevation = 10.dp)

二十、系统 Insets

状态栏适配。

statusBarsPadding()

Modifier.statusBarsPadding()

navigationBarsPadding()

Modifier.navigationBarsPadding()

safeDrawingPadding()

Modifier.safeDrawingPadding()

全面屏推荐。

二十一、绘制类 Modifier

drawBehind()

先画背景

Modifier.drawBehind {    drawCircle(Color.Red)}

drawWithContent()

先画自己

Modifier.drawWithContent {    drawContent()    drawRect(Color.Red)}

drawWithCache()

缓存绘制对象

Modifier.drawWithCache {}

性能最佳。

二十二、语义（无障碍）

semantics()

Modifier.semantics {}

用于：

TalkBack
UI测试
Accessibility

二十三、性能最重要知识

很多人写：

Text(    modifier = Modifier        .padding(10.dp)        .background(Color.Red)        .padding(10.dp))

实际上顺序不同结果完全不同。

例如：

写法1

Modifier    .background(Color.Red)    .padding(20.dp)

效果：

红色背景┌────────────┐│            ││  padding   ││            │└────────────┘

背景包含Padding。

写法2

Modifier    .padding(20.dp)    .background(Color.Red)

效果：

padding┌────────────┐│ 红色背景    │└────────────┘

背景不包含Padding。

Modifier 执行顺序口诀

Modifier    .size()    .padding()    .background()    .clip()    .clickable()

记忆：

布局(Layout) ↓绘制(Draw) ↓裁剪(Clip) ↓事件(Input) ↓动画(Animation)

实际开发最常见组合

Modifier    .fillMaxWidth()    .padding(16.dp)    .clip(RoundedCornerShape(12.dp))    .background(Color.White)    .clickable { }

这几乎就是 Compose 中 Card、ListItem、设置页条目的标准写法。

掌握了 Modifier 后，基本上已经掌握了 Compose UI 开发中 60% 以上的核心内容。接下来深入学习时，重点建议研究 Modifier.Node 机制、Layout Modifier（自定义布局）、Draw Modifier（自定义绘制）、PointerInput（手势系统）以及 Modifier 顺序对测量/绘制的影响，这些才是 Compose 高级开发的核心