Expo 小部件

重要 该库目前处于 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",
              "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 组件。

🌐 Start by creating a Widget using the createWidget function and pass the widget component marked with the 'widget' directive.

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

type MyWidgetProps = {
  count: number;
};

const MyWidget = (props: WidgetBase<MyWidgetProps>) => {
  'widget';
  return (
    <VStack>
      <Text modifiers={[font({ weight: 'bold', size: 16 }), foregroundStyle('#000000')]}>
        Count: {props.count}
      </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

Widget 组件接收一个 family 属性，用于指示正在渲染的尺寸。使用它来针对不同的 Widget 尺寸调整布局。

🌐 Widget component receives a family prop indicating which size is being rendered. Use this to adapt layout for different widget sizes.

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

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

const WeatherWidget = (props: WidgetBase<WeatherWidgetProps>) => {
  'widget';
  // Render different layouts based on size
  if (props.family === 'systemSmall') {
    return (
      <VStack>
        <Text>{props.temperature}°</Text>
      </VStack>
    );
  }

  if (props.family === '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: {props.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

Live Activity 布局必须使用 createLiveActivity 创建一次，并使用 'widget' 指令标记。

🌐 Live Activity layouts must be created once using createLiveActivity and marked with the 'widget' directive.

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

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

const DeliveryActivity = (props: DeliveryActivityProps) => {
  'widget';
  return {
    banner: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Text modifiers={[font({ weight: 'bold' }), foregroundStyle('#007AFF')]}>
          {props.status}
        </Text>
        <Text>Estimated arrival: {props.etaMinutes} minutes</Text>
      </VStack>
    ),
    compactLeading: <Image systemName="box.truck.fill" color="#007AFF" />,
    compactTrailing: <Text>{props.etaMinutes} min</Text>,
    minimal: <Image systemName="box.truck.fill" color="#007AFF" />,
    expandedLeading: (
      <VStack modifiers={[padding({ all: 12 })]}>
        <Image systemName="box.truck.fill" color="#007AFF" />
        <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 { Image, Text, VStack } from '@expo/ui/swift-ui';
import { font, foregroundStyle, padding } from '@expo/ui/swift-ui/modifiers';
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',
    });
    // 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!',
  });
}

应用接口

🌐 API

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

Classes

Methods

Event Subscriptions

Types