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

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

重要 此库当前处于 alpha 阶段，可能会发生破坏性变更。它在 Expo Go 应用中不可用，请使用 development builds 进行试用。

expo-widgets 使您能够使用 Expo UI 组件创建 iOS 主屏幕小组件和 Live Activities，而无需编写原生代码。它提供了一个简单的 API，用于创建和更新小组件时间线，以及启动和管理 Live Activities。布局可以使用 expo/ui 组件和修饰器构建。

安装

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

在 app config 中配置

如果您的项目中使用了 config plugins（Continuous Native Generation (CNG)），您可以通过其内置的 config plugin 来配置 expo-widgets。该插件允许您配置各种无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-widgets",
        {
          "widgets": [
            {
              "name": "MyWidget",
              "displayName": "My Widget",
              "description": "A sample home screen widget",
              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"]
            }
          ]
        }
      ]
    ]
  }
}

Configurable properties

包含所有选项的完整示例

{
  "expo": {
    "plugins": [
      [
        "expo-widgets",
        {
          "bundleIdentifier": "com.example.myapp.widgets",
          "groupIdentifier": "group.com.example.myapp",
          "enablePushNotifications": true,
          "widgets": [
            {
              "name": "StatusWidget",
              "displayName": "Status",
              "description": "Shows your current status at a glance",
              "contentMarginsDisabled": true,
              "supportedFamilies": ["systemSmall", "systemMedium"]
            },
            {
              "name": "DetailWidget",
              "displayName": "Details",
              "description": "Shows detailed information",
              "supportedFamilies": ["systemMedium", "systemLarge"]
            },
            {
              "name": "LockScreenWidget",
              "displayName": "Quick View",
              "description": "View info on your Lock Screen",
              "supportedFamilies": ["accessoryCircular", "accessoryRectangular", "accessoryInline"]
            }
          ]
        }
      ]
    ]
  }
}

使用

小组件

前提条件：创建小组件

首先使用 createWidget 函数创建一个 Widget，并传入带有 'widget' 指令标记的小组件组件。该组件会将您的 widget props 作为第一个参数，将 WidgetEnvironment 对象作为第二个参数。

import { Text, VStack } from '@expo/ui/swift-ui';
import { font, foregroundStyle } from '@expo/ui/swift-ui/modifiers';
import { createWidget, type WidgetEnvironment } from 'expo-widgets';

type MyWidgetProps = {
  count: number;
};

const MyWidget = (props: MyWidgetProps, environment: WidgetEnvironment) => {
  'widget';
  return (
    <VStack>
      <Text modifiers={[font({ weight: 'bold', size: 16 }), foregroundStyle('#000000')]}>
        计数：{props.count}
      </Text>
      <Text>所属尺寸：{environment.widgetFamily}</Text>
    </VStack>
  );
};

export default createWidget('MyWidget', MyWidget);

小组件名称（'MyWidget'）必须与 app config 中小组件配置里的 name 字段一致。

基础小组件

更新小组件的一个有效方式是使用 updateSnapshot 方法。这会创建一个仅包含单个条目的小组件时间线，并立即显示。

下面的示例延续自 创建小组件。

import MyWidget from './MyWidget';

// 更新小组件
MyWidget.updateSnapshot({ count: 5 });

时间线小组件

使用 updateTimeline 方法在特定时间安排小组件更新。系统会根据时间线自动更新小组件。

下面的示例延续自 创建小组件。

import MyWidget from './MyWidget';

MyWidget.updateTimeline([
  { date: new Date(), props: { count: 1 } },
  { date: new Date(Date.now() + 3600000), props: { count: 2 } }, // 距现在 1 小时
  { date: new Date(Date.now() + 7200000), props: { count: 3 } }, // 距现在 2 小时
  { date: new Date(Date.now() + 10800000), props: { count: 4 } }, // 距现在 3 小时
]);

响应式小组件

使用 environment 参数使布局适配当前小组件尺寸和渲染上下文。

import { HStack, Text, VStack } from '@expo/ui/swift-ui';
import { createWidget, type WidgetEnvironment } from 'expo-widgets';

type WeatherWidgetProps = {
  temperature: number;
  condition: string;
};

const WeatherWidget = (props: WeatherWidgetProps, environment: WidgetEnvironment) => {
  'widget';
  // 根据尺寸渲染不同布局
  if (environment.widgetFamily === 'systemSmall') {
    return (
      <VStack>
        <Text>{props.temperature}°</Text>
      </VStack>
    );
  }

  if (environment.widgetFamily === 'systemMedium') {
    return (
      <HStack>
        <Text>{props.temperature}°</Text>
        <Text>{props.condition}</Text>
      </HStack>
    );
  }

  // systemLarge 和其他情况
  return (
    <VStack>
      <Text>温度：{props.temperature}°</Text>
      <Text>天气：{props.condition}</Text>
      <Text>更新时间：{environment.date.toLocaleTimeString()}</Text>
    </VStack>
  );
};

