Expo 小组件

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 主屏幕小组件和实时活动。它提供了一个简单的 API，用于创建和更新小组件时间线，以及启动和管理实时活动。布局可以使用 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)），你可以使用 expo-widgets 内置的 config plugin 进行配置。该插件允许你配置一些无法在运行时设置的属性，这些属性需要重新构建新的应用二进制文件后才会生效。

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-widgets",
        {
          "widgets": [
            {
              "name": "MyWidget",
              "displayName": "我的小组件",
              "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 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: '晴朗',
});

实时活动

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

前提：创建实时活动

实时活动布局必须先使用 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);

启动实时活动

下面的示例延续自 创建实时活动。

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

function App() {
  const startDeliveryTracking = () => {
    // 启动实时活动
    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;

更新实时活动

下面的示例延续自 启动实时活动。

import { LiveActivity } from 'expo-widgets';

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

结束实时活动

使用 end 来结束实时活动。你可以选择取消显示策略，可选地提供最终内容状态，并传入一个 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() 处理特定实时活动实例。

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: '你的配送正在路上',
  });

  const pushToken = await instance.getPushToken();
  console.log('每个活动的令牌：', pushToken);

  const subscription = instance.addPushTokenListener(event => {
    console.log('更新后的推送令牌：', event.activityId, event.pushToken);
  });

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

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

API

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

Classes

Methods

Event Subscriptions

Types