Expo 小部件

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

重要 该库目前处于 alpha 阶段，可能会有重大更改。它在 Expo Go 应用中不可用，请使用 开发版本 进行尝试。

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

安装

🌐 Installation

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

应用配置中的配置

🌐 Configuration in app config

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

🌐 You can configure expo-widgets using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

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

包含所有选项的完整示例

🌐 Full example with all options

{
  "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"]
            }
          ]
        }
      ]
    ]
  }
}

用法

🌐 Usage

小部件

🌐 Widgets

先决条件：创建小部件

🌐 Prerequisite: Creating widget

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

🌐 Start by creating a Widget using the createWidget function and pass the widget component marked with the 'widget' directive. The component receives your widget props as the first argument and a WidgetEnvironment object as the second.

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')]}>
        Count: {props.count}
      </Text>
      <Text>Family: {environment.widgetFamily}</Text>
    </VStack>
  );
};

export default createWidget('MyWidget', MyWidget);

小部件名称（'MyWidget'）必须与你的小部件配置中 应用配置 的 name 字段相匹配。

🌐 The widget name ('MyWidget') must match the name field in your widget configuration in the app config.

基础小部件

🌐 Basic widget

更新小部件的有效方法是使用 updateSnapshot 方法。这会创建一个只有一个条目的小部件时间线，该条目会立即显示。

🌐 An effective way to update a widget is to use the updateSnapshot method. This creates a widget timeline with a single entry that displays immediately.

下面的例子接着创建小部件进行。

🌐 The example below continues from Creating widget.

import MyWidget from './MyWidget';

// Update the widget
MyWidget.updateSnapshot({ count: 5 });

时间轴小部件

🌐 Timeline widget

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

🌐 Use updateTimeline method to schedule widget updates at specific time. System will automatically update the widget based on the timeline.

下面的例子接着创建小部件进行。

🌐 The example below continues from Creating widget.

import MyWidget from './MyWidget';

MyWidget.updateTimeline([
  { date: new Date(), props: { count: 1 } },
  { date: new Date(Date.now() + 3600000), props: { count: 2 } }, // 1 hour from now
  { date: new Date(Date.now() + 7200000), props: { count: 3 } }, // 2 hours from now
  { date: new Date(Date.now() + 10800000), props: { count: 4 } }, // 3 hours from now
]);

响应式小部件

🌐 Responsive widget

使用 environment 参数以将布局适应当前小部件的大小和渲染上下文。

🌐 Use the environment argument to adapt the layout to the current widget size and rendering context.

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';
  // Render different layouts based on size
  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 and others
  return (
    <VStack>
      <Text>Temperature: {props.temperature}°</Text>
      <Text>Condition: {props.condition}</Text>
      <Text>Updated: {environment.date.toLocaleTimeString()}</Text>
    </VStack>
  );
};

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

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

实时活动

🌐 Live Activities

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

🌐 Live Activities display real-time information on the Lock Screen and in the Dynamic Island on supported devices.

先决条件：创建实时活动

🌐 Prerequisite: Creating Live Activity

实时活动布局必须使用 createLiveActivity 创建一次，并使用 'widget' 指令标记。组件将你的 props 作为第一个参数，并将 LiveActivityEnvironment 对象作为第二个参数接收。

🌐 Live Activity layouts must be created once using createLiveActivity and marked with the 'widget' directive. The component receives your props as the first argument and a LiveActivityEnvironment object as the second.

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>Estimated arrival: {props.etaMinutes} minutes</Text>
      </VStack>
    ),
    compactLeading: <Image systemName="box.truck.fill" color={accentColor} />,
    compactTrailing: <Text>{props.etaMinutes} min</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 })]}>Delivering</Text>
      </VStack>
    ),
    expandedTrailing: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text modifiers={[font({ weight: 'bold', size: 20 })]}>{props.etaMinutes}</Text>
        <Text modifiers={[font({ size: 12 })]}>minutes</Text>
      </VStack>
    ),
    expandedBottom: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text>Driver: John Smith</Text>
        <Text>Order #12345</Text>
      </VStack>
    ),
  };
};

export default createLiveActivity('DeliveryActivity', DeliveryActivity);

开始实时活动

🌐 Starting a Live Activity

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

🌐 The example below continues from Creating Live Activity.

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

function App() {
  const startDeliveryTracking = () => {
    // Start the Live Activity
    const instance = DeliveryActivity.start(
      {
        etaMinutes: 15,
        status: 'Your delivery is on the way',
      },
      'myapp://deliveries/12345'
    );
    // Store instance
  };

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

更新实时活动

🌐 Updating a Live Activity

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

🌐 The example below continues from Starting a Live Activity.

import { LiveActivity } from 'expo-widgets';

function updateDelivery(instance: LiveActivity<DeliveryActivityProps>) {
  instance.update({
    etaMinutes: 2,
    status: 'Delivery arriving soon!',
  });
}

结束直播活动

🌐 Ending a Live Activity

使用 end 来完成实时活动。你可以选择结束策略，可选地提供最终内容状态，并传递一个 contentDate，以便系统可以忽略过时的更新。

🌐 Use end to finish a Live Activity. You can choose the dismissal policy, optionally provide a final content state, and pass a contentDate so the system can ignore stale updates.

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) 作为退出策略。

🌐 You can also pass 'default' or 'immediate' instead of after(date) for the dismissal policy.

推送令牌以进行远程更新

🌐 Push tokens for remote updates

当 enablePushNotifications 为 true 时，使用 addPushToStartTokenListener 来接收应用范围的推送启动令牌，并使用 instance.getPushToken() 或 instance.addPushTokenListener() 来处理特定的实时活动实例。

🌐 When enablePushNotifications is true, use addPushToStartTokenListener to receive the app-wide push-to-start token and instance.getPushToken() or instance.addPushTokenListener() to work with a specific Live Activity instance.

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

  // Later, when you no longer need updates:
  subscription.remove();
}

// Later, when you no longer need updates:
pushToStartSubscription.remove();

应用接口

🌐 API

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

Classes

Methods

Event Subscriptions

Types