const Widget = createWidget('WeatherWidget', WeatherWidget);
export default Widget;

Widget.updateSnapshot({
  temperature: 72,
  condition: 'Sunny',
});

Live Activities

Live Activities 会在受支持的设备上于锁屏和灵动岛中显示实时信息。

前提条件：创建 Live Activity

Live Activity 布局必须先使用 createLiveActivity 创建一次，并标记为 'widget' 指令。该组件会将您的 props 作为第一个参数，将 LiveActivityEnvironment 对象作为第二个参数。

import { Image, Text, VStack } from '@expo/ui/swift-ui';
import { font, foregroundStyle, padding } from '@expo/ui/swift-ui/modifiers';
import { createLiveActivity, type LiveActivityEnvironment } from 'expo-widgets';

type DeliveryActivityProps = {
  etaMinutes: number;
  status: string;
};

const DeliveryActivity = (props: DeliveryActivityProps, environment: LiveActivityEnvironment) => {
  'widget';
  const accentColor = environment.colorScheme === 'dark' ? '#FFFFFF' : '#007AFF';

  return {
    banner: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text modifiers={[font({ weight: 'bold' }), foregroundStyle(accentColor)]}>
          {props.status}
        </Text>
        <Text>预计到达：{props.etaMinutes} 分钟</Text>
      </VStack>
    ),
    compactLeading: <Image systemName="box.truck.fill" color={accentColor} />,
    compactTrailing: <Text>{props.etaMinutes} 分钟</Text>,
    minimal: <Image systemName="box.truck.fill" color={accentColor} />,
    expandedLeading: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Image systemName="box.truck.fill" color={accentColor} />
        <Text modifiers={[font({ size: 12 })]}>配送中</Text>
      </VStack>
    ),
    expandedTrailing: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text modifiers={[font({ weight: 'bold', size: 20 })]}>{props.etaMinutes}</Text>
        <Text modifiers={[font({ size: 12 })]}>分钟</Text>
      </VStack>
    ),
    expandedBottom: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text>司机：John Smith</Text>
        <Text>订单 #12345</Text>
      </VStack>
    ),
  };
};

export default createLiveActivity('DeliveryActivity', DeliveryActivity);

启动 Live Activity

下面的示例延续自 创建 Live Activity。

import { Button, View } from 'react-native';
import DeliveryActivity from './DeliveryActivity';

function App() {
  const startDeliveryTracking = () => {
    // 启动 Live Activity
    const instance = DeliveryActivity.start(
      {
        etaMinutes: 15,
        status: '您的配送正在路上',
      },
      'myapp://deliveries/12345'
    );
    // 存储实例
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="开始配送追踪" onPress={startDeliveryTracking} />
    </View>
  );
}
export default App;

更新 Live Activity

下面的示例延续自 启动 Live Activity。

import { LiveActivity } from 'expo-widgets';

function updateDelivery(instance: LiveActivity<DeliveryActivityProps>) {
  instance.update({
    etaMinutes: 2,
    status: '配送即将送达！',
  });
}

结束 Live Activity

使用 end 来结束 Live Activity。您可以选择关闭策略，按需提供最终内容状态，并传入 contentDate，以便系统忽略过期更新。

import { after, type LiveActivity } from 'expo-widgets';

async function completeDelivery(instance: LiveActivity<DeliveryActivityProps>) {
  await instance.end(
    after(new Date(Date.now() + 15 * 60 * 1000)),
    {
      etaMinutes: 0,
      status: '已送达',
    },
    new Date()
  );
}

您也可以在关闭策略中使用 'default' 或 'immediate' 来替代 after(date)。

用于远程更新的推送令牌

当 enablePushNotifications 为 true 时，使用 addPushToStartTokenListener 接收应用级的 push-to-start 令牌，并使用 instance.getPushToken() 或 instance.addPushTokenListener() 处理特定的 Live Activity 实例。

import { addPushToStartTokenListener } from 'expo-widgets';
import DeliveryActivity from './DeliveryActivity';

const pushToStartSubscription = addPushToStartTokenListener(event => {
  console.log('Push-to-start token:', event.activityPushToStartToken);
});

async function startDeliveryTracking() {
  const instance = DeliveryActivity.start({
    etaMinutes: 15,
    status: 'Your delivery is on the way',
  });

  const pushToken = await instance.getPushToken();
  console.log('Per-activity token:', pushToken);

  const subscription = instance.addPushTokenListener(event => {
    console.log('Updated push token:', event.activityId, event.pushToken);
  });

  // 稍后，当您不再需要更新时：
  subscription.remove();
}

// 稍后，当您不再需要更新时：
pushToStartSubscription.remove();

API

import { createWidget, createLiveActivity } from 'expo-widgets';

Classes

Methods

Event Subscriptions

Types