This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
修饰符
用于 @expo/ui 组件的 Jetpack Compose 布局修饰符
Jetpack Compose 修饰符可用于自定义 UI 组件的布局、外观和行为。修饰符相当于 Compose 中的样式属性,可控制尺寸、内边距、背景、交互等。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
用法
使用 modifiers 属性和数组语法将修饰符应用于组件。你可以组合多个修饰符,创建复杂的样式和行为。修饰符按照它们在数组中出现的顺序应用,这可能会影响最终结果(例如,先应用 padding 再应用 background,与反过来应用会产生不同的效果)。
import { Button, Host } from '@expo/ui/jetpack-compose'; import { paddingAll, fillMaxWidth, background, border, shadow, clickable, } from '@expo/ui/jetpack-compose/modifiers'; function ModifiersExample() { return ( <Host style={{ flex: 1 }}> {/* Basic styling modifiers */} <Button modifiers={[ paddingAll(16), fillMaxWidth(), background('#FF6B6B'), ]}> Full-width padded button </Button> {/* Complex combination with border and shadow */} <Button modifiers={[ paddingAll(12), background('#4ECDC4'), border(2, '#2C3E50'), shadow(4), ]}> Styled with border and shadow </Button> </Host> ); }
你也可以创建适用于任何 Expo UI 组件的自定义修饰符。详情请参阅扩展 Jetpack Compose 组件指南。
内边距
控制组件内容周围的间距。
paddingAll(all)
在四边应用相同的内边距。
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[paddingAll(16)]}>Padded button</Button>;
padding(start, top, end, bottom)
为每一侧分别设置内边距。
import { padding } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[padding(16, 8, 16, 8)]}>Custom padding</Button>;
尺寸
控制组件的尺寸。
size(width, height)
设置组件的精确尺寸。
import { size } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[size(200, 48)]}>Fixed size</Button>;
fillMaxSize(fraction?)
填满两个方向上的所有可用空间。
import { fillMaxSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxSize()]}>Fill all space</Button> <Button modifiers={[fillMaxSize(0.5)]}>Fill half</Button>
fillMaxWidth(fraction?)
填满可用宽度。
import { fillMaxWidth } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxWidth()]}>Full width</Button>;
fillMaxHeight(fraction?)
填满可用高度。
width(value)
设置精确宽度。
height(value)
设置精确高度。
wrapContentWidth(alignment?)
将组件尺寸设置为适应其内容宽度。
wrapContentHeight(alignment?)
将组件尺寸设置为适应其内容高度。
位置
控制组件相对于其自然位置的定位。
offset(x, y)
将组件从其自然位置偏移,且不影响周围组件的布局。
import { offset } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[offset(10, 5)]}>Offset button</Button>;
外观
控制组件的视觉外观。
background(color)
设置背景颜色。
import { background } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[background('#3498DB')]}> Blue background </Button>;
border(borderWidth, borderColor)
为组件添加边框。
import { border } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[border(2, '#E74C3C')]}>Bordered button</Button>;
shadow(elevation)
在组件下方添加仰角阴影。
import { shadow } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[shadow(8)]}>Elevated button</Button>;
dropShadow(shape, config?)
在组件后方绘制阴影,并可控制模糊半径、扩散范围、偏移量和颜色。与 shadow 不同,它不需要仰角值。
import { dropShadow, Shapes, } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[ dropShadow(Shapes.RoundedCorner(24), { radius: 16, spread: 4, color: '#6200EE', offsetY: 8, }), ]}> Drop shadow </Button>;
innerShadow(shape, config?)
在组件内部绘制阴影,以创建内嵌效果。先应用 background 修饰符,再应用 innerShadow,以确保阴影能够渲染。
import { innerShadow, background, Shapes, } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[ background('#FFFFFF'), innerShadow(Shapes.RoundedCorner(24), { radius: 16, spread: 2, offsetY: 6, }), ]}> Inner shadow </Button>;
alpha(alpha)
控制组件的不透明度。
import { alpha } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[alpha(0.5)]}>Semi-transparent</Button>;
blur(radius)
为组件应用模糊效果。
import { blur } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[blur(4)]}>Blurred button</Button>;
阴影样式
常见阴影样式由 dropShadow 和 innerShadow 修饰符组合而成,而不是单独的 API。由于 modifiers 属性接受数组,你可以叠加并调整阴影修饰符,以构建各种样式。
新粗野主义阴影
新粗野主义阴影是一种边缘清晰、无模糊且带有粗边框的投影。将 radius 和 spread 设为 0,然后偏移阴影。
import { dropShadow, border, background, Shapes, } from '@expo/ui/jetpack-compose/modifiers'; <Box modifiers={[ dropShadow(Shapes.Rectangle, { radius: 0, spread: 0, offsetX: 8, offsetY: 8, color: '#000000', }), border(8, '#000000'), background('#FFFFFF'), ]} />;
新拟态阴影
新拟态阴影会在与背景颜色相同的表面上叠加两个投影:一个朝向光源的浅色阴影,以及一个位于相反方向的深色阴影。在 background 之前应用这两个阴影。
import { dropShadow, background, Shapes, } from '@expo/ui/jetpack-compose/modifiers'; const shape = Shapes.RoundedCorner(24); <Box modifiers={[ dropShadow(shape, { radius: 15, offsetX: -10, offsetY: -10, color: '#FFFFFF', }), dropShadow(shape, { radius: 15, offsetX: 10, offsetY: 10, color: '#B1B1B1', }), background('#E0E0E0'), ]} />;
要创建按下时的凹陷变体,请改用两个 innerShadow 修饰符,并将它们放在 background 之后。
变换
对组件应用视觉变换。
rotate(degrees)
旋转组件。
import { rotate } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[rotate(45)]}>Rotated</Button>;
zIndex(index)
控制重叠组件的绘制顺序。
import { zIndex } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[zIndex(10)]}>On top</Button>;
动画
为组件内的布局变化添加动画。
animateContentSize(dampingRatio?, stiffness?)
使用弹簧动画,为组件内容的尺寸变化添加动画。
import { animateContentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[animateContentSize()]}>Animated size</Button> <Button modifiers={[animateContentSize(0.5, 200)]}>Custom spring</Button>
布局
控制组件在父容器中的尺寸和位置。
weight(weight)
在 Row 或 Column 中为组件分配弹性权重,并按比例在具有权重的子项之间分配可用空间。
import { weight } from '@expo/ui/jetpack-compose/modifiers'; // In a Row, the first button takes 2/3 and the second takes 1/3 <Button modifiers={[weight(2)]}>Wider</Button> <Button modifiers={[weight(1)]}>Narrower</Button>
align(alignment)
设置组件在父容器中的对齐方式。
matchParentSize()
将组件尺寸设置为与其父级 Box 相同。与 fillMaxSize 不同,它不会影响父级的测量结果。
import { matchParentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[matchParentSize()]}>Match parent</Button>;
交互
为组件添加用户交互处理程序。
clickable(handler)
使组件能够响应点击事件。
import { clickable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[clickable(() => console.log('Clicked!'))]}> Clickable </Button>;
combinedClickable(handlers, options?)
使组件能够响应短按和长按手势。它封装了 Compose 的 Modifier.combinedClickable。适用于长按时打开 DropdownMenu,同时在同一视图上保留单独的短按操作。
import { Text } from '@expo/ui/jetpack-compose'; import { combinedClickable } from '@expo/ui/jetpack-compose/modifiers'; <Text modifiers={[ combinedClickable({ onClick: () => console.log('Tapped'), onLongClick: () => setMenuExpanded(true), }), ]}> Long-press me </Text>;
selectable(selected, handler)
使组件可被选中,类似单选按钮。
import { selectable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[ selectable(isSelected, () => setIsSelected(!isSelected)), ]}> Selectable option </Button>;
裁剪
将组件内容裁剪为指定形状。
clip(shape)
将组件裁剪为指定形状。形状边界之外的内容不会绘制。
可用形状
import { clip } from '@expo/ui/jetpack-compose/modifiers'; import { Shapes } from '@expo/ui/jetpack-compose/modifiers'; // Circular clipping <Button modifiers={[clip(Shapes.Circle)]}>Circle</Button> // Rounded corners with uniform radius <Button modifiers={[clip(Shapes.RoundedCorner(12))]}>Rounded</Button> // Rounded corners with individual radii <Button modifiers={[ clip(Shapes.RoundedCorner({ topStart: 16, topEnd: 16, bottomStart: 0, bottomEnd: 0 })), ]}> Top rounded only </Button> // Cut corners <Button modifiers={[clip(Shapes.CutCorner(8))]}>Cut corners</Button>
实用工具
testID(tag)
为组件分配测试标识符,以便在 UI 测试中使用。
import { testID } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[testID('submit-button')]}>Submit</Button>;
API
import { paddingAll, padding, size, fillMaxWidth, background, clickable, clip, Shapes } from '@expo/ui/jetpack-compose/modifiers';
Constants
Type: {
Circle: BuiltinShape,
CutCorner: (params: number | CornerRadii) => BuiltinShape,
Material: {
Arch: BuiltinShape,
Boom: BuiltinShape,
Bun: BuiltinShape,
Clover4Leaf: BuiltinShape,
Clover8Leaf: BuiltinShape,
Cookie12Sided: BuiltinShape,
Cookie4Sided: BuiltinShape,
Cookie6Sided: BuiltinShape,
Cookie7Sided: BuiltinShape,
Cookie9Sided: BuiltinShape,
Diamond: BuiltinShape,
Fan: BuiltinShape,
Ghostish: BuiltinShape,
Heart: BuiltinShape,
Oval: BuiltinShape,
Pentagon: BuiltinShape,
Pill: BuiltinShape,
PixelCircle: BuiltinShape,
PixelTriangle: BuiltinShape,
Puffy: BuiltinShape,
PuffyDiamond: BuiltinShape,
Slanted: BuiltinShape,
SoftBurst: BuiltinShape,
Sunny: BuiltinShape,
Triangle: BuiltinShape,
VerySunny: BuiltinShape
},
Rectangle: BuiltinShape,
RoundedCorner: (params: number | CornerRadii) => BuiltinShape
}
Predefined shapes for use with the clip modifier.
Example
clip(Shapes.Circle) clip(Shapes.RoundedCorner(16)) clip(Shapes.RoundedCorner({ topStart: 8, bottomEnd: 16 })) clip(Shapes.Material.Heart)
Methods
Animates size changes with spring animation.
ModifierConfigSets the background color.
Pass an animationSpec to smoothly animate between colors when the prop changes (backed by animateColorAsState).
ModifierConfigMakes the view respond to both click and long-click gestures.
Wraps Compose's Modifier.combinedClickable. Useful for triggering a DropdownMenu
on long-press while keeping a separate short-press action.
ModifierConfigFactory function to create modifier configuration objects.
ModifierConfigConstrain the size of the wrapped layout only when it would be
otherwise unconstrained: the minWidth and minHeight constraints
are only applied when the incoming corresponding constraint is 0.
ModifierConfigDraws a shadow behind the view with control over the blur radius, spread, offset, and color. Unlike
shadow, it does not require an elevation value.
ModifierConfigApplies a graphics layer transformation with animation support.
ModifierConfigMakes the view horizontally scrollable.
Wraps Modifier.horizontalScroll(rememberScrollState()).
Use on a Row to create a non-lazy scrollable container.
ModifierConfigAdds padding to avoid the software keyboard (IME). When the keyboard is visible, padding is added to keep content above it.
ModifierConfigDraws a shadow inside the view to create an inset effect. The view's background must come before
this modifier for the shadow to render.
ModifierConfig{
$type: 'keyframes',
delayMillis: number,
durationMillis: number,
keyframes: Record<number, number>
}Clips a carousel item's mask to the given shape, so the item keeps its shape while the
carousel masks it. Wraps Compose's CarouselItemScope.maskClip.
A carousel reveals each item through a mask, so a plain clip on the item loses its
corners as the item squeezes into a peek. Clipping the mask itself keeps them.
Only works on a child of a Carousel component. Like clip, it only affects what is
drawn after it in the modifier chain, so place it before background.
ModifierConfigExample
modifiers={[size(300, 200), maskClip(Shapes.RoundedCorner(28)), background('#6200EE')]}
Makes the view match the parent Box size. Only works when used inside Box.
ModifierConfigMarks a composable as the anchor for an ExposedDropdownMenuBox.
Only works when used inside ExposedDropdownMenuBox.
ModifierConfigCalls the handler whenever the composable is positioned, with its position and size.
x and y are relative to the window. All values are in dp.
ModifierConfigCalls the handler whenever the composable's measured size changes. Sizes are in dp.
ModifierConfigCalls the handler when the composable's visibility changes (for example, enters or leaves the viewport in a lazy list).
ModifierConfigApplies padding with individual values for each side.
ModifierConfigMakes the view selectable, like a radio button row.
ModifierConfigMarks a column/row as a selectable group for accessibility. Screen readers will treat the children as a group of selectable items.
ModifierConfigApplies semantic properties. Wraps Modifier.semantics { ... }.
ModifierConfig{
$type: 'spring',
dampingRatio: number,
stiffness: number,
visibilityThreshold: number
}Makes the view toggleable with accessibility semantics. Use this to make a row containing a checkbox or switch tappable as a whole.
ModifierConfig{
$type: 'tween',
delayMillis: number,
durationMillis: number,
easing: 'linear' | 'fastOutSlowIn' | 'fastOutLinearIn' | 'linearOutSlowIn' | 'ease'
}Makes the view vertically scrollable.
Wraps Modifier.verticalScroll(rememberScrollState()).
Use on a Column to create a non-lazy scrollable container.
ModifierConfigSets the weight for flexible sizing in Row or Column. Only works when used inside Row or Column.
ModifierConfigEvent subscriptions
Creates a modifier with an event listener.
ModifierConfigInterfaces
Modifier configuration for native views. This is the JSON Config pattern used by both iOS (SwiftUI) and Android (Jetpack Compose).
Types
Literal type: string
Acceptable values are: 'topStart' | 'topCenter' | 'topEnd' | 'centerStart' | 'center' | 'centerEnd' | 'bottomStart' | 'bottomCenter' | 'bottomEnd' | 'top' | 'centerVertically' | 'bottom' | 'start' | 'centerHorizontally' | 'end'
Built-in Jetpack Compose shape for the clip modifier.
Type: object shaped as below:
Or object shaped as below:
Or object shaped as below:
Or object shaped as below:
Or object shaped as below:
Deprecated: Use ModifierConfig instead. ExpoModifier (SharedRef pattern) has been replaced with JSON Config pattern for better DX and platform consistency.
Type: ModifierConfig