15、修饰符列表

Compose 修饰符列表

Compose 提供了大量修饰符，可用于调整可组合项的外观、行为和交互。以下是最常用的修饰符列表，按照其主要功能组织。

布局修饰符

尺寸修饰符

Modifier.size(100.dp)  // 将内容尺寸设置为精确的宽度和高度
Modifier.width(100.dp) // 仅设置宽度
Modifier.height(100.dp) // 仅设置高度
Modifier.requiredSize(100.dp) // 强制设置确切尺寸，忽略父级约束
Modifier.fillMaxWidth(0.5f) // 填充父级最大宽度的50%
Modifier.fillMaxHeight() // 填充父级全部高度
Modifier.wrapContentSize() // 根据内容调整尺寸
Modifier.requiredWidth(IntrinsicSize.Min) // 将宽度设置为内容的最小固有宽度

边距和填充修饰符

Modifier.padding(16.dp) // 在所有方向添加内边距
Modifier.padding(start = 8.dp, top = 16.dp) // 为特定方向添加内边距
Modifier.paddingFromBaseline(top = 24.dp) // 从基线上方添加内边距
Modifier.offset(x = 16.dp, y = 8.dp) // 相对于原始位置偏移
Modifier.offset { IntOffset(x = 10, y = 20) } // 使用lambda计算偏移

对齐修饰符

Modifier.align(Alignment.Center) // 在父容器中对齐(用于Column或Row的子项)
Modifier.alignByBaseline() // 按基线对齐(仅适用于Row)
Modifier.matchParentSize() // 匹配父Box的尺寸(仅适用于Box的子项)
Modifier.fillMaxSize() // 填充父级所有可用空间

作用域修饰符

// 在Column中
Modifier.weight(1f) // 根据权重分配剩余空间
Modifier.weight(1f, fill = false) // 分配空间但不填充

// 在Row中
Modifier.weight(1f) // 根据权重分配剩余空间
Modifier.align(Alignment.CenterVertically) // 垂直对齐

// 在Box中
Modifier.matchParentSize() // 匹配父Box的尺寸
Modifier.align(Alignment.TopEnd) // 在Box中对齐

绘制修饰符

Modifier.background(Color.Blue) // 添加纯色背景
Modifier.background(brush) // 添加渐变背景
Modifier.border(2.dp, Color.Red) // 添加边框
Modifier.border(2.dp, Color.Red, shape = CircleShape) // 带形状的边框
Modifier.clip(RoundedCornerShape(8.dp)) // 裁剪内容为指定形状
Modifier.clipToBounds() // 裁剪到布局边界
Modifier.shadow(elevation = 4.dp) // 添加阴影
Modifier.graphicsLayer { // 高级图形效果
    alpha = 0.5f
    rotationZ = 45f
    scaleX = 0.8f
}
Modifier.drawBehind { // 在内容后方自定义绘制
    drawRect(Color.Red, topLeft = Offset(10f, 10f), size = Size(50f, 50f))
}
Modifier.drawWithCache { // 缓存绘制资源
    val paint = Paint().apply { color = Color.Red }
    onDrawBehind {
        drawRect(paint, size = size)
    }
}
Modifier.drawWithContent { // 自定义内容绘制
    drawContent() // 绘制原始内容
    drawRect(Color.Red.copy(alpha = 0.3f), size = size)
}

交互修饰符

Modifier.clickable(onClick = { /* 处理点击 */ }) // 使元素可点击
Modifier.clickable(
    enabled = true,
    onClickLabel = "Description for accessibility",
    role = Role.Button,
    onClick = { /* 处理点击 */ }
) // 带无障碍功能的可点击

Modifier.triStateToggleable( // 三态切换(开/关/不确定)
    state = ToggleableState.Indeterminate,
    onClick = { /* 处理点击 */ }
)

Modifier.toggleable( // 双态切换
    value = checked,
    onValueChange = { checked = it }
)

Modifier.selectable( // 可选择项
    selected = isSelected,
    onClick = { /* 处理选择 */ },
    role = Role.RadioButton
)

Modifier.indication(interactionSource, indication) // 添加视觉反馈

手势修饰符

Modifier.pointerInput(Unit) { // 基本手势处理
    detectTapGestures(
        onPress = { /* 手指按下 */ },
        onDoubleTap = { /* 双击 */ },
        onLongPress = { /* 长按 */ },
        onTap = { /* 点击 */ }
    )
}

Modifier.draggable( // 拖动手势
    interactionSource = interactionSource,
    orientation = Orientation.Vertical,
    state = dragState,
    onDragStopped = { velocity ->
        // 处理拖动停止
    }
)

Modifier.scrollable( // 滚动手势
    interactionSource = interactionSource,
    orientation = Orientation.Vertical,
    state = scrollState,
    enabled = true,
    reverseDirection = false
)

Modifier.nestedScroll( // 嵌套滚动
    rememberNestedScrollInteropConnection()
)

可访问性修饰符

Modifier.semantics { // 设置语义属性
    contentDescription = "Image description"
    onClick {
        // 处理点击
        true
    }
}

Modifier.testTag("myTestTag") // 为测试添加标签
Modifier.testTagsAsResourceId(true) // 将测试标签视为资源ID

实用工具修饰符

Modifier.alpha(0.5f) // 设置不透明度
Modifier.zIndex(1f) // 设置z轴顺序
Modifier.onGloballyPositioned { // 获取布局位置
    val position = it.positionInRoot()
}
Modifier.onSizeChanged { size -> // 获取布局尺寸
    // 处理尺寸变化
}
Modifier.onFocusChanged { focusState -> // 处理焦点变化
    if (focusState.isFocused) {
        // 获取焦点
    }
}
Modifier.focusable() // 使元素可聚焦
Modifier.focusProperties { // 自定义焦点行为
    left = previousFocusableItem
}

创建自定义修饰符

// 简单组合现有修饰符
fun Modifier.myBackground(color: Color) = this
    .padding(16.dp)
    .clip(RoundedCornerShape(8.dp))
    .background(color)

// 使用 Modifier.Node 创建高性能自定义修饰符
fun Modifier.circle(color: Color) = this then CircleElement(color)

private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)
    override fun update(node: CircleNode) {
        node.color = color
    }
}

private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}

修饰符顺序的重要性

修饰符应用的顺序非常重要，会影响最终结果：

// 正确：整个区域(包括内边距)都是可点击的
Modifier
    .clickable(onClick = { /* ... */ })
    .padding(16.dp)

// 不同结果：只有内容区域可点击，内边距区域不可点击
Modifier
    .padding(16.dp)
    .clickable(onClick = { /* ... */ })

了解修饰符如何按顺序应用，对于创建预期的UI行为至关重要。修饰符从左到右依次应用，每个修饰符基于前一个修饰符的结果进行操作。