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 中的样式属性的等价物——它们控制大小、内边距、背景、交互等。
🌐 Jetpack Compose modifiers allow you to customize the layout, appearance, and behavior of UI components. Modifiers are the Compose equivalent of style properties — they control sizing, padding, backgrounds, interactions, and more.
安装
🌐 Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
用法
🌐 Usage
修饰符通过使用带有数组语法的 modifiers 属性应用于组件。你可以组合多个修饰符来创建复杂的样式和行为。修饰符按它们在数组中出现的顺序应用,这可能会影响最终结果(例如,在 background 之前应用 padding 会产生与相反顺序不同的结果)。
🌐 Modifiers are applied to components using the modifiers prop with an array syntax. You can combine multiple modifiers to create complex styling and behavior. Modifiers are applied in the order they appear in the array, which can affect the final result (for example, applying padding before background produces different results than the reverse).
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 组件 指南。
填充
🌐 Padding
控制组件内容周围的间距。
🌐 Control the spacing around a component's content.
paddingAll(all)
在四个边上应用相等的填充。
🌐 Applies equal padding on all four sides.
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[paddingAll(16)]}>Padded button</Button>;
padding(start, top, end, bottom)
对每一侧应用单独的填充。
🌐 Applies individual padding to each side.
import { padding } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[padding(16, 8, 16, 8)]}>Custom padding</Button>;
尺寸
🌐 Size
控制组件的尺寸。
🌐 Control the dimensions of a component.
size(width, height)
为组件设置精确尺寸。
🌐 Sets exact dimensions for the component.
import { size } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[size(200, 48)]}>Fixed size</Button>;
fillMaxSize(fraction?)
在两个维度上填充所有可用空间。
🌐 Fills all available space in both dimensions.
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?)
填充可用宽度。
🌐 Fills available width.
import { fillMaxWidth } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxWidth()]}>Full width</Button>;
fillMaxHeight(fraction?)
填充可用高度。
🌐 Fills available height.
width(value)
设置内容的确切宽度,或者最小或最大固有宽度。传入的约束仍然可能让视图比这个宽度更窄或更宽。
🌐 Sets an exact width, or the minimum or maximum intrinsic width of the content. The incoming constraints can still make the view narrower or wider than that width.
一种情况是一个带有 matchContents 的 Host:可用宽度没有限制,所以在 Row 中带有 weight 的子元素没有空间。在下面的例子中,width(IntrinsicSize.Max) 给 Row 所需的内容宽度,fillMaxWidth() 之前保持这一行填满有限的宽度,而 weight(1) 给标签留出开关旁边的空间:
🌐 One case is a Host with matchContents: the available width has no limit, so children with weight in a Row get no space. In the following example, width(IntrinsicSize.Max) gives the Row the width its content needs, fillMaxWidth() before it keeps the row filling a bounded width, and weight(1) gives the label the space left next to the switch:
import { Host, Row, Switch, Text } from '@expo/ui/jetpack-compose'; import { fillMaxWidth, IntrinsicSize, weight, width, } from '@expo/ui/jetpack-compose/modifiers'; <Host matchContents> <Row modifiers={[fillMaxWidth(), width(IntrinsicSize.Max)]}> <Text modifiers={[weight(1)]}>Errors only</Text> <Switch value={checked} onCheckedChange={setChecked} /> </Row> </Host>;
height(value)
设置一个精确的高度。
🌐 Sets an exact height.
wrapContentWidth(alignment?)
调整组件的尺寸以适应其内容的宽度。
🌐 Sizes the component to wrap its content width.
wrapContentHeight(alignment?)
调整组件的尺寸以适应其内容的高度。
🌐 Sizes the component to wrap its content height.
位置
🌐 Position
控制组件相对于其自然位置的位置。
🌐 Control the position of a component relative to its natural placement.
offset(x, y)
将组件从其自然位置偏移,而不影响周围组件的布局。
🌐 Offsets the component from its natural position without affecting the layout of surrounding components.
import { offset } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[offset(10, 5)]}>Offset button</Button>;
外观
🌐 Appearance
控制组件的视觉外观。
🌐 Control the visual appearance of a component.
background(color)
设置背景颜色。
🌐 Sets the background color.
import { background } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[background('#3498DB')]}> Blue background </Button>;
border(borderWidth, borderColor)
在组件周围添加边框。
🌐 Adds a border around the component.
import { border } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[border(2, '#E74C3C')]}>Bordered button</Button>;
shadow(elevation)
在组件下方添加一个高度阴影。
🌐 Adds an elevation shadow beneath the component.
import { shadow } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[shadow(8)]}>Elevated button</Button>;
dropShadow(shape, config?)
在组件后面绘制阴影,可以控制模糊半径、扩散、偏移和颜色。与 shadow 不同,它不需要高度值。
🌐 Draws a shadow behind the component with control over the blur radius, spread, offset, and color. Unlike shadow, it does not require an elevation value.
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?)
在组件内部绘制阴影以创建内嵌效果。在 innerShadow 之前应用 background 修饰符以便渲染阴影。
🌐 Draws a shadow inside the component to create an inset effect. Apply the background modifier before innerShadow so the shadow renders.
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)
控制组件的不透明度。
🌐 Controls the opacity of the component.
import { alpha } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[alpha(0.5)]}>Semi-transparent</Button>;
blur(radius)
对组件应用模糊效果。
🌐 Applies a blur effect to the component.
import { blur } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[blur(4)]}>Blurred button</Button>;
cornerRadius(radius)
给组件加上圆角。
🌐 Adds rounded corners to the component.
信息 仅在使用
expo-widgets构建的 Android 小部件内有效,适用于 Android 12(API 级别 31)及更高版本。
Jetpack Compose 没有与 Glance 的 cornerRadius 完全相同的对应功能,所以 Expo UI 会忽略这个修饰符。可以使用 clip(Shapes.RoundedCorner(radius)) 在应用中圆角处理。
🌐 Jetpack Compose has no exact equivalent of Glance's cornerRadius, so Expo UI ignores this modifier. Use clip(Shapes.RoundedCorner(radius)) to round corners in an app.
import { background, cornerRadius, } from '@expo/ui/jetpack-compose/modifiers'; <Box modifiers={[cornerRadius(12), background('#3498DB')]} />;
暗影秘诀
🌐 Shadow recipes
常见的阴影样式是 dropShadow 和 innerShadow 修饰符的组合,而不是独立的 API。由于 modifiers 属性接收数组,你可以堆叠并调整阴影修饰符来构建每种样式。
🌐 Common shadow styles are combinations of the dropShadow and innerShadow modifiers rather than separate APIs. Because the modifiers prop takes an array, you stack and tune the shadow modifiers to build each style.
新野兽派阴影
🌐 Neobrutalist shadow
新野兽主义阴影是一种没有模糊且边缘厚重的硬边投影。将 radius 和 spread 设置为 0,然后偏移阴影。
🌐 A neobrutalist shadow is a hard-edged drop shadow with no blur and a thick border. Set radius and spread to 0, then offset the shadow.
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'), ]} />;
新拟态阴影
🌐 Neumorphic shadow
拟态阴影在与其背景颜色相同的表面上叠加两个投影:一个朝向光源的浅阴影,另一个在相对方向的深阴影。在 background 之前应用两个阴影。
🌐 A neumorphic shadow layers two drop shadows on a surface that shares its background color: a light shadow toward the light source and a darker shadow on the opposite side. Apply both before the 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 之后。
🌐 To create the pressed, recessed variant, use two innerShadow modifiers instead and place them after the background.
变形
🌐 Transform
对组件应用视觉变换。
🌐 Apply visual transformations to a component.
rotate(degrees)
旋转组件。
🌐 Rotates the component.
import { rotate } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[rotate(45)]}>Rotated</Button>;
zIndex(index)
控制重叠组件的绘制顺序。
🌐 Controls the drawing order of overlapping components.
import { zIndex } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[zIndex(10)]}>On top</Button>;
动画
🌐 Animation
在组件内为布局更改添加动画。
🌐 Animate layout changes within a component.
animateContentSize(dampingRatio?, stiffness?)
使用弹簧动画为组件内容的大小变化添加动画效果。
🌐 Animates size changes of the component's content using a spring animation.
import { animateContentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[animateContentSize()]}>Animated size</Button> <Button modifiers={[animateContentSize(0.5, 200)]}>Custom spring</Button>
布局
🌐 Layout
控制组件在其父容器中的大小和位置。
🌐 Control how a component is sized and positioned within its parent container.
weight(weight)
为 Row 或 Column 内的组件分配灵活的权重,在加权子组件之间按比例分配可用空间。
🌐 Assigns a flexible weight to a component inside a Row or Column, distributing available space proportionally among weighted children.
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)
设置组件在其父容器中的对齐方式。
🌐 Sets the alignment of the component within its parent container.
matchParentSize()
将组件的大小调整为与其父组件 Box 的大小相匹配。与 fillMaxSize 不同,这不会影响父组件的测量。
🌐 Sizes the component to match the size of its parent Box. Unlike fillMaxSize, this does not affect the parent's measurement.
import { matchParentSize } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[matchParentSize()]}>Match parent</Button>;
互动
🌐 Interaction
为组件添加用户交互处理程序。
🌐 Add user interaction handlers to a component.
clickable(handler)
使组件响应点击事件。
🌐 Makes the component respond to click events.
import { clickable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[clickable(() => console.log('Clicked!'))]}> Clickable </Button>;
combinedClickable(handlers, options?)
使组件能够响应短按和长按手势。封装了 Compose 的 Modifier.combinedClickable。在长按时打开 DropdownMenu 的同时,在同一视图上保持独立的短按操作,非常有用。
🌐 Makes the component respond to both short-tap and long-press gestures. Wraps Compose's Modifier.combinedClickable. Useful for opening a DropdownMenu on long-press while keeping a separate short-tap action on the same view.
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)
使组件可选择,类似于单选按钮。
🌐 Makes the component selectable, similar to a radio button.
import { selectable } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[ selectable(isSelected, () => setIsSelected(!isSelected)), ]}> Selectable option </Button>;
剪辑
🌐 Clipping
将组件的内容裁剪为特定形状。
🌐 Clip a component's content to a specific shape.
clip(shape)
将组件裁剪到给定形状。形状边界外的内容不会被绘制。
🌐 Clips the component to the given shape. Content outside the shape boundary is not drawn.
可用形状
🌐 Available shapes
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>
实用工具
🌐 Utility
testID(tag)
为组件分配一个测试标识符,以便在 UI 测试中使用。
🌐 Assigns a test identifier to the component for use in UI testing.
import { testID } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[testID('submit-button')]}>Submit</Button>;
semantics(params)
设置可被无障碍和自动填充服务读取的语义属性。
🌐 Sets semantic properties that accessibility and autofill services read.
import { semantics } from '@expo/ui/jetpack-compose/modifiers'; // The visible label is an abbreviation; TalkBack reads the full phrase. <Text modifiers={[semantics({ contentDescription: '1 week' })]}> 1W </Text>;
应用接口
🌐 API
import { paddingAll, padding, size, fillMaxWidth, background, clickable, clip, Shapes } from '@expo/ui/jetpack-compose/modifiers';
No API data file found, sorry!