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

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

填充

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

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

暗影秘诀

🌐 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 { 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>;

应用接口

🌐 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