Expo 小组件

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

重要 此库在 Expo Go 应用中不可用——请使用开发构建来试用它。

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 配置中进行配置

如果你的项目中使用了配置插件（Continuous Native Generation (CNG)），你可以使用 expo-widgets 内置的配置插件进行配置。该插件允许你配置一些无法在运行时设置、且需要重新构建新的应用二进制文件才能生效的属性。

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-widgets",
        {
          "widgets": [
            {
              "name": "MyWidget",
              "displayName": "My Widget",
              "description": "一个示例主屏幕小组件",
              "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": "状态",
              "description": "一目了然地显示当前状态",
              "contentMarginsDisabled": true,
              "supportedFamilies": ["systemSmall", "systemMedium"]
            },
            {
              "name": "DetailWidget",
              "displayName": "详情",
              "description": "显示详细信息",
              "supportedFamilies": ["systemMedium", "systemLarge"]
            },
            {
              "name": "LockScreenWidget",
              "displayName": "快速查看",
              "description": "在锁屏上查看信息",
              "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 配置中小组件配置里的 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: 'Your delivery is on the way',
      },
      'myapp://deliveries/12345'
    );
    // 存储实例
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Start Delivery Tracking" 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: 'Delivery arriving soon!',
  });
}

结束 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: 'Delivered',
    },
    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