修饰符

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

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

变形

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

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

Types