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 布局修饰符。

Android
Included in Expo Go
Recommended version:
~58.0.15

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

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

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> ); }

填充

🌐 Padding

控制组件内容周围的间距。

🌐 Control the spacing around a component's content.

paddingAll(all)

在四个边上应用相等的填充。

🌐 Applies equal padding on all four sides.

参数类型描述
allnumber以 dp 为单位的填充值。
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.

参数类型描述
startnumber左/起始填充(dp)。
topnumber顶部填充(dp)。
endnumber右/结束填充(dp)。
bottomnumber底部填充(dp)。
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.

参数类型描述
widthnumber宽度,单位为 dp。
heightnumber高度,单位为 dp。
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.

参数类型描述
fractionnumber可用空间的分数(0.0–1.0)。默认值 1.0。
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.

参数类型描述
fractionnumber可用宽度的比例(0.0–1.0)。默认值 1.0。
import { fillMaxWidth } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[fillMaxWidth()]}>Full width</Button>;

fillMaxHeight(fraction?)

填充可用高度。

🌐 Fills available height.

参数类型描述
fractionnumber可用高度的分数(0.0–1.0)。默认值 1.0。

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.

参数类型描述
valuenumber | IntrinsicSize宽度(dp)或 IntrinsicSize。IntrinsicSize.Min 使用最小固有宽度,即内容仍能正确显示的最小宽度(对于文本,就是最宽的单词)。IntrinsicSize.Max 使用最大固有宽度,即内容在没有任何限制时需要的宽度(对于文本,就是一行文字的宽度)。

一种情况是一个带有 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.

参数类型描述
valuenumber高度,单位为dp。

wrapContentWidth(alignment?)

调整组件的尺寸以适应其内容的宽度。

🌐 Sizes the component to wrap its content width.

参数类型描述
alignmentstring内容的水平对齐方式。

wrapContentHeight(alignment?)

调整组件的尺寸以适应其内容的高度。

🌐 Sizes the component to wrap its content height.

参数类型描述
alignmentstring内容的垂直对齐方式。

位置

🌐 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.

参数类型描述
xnumber水平偏移量(以 dp 为单位)。
ynumber垂直偏移量(以 dp 为单位)。
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.

参数类型描述
colorstring背景颜色(十六进制字符串)。
import { background } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[background('#3498DB')]}> Blue background </Button>;

border(borderWidth, borderColor)

在组件周围添加边框。

🌐 Adds a border around the component.

参数类型描述
borderWidthnumber边框宽度(dp)。
borderColorstring边框颜色(十六进制字符串)。
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.

参数类型描述
elevationnumber阴影高度(以 dp 为单位)。
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.

参数类型描述
shapeShape阴影的形状(见下表形状)。
config.radiusnumber模糊半径,单位为 dp。
config.spreadnumber扩展(正值)或收缩(负值)的量,单位为 dp。
config.colorstring阴影颜色(十六进制字符串)。默认为黑色。
config.offsetXnumber水平偏移,单位为 dp。
config.offsetYnumber垂直偏移,单位为 dp。
config.alphanumber阴影不透明度(0.0–1.0)。
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.

参数类型描述
shapeShape阴影的形状(见下表形状)。
config.radiusnumber模糊半径,单位为 dp。
config.spreadnumber扩展(正值)或收缩(负值)的量,单位为 dp。
config.colorstring阴影颜色(十六进制字符串)。默认为黑色。
config.offsetXnumber水平偏移,单位为 dp。
config.offsetYnumber垂直偏移,单位为 dp。
config.alphanumber阴影不透明度(0.0–1.0)。
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.

参数类型描述
alphanumber透明度值(0.0–1.0)。
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.

参数类型描述
radiusnumber模糊半径,单位为 dp。
import { blur } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[blur(4)]}>Blurred button</Button>;

cornerRadius(radius)

给组件加上圆角。

🌐 Adds rounded corners to the component.

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.

参数类型描述
radiusnumber圆角半径,单位dp。
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.

参数类型描述
degreesnumber旋转角度(度)。
import { rotate } from '@expo/ui/jetpack-compose/modifiers'; <Button modifiers={[rotate(45)]}>Rotated</Button>;

zIndex(index)

控制重叠组件的绘制顺序。

🌐 Controls the drawing order of overlapping components.

参数类型描述
indexnumber层索引。
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.

参数类型描述
dampingRationumber弹簧阻尼比。控制弹性。
stiffnessnumber弹簧刚度。控制动画速度。
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.

参数类型描述
weightnumber权重因子。
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.

参数类型描述
alignmentstring容器内的对齐方式。

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.

参数类型描述
handler() => void点击时调用的回调函数。
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.

参数类型描述
handlers.onClick() => void可选回调,在短按时调用。
handlers.onLongClick() => void可选回调,在长按时调用。
options.indicationboolean是否显示波纹效果。默认值为 true。
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.

参数类型描述
selectedboolean组件当前是否被选中。
handler() => void在选择状态变化时调用的回调。
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.

参数类型描述
shapeShape要裁剪到的形状。

可用形状

🌐 Available shapes

形状描述
Shapes.Rectangle一个没有圆角的矩形。
Shapes.Circle一个完美的圆形。
Shapes.RoundedCorner(radius)一个四角均匀圆角的矩形。通过传入 number 可以设定相等半径,或者传入对象 { topStart, topEnd, bottomStart, bottomEnd } 为每个角设置不同的半径。
Shapes.CutCorner(radius)一个带切角的矩形。接受与 RoundedCorner 相同的半径选项。
Shapes.Material.Cookie4Sided材料设计的四边饼干形状。
Shapes.Material.Cookie6Sided材料设计的六边饼干形状。
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.

参数类型描述
tagstring测试 ID。
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.

参数类型描述
params.contentDescriptionstring当内容无法很好地被朗读时,TalkBack 会为该元素朗读此内容。
params.contentTypestring自动填充提示,例如 'email' 或 'password'。
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!