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

图标

用于显示图标的 Jetpack Compose 图标组件。

Android

Included in Expo Go

GitHub

npm

更新日志

有关跨平台用法，请参阅通用的 Icon — 它会针对不同平台渲染相应的原生组件。

用于在 Jetpack Compose 中渲染 Material Symbol XML 矢量 drawable 的图标组件。推荐的来源是 @expo/material-symbols — 它将 Google 的 Material Symbols 作为独立的资源子路径提供，因此 Metro 只会打包你实际导入的图标。对于其他样式（rounded、sharp、filled）或自定义轴，包的 CLI 会直接将任意变体下载到你的项目中。

安装

Terminal

- npx expo install @expo/ui

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

可选地，安装 @expo/material-symbols 以使用内置图标。若要使用不同样式或自定义轴，请参阅自定义样式 — 无需安装。

Terminal

- npx expo install @expo/material-symbols

用法

基本图标

直接从 @expo/material-symbols 的各自子路径导入任意图标 — 每个图标都会解析为一个可由 Icon 原生渲染的 Metro 资源。对于你添加到项目中的本地 XML 文件，请改用 require()（见下方的自定义样式）。

BasicIcon.tsx

import { Host, Icon } from '@expo/ui/jetpack-compose';
import Home from '@expo/material-symbols/home.xml';

export default function BasicIcon() {
  return (
    <Host matchContents>
      <Icon source={Home} contentDescription="主页" />
    </Host>
  );
}

带有色调的图标

使用 tint 属性为图标应用颜色覆盖层。

TintedIcon.tsx

import { Host, Icon } from '@expo/ui/jetpack-compose';
import Favorite from '@expo/material-symbols/favorite.xml';

export default function TintedIcon() {
  return (
    <Host matchContents>
      <Icon source={Favorite} tint="#6200ee" contentDescription="收藏" />
    </Host>
  );
}

带有尺寸的图标

使用 size 属性以 dp 指定自定义尺寸。

SizedIcon.tsx

import { Host, Icon } from '@expo/ui/jetpack-compose';
import Settings from '@expo/material-symbols/settings.xml';

export default function SizedIcon() {
  return (
    <Host matchContents>
      <Icon source={Settings} size={48} contentDescription="设置" />
    </Host>
  );
}

通过 `@expo/material-symbols` CLI 自定义样式

@expo/material-symbols 随附带默认轴的 outlined 样式。当你需要不同样式（rounded、sharp）、filled 变体，或自定义 weight、grade 或 optical size 时，请使用其 CLI 直接从 Google Fonts 获取特定 drawable 到你的项目中。

Terminal

# 按名称下载图标（默认：outlined、weight 400、24px）

- npx @expo/material-symbols star home

# Rounded 样式

- npx @expo/material-symbols --style rounded star home

# Sharp + filled

- npx @expo/material-symbols --style sharp --fill favorite

# 粘贴 fonts.google.com/icons 中的 URL 以保留你在那里选择的轴

-

npx @expo/material-symbols "https://fonts.google.com/icons?selected=Material+Symbols+Outlined:check_box:FILL@1;wght@300;GRAD@0;opsz@24"

选项	描述	默认值
`-o, --output <dir>`	输出目录	`./assets`
`-s, --style <style>`	图标样式：`outlined`、`rounded`、`sharp`	`outlined`
`-f, --fill`	使用 filled 变体
`-w, --weight <wght>`	Weight：`100`–`700`	`400`
`-g, --grade <grad>`	Grade：`-25`、`0`、`200`	`0`
`--opsz <size>`	Optical size：`20`、`24`、`40`、`48`	`24`

CLI 会将可直接使用的 XML 矢量 drawable 写入你的项目。使用 require() 加载它们并传递给 Icon。

CustomIcon.tsx

import { Host, Icon } from '@expo/ui/jetpack-compose';

export default function CustomIcon() {
  return (
    <Host matchContents>
      <Icon source={require('./assets/star-rounded.xml')} size={32} contentDescription="星标" />
    </Host>
  );
}

API

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

Component

`Icon`

Android

Type: React.Element<IconProps>

Displays an icon from an XML vector drawable or other image source.

The Icon component renders vector graphics and images with support for tinting, sizing, and accessibility features. On Android, it natively supports XML vector drawables loaded via Metro bundler using require().

Example

Basic usage:

import { Icon } from 'expo-ui';

<Icon source={require('./assets/home.xml')} />

Example

With styling:

<Icon
  source={require('./assets/settings.xml')}
  size={24}
  tint="#007AFF"
  contentDescription="Settings icon"
/>

Example

With modifiers:

<Icon
  source={require('./assets/star.xml')}
  size={32}
  modifiers={[
    padding(8),
    background('lightgray')
  ]}
/>

IconProps

`contentDescription`

Android

Optional • Type: string

Accessibility label for the icon. Used by screen readers to describe the icon to users.

Example

<Icon
  source={require('./assets/settings.xml')}
  contentDescription="Settings icon"
/>

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component. Allows you to apply layout and styling modifiers to the icon.

Example

<Icon
  source={require('./assets/icon.xml')}
  modifiers={[
    padding(8),
    background('lightgray')
  ]}
/>

`size`

Android

Optional • Type: number

The size of the icon in density-independent pixels (dp). If not specified, the icon will use its intrinsic size.

Example

<Icon source={require('./assets/settings.xml')} size={24} />

`source`

Android

Type: ImageSourcePropType

The source of the icon. Can be a URI string or the result of require(). On Android, supports XML vector drawables loaded via Metro bundler.

Example

<Icon source={require('./assets/home.xml')} />
<Icon source={{ uri: 'file:///path/to/icon.xml' }} />

`tint`

Android

Optional • Literal type: union

The tint color to apply to the icon. Accepts hex strings, named colors, or RGB arrays.

When omitted, the icon inherits the color from the surrounding LocalContentColor (e.g. the toolbar/FAB content color).
When set to null, no tint is applied — the icon is drawn with its original colors (Color.Unspecified). Use this for multicolored icons.

Example

<Icon source={require('./assets/star.xml')} tint="#007AFF" />
<Icon source={require('./assets/star.xml')} tint="blue" />
<Icon source={require('./assets/multicolor.xml')} tint={null} />

Acceptable values are: ColorValue | null

图标

安装

用法

基本图标

带有色调的图标

带有尺寸的图标

通过 @expo/material-symbols CLI 自定义样式

API

Component

Icon

contentDescription

modifiers

size

source

tint

通过 `@expo/material-symbols` CLI 自定义样式

`Icon`

`contentDescription`

`modifiers`

`size`

`source`

`tint`