This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

Jetpack Compose 修饰符允许你自定义 UI 组件的布局、外观和行为。修饰符相当于 Compose 中的样式属性——它们控制尺寸、内边距、背景、交互等等。

安装

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

修饰符通过使用带有数组语法的 modifiers prop 应用于组件。你可以组合多个修饰符来创建复杂的样式和行为。修饰符会按照它们在数组中出现的顺序应用，这可能会影响最终结果（例如，先应用 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>;

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)]}>半透明</Button>;

blur(radius)

为组件应用模糊效果。

import { blur } from '@expo/ui/jetpack-compose/modifiers';

<Button modifiers={[blur(4)]}>模糊按钮</Button>;

阴影配方

常见的阴影样式通常是 dropShadow 和 innerShadow 修饰符的组合，而不是单独的 API。由于 modifiers prop 接受一个数组，因此你可以叠加并微调阴影修饰符来构建每种样式。

新野兽派阴影

新野兽派阴影是一种边缘硬朗、无模糊且边框较粗的投影。将 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)]}>已旋转</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>;

combinedClickable(handlers, options?)

使组件同时响应短按和长按手势。封装了 Compose 的 Modifier.combinedClickable。适用于在长按时打开 DropdownMenu，同时在同一视图上保留单独的短按操作。

import { combinedClickable } from '@expo/ui/jetpack-compose/modifiers';

<Text
  modifiers={[
    combinedClickable({
      onClick: () => console.log('Tapped'),
      onLongClick: () => setMenuExpanded(true),
    }),
  ]}>
  长按我
</Text>;

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')]}>Submit</Button>;

API

import { paddingAll, padding, size, fillMaxWidth, background, clickable, clip, Shapes } from '@expo/ui/jetpack-compose/modifiers';

Constants

clip(Shapes.Circle)
clip(Shapes.RoundedCorner(16))
clip(Shapes.RoundedCorner({ topStart: 8, bottomEnd: 16 }))
clip(Shapes.Material.Heart)

Methods

Event subscriptions

Interfaces

Types