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 }}> {/* 基础样式修饰符 */} <Button modifiers={[paddingAll(16), fillMaxWidth(), background('#FF6B6B')]}> 全宽带内边距按钮 </Button> {/* 带有边框和阴影的复杂组合 */} <Button modifiers={[paddingAll(12), background('#4ECDC4'), border(2, '#2C3E50'), shadow(4)]}> 带边框和阴影的样式按钮 </Button> </Host> ); }
内边距
控制组件内容周围的间距。
paddingAll(all)
在四个边上应用相等的内边距。
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[paddingAll(16)]}>带内边距的按钮</Button>;
padding(start, top, end, bottom)
分别为每一侧应用内边距。
import { padding } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[padding(16, 8, 16, 8)]}>自定义内边距</Button>;
大小
控制组件的尺寸。
size(width, height)
为组件设置精确尺寸。
import { size } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[size(200, 48)]}>固定大小</Button>;
fillMaxSize(fraction?)
在宽高两个方向上填充所有可用空间。
import { fillMaxSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxSize()]}>填满所有空间</Button> <Button modifiers={[fillMaxSize(0.5)]}>填满一半</Button>
fillMaxWidth(fraction?)
填充可用宽度。
import { fillMaxWidth } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxWidth()]}>全宽</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)]}>偏移按钮</Button>;
外观
控制组件的视觉外观。
background(color)
设置背景颜色。
import { background } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[background('#3498DB')]}>蓝色背景</Button>;
border(borderWidth, borderColor)
为组件添加边框。
import { border } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[border(2, '#E74C3C')]}>带边框按钮</Button>;
shadow(elevation)
为组件下方添加海拔阴影。
import { shadow } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[shadow(8)]}>有层次感的按钮</Button>;
alpha(alpha)
控制组件的不透明度。
import { alpha } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[alpha(0.5)]}>半透明</Button>;
blur(radius)
为组件应用模糊效果。
import { blur } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[blur(4)]}>模糊按钮</Button>;
变换
对组件应用视觉变换。
rotate(degrees)
旋转组件。
import { rotate } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[rotate(45)]}>已旋转</Button>;
zIndex(index)
控制重叠组件的绘制顺序。
import { zIndex } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[zIndex(10)]}>置顶</Button>;
动画
为组件内的布局变化添加动画。
animateContentSize(dampingRatio?, stiffness?)
使用弹簧动画为组件内容的尺寸变化添加动画。
import { animateContentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[animateContentSize()]}>尺寸动画</Button> <Button modifiers={[animateContentSize(0.5, 200)]}>自定义弹簧</Button>
布局
控制组件在其父容器中的尺寸和位置。
weight(weight)
在 Row 或 Column 内为组件分配弹性权重,使可用空间在带权重的子项之间按比例分配。
import { weight } from '@expo/ui/jetpack-compose/modifiers'; // 在 Row 中,第一个按钮占 2/3,第二个占 1/3 <Button modifiers={[weight(2)]}>更宽</Button> <Button modifiers={[weight(1)]}>更窄</Button>
align(alignment)
设置组件在其父容器中的对齐方式。
matchParentSize()
将组件大小设为与其父 Box 的大小一致。与 fillMaxSize 不同,这不会影响父组件的测量。
import { matchParentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[matchParentSize()]}>匹配父级</Button>;
交互
为组件添加用户交互处理器。
clickable(handler)
使组件响应点击事件。
import { clickable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[clickable(() => console.log('Clicked!'))]}>可点击</Button>;
selectable(selected, handler)
使组件可选中,类似单选按钮。
import { selectable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[selectable(isSelected, () => setIsSelected(!isSelected))]}> 可选项 </Button>;
裁剪
将组件的内容裁剪为特定形状。
clip(shape)
将组件裁剪为给定形状。形状边界之外的内容不会被绘制。
可用形状
import { clip } from '@expo/ui/jetpack-compose/modifiers'; import { Shapes } from '@expo/ui/jetpack-compose/modifiers'; // 圆形裁剪 <Button modifiers={[clip(Shapes.Circle)]}>圆形</Button> // 统一半径的圆角 <Button modifiers={[clip(Shapes.RoundedCorner(12))]}>圆角</Button> // 单独设置各个角的圆角 <Button modifiers={[ clip(Shapes.RoundedCorner({ topStart: 16, topEnd: 16, bottomStart: 0, bottomEnd: 0 })), ]}> 仅顶部圆角 </Button> // 切角 <Button modifiers={[clip(Shapes.CutCorner(8))]}>切角</Button>
工具
testID(tag)
为组件分配一个测试标识符,以便在 UI 测试中使用。
import { testID } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[testID('submit-button')]}>提交</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>
}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' | 'ease' | 'fastOutSlowIn' | 'fastOutLinearIn' | 'linearOutSlowIn'
}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