react-native-live-widgets 1.2.1 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -0
- package/README.md +89 -49
- package/android/src/main/AndroidManifest.xml +12 -0
- package/android/src/main/assets/fonts/MaterialIcons-Regular.ttf +0 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +61 -1
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +153 -17
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +1 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +86 -13
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +647 -104
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +3 -1
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
- package/app.plugin.js +36 -0
- package/assets/MaterialIcons.json +2236 -0
- package/cli/codegen.js +789 -0
- package/cli/setup.js +323 -63
- package/docs/EXPO-GUIDE-EN.md +21 -3
- package/docs/EXPO-GUIDE-VI.md +21 -3
- package/docs/GUIDE-EN.md +203 -21
- package/docs/GUIDE-VI.md +207 -22
- package/docs/index.html +1328 -211
- package/docs/llms-full.txt +15 -0
- package/docs/llms.txt +16 -7
- package/ios/Bridge/LiveActivityModule.swift +333 -44
- package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
- package/ios/Models/DynamicLayoutModels.swift +114 -4
- package/ios/Renderer/DynamicNodeView.swift +15 -6
- package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
- package/ios/Widgets/DynamicControlWidget.swift +63 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +99 -26
- package/ios/Widgets/DynamicLiveActivityWidget.swift +25 -4
- package/lib/builder.d.ts +50 -7
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +326 -18
- package/lib/builder.js.map +1 -1
- package/lib/hooks.d.ts +13 -9
- package/lib/hooks.d.ts.map +1 -1
- package/lib/hooks.js +70 -12
- package/lib/hooks.js.map +1 -1
- package/lib/index.d.ts +80 -7
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +303 -59
- package/lib/index.js.map +1 -1
- package/lib/ir.d.ts.map +1 -1
- package/lib/ir.js +9 -2
- package/lib/ir.js.map +1 -1
- package/lib/jsx.d.ts +11 -7
- package/lib/jsx.d.ts.map +1 -1
- package/lib/jsx.js +50 -13
- package/lib/jsx.js.map +1 -1
- package/lib/material-icons.generated.d.ts +8 -0
- package/lib/material-icons.generated.d.ts.map +1 -0
- package/lib/material-icons.generated.js +9 -0
- package/lib/material-icons.generated.js.map +1 -0
- package/lib/preview.d.ts +11 -4
- package/lib/preview.d.ts.map +1 -1
- package/lib/preview.js +150 -82
- package/lib/preview.js.map +1 -1
- package/lib/sf-symbols.generated.d.ts +8 -0
- package/lib/sf-symbols.generated.d.ts.map +1 -0
- package/lib/sf-symbols.generated.js +9 -0
- package/lib/sf-symbols.generated.js.map +1 -0
- package/lib/types.d.ts +302 -18
- package/lib/types.d.ts.map +1 -1
- package/package.json +6 -2
- package/scripts/build.js +98 -0
- package/scripts/generate-material-icons.js +93 -0
- package/scripts/generate-sf-symbols.js +95 -0
- package/scripts/release.js +115 -0
- package/scripts/test-ir-semantic.js +314 -0
- package/src/builder.ts +382 -24
- package/src/hooks.ts +88 -12
- package/src/index.ts +319 -56
- package/src/ir.ts +8 -2
- package/src/jsx.tsx +69 -21
- package/src/material-icons.generated.ts +3844 -0
- package/src/preview.tsx +235 -81
- package/src/sf-symbols.generated.ts +9533 -0
- package/src/types.ts +348 -18
package/docs/EXPO-GUIDE-VI.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# HƯỚNG DẪN TÍCH HỢP VÀ SỬ DỤNG EXPO VỚI REACT-NATIVE-LIVE-WIDGETS 🚀
|
|
2
2
|
|
|
3
|
-
> 🌐 **Language:** **Tiếng Việt** | [English Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [📖 Bare RN Guide (GUIDE-VI.md)](./GUIDE-VI.md) • [⚡ Kho mã nguồn mẫu Expo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)
|
|
3
|
+
> 🌐 **Language:** **Tiếng Việt** | [English Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [📖 Bare RN Guide (GUIDE-VI.md)](./GUIDE-VI.md) • [⚡ Kho mã nguồn mẫu Expo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo) • [🌐 Web Docs (Live Simulator)](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
4
4
|
|
|
5
5
|
Tài liệu này hướng dẫn chi tiết cách tích hợp **`react-native-live-widgets`** vào ứng dụng **Expo (SDK 50, 51, 52, 58+)**, từ cấu hình Expo Config Plugin, thiết lập iOS WidgetKit/ActivityKit tự động, chạy trên Local Simulator bằng Expo Dev Client cho đến việc đóng gói phát hành qua **EAS Build**.
|
|
6
6
|
|
|
@@ -86,7 +86,25 @@ npx expo run:android
|
|
|
86
86
|
|
|
87
87
|
## 3. Cài đặt & Thiết lập Từng bước
|
|
88
88
|
|
|
89
|
-
###
|
|
89
|
+
### Cách nhanh nhất: Tự động hoá 100% bằng 1 câu lệnh
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# 1. Cài đặt package
|
|
93
|
+
npx expo install react-native-live-widgets
|
|
94
|
+
|
|
95
|
+
# 2. Khởi tạo tự động (Tự chèn Config Plugin vào app.json, tạo widgets.config.ts, sync icons & Swift)
|
|
96
|
+
npx react-native-live-widgets init
|
|
97
|
+
|
|
98
|
+
# 3. Chạy ứng dụng trên máy ảo / thiết bị thật
|
|
99
|
+
npx expo run:ios
|
|
100
|
+
# hoặc: npx expo run:android
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
### Quy trình thủ công (Nếu bạn muốn tự kiểm soát cấu hình)
|
|
106
|
+
|
|
107
|
+
#### Bước 1: Cài đặt package
|
|
90
108
|
Tại thư mục gốc của dự án Expo:
|
|
91
109
|
```bash
|
|
92
110
|
npx expo install react-native-live-widgets
|
|
@@ -94,7 +112,7 @@ npx expo install react-native-live-widgets
|
|
|
94
112
|
|
|
95
113
|
---
|
|
96
114
|
|
|
97
|
-
|
|
115
|
+
#### Bước 2: Cấu hình `app.json` (Expo Config Plugin)
|
|
98
116
|
Mở file `app.json` và bổ sung plugin `react-native-live-widgets`:
|
|
99
117
|
|
|
100
118
|
```json
|
package/docs/GUIDE-EN.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# REACT-NATIVE-LIVE-WIDGETS — COMPLETE SETUP & DEVELOPER GUIDE 🚀
|
|
2
2
|
|
|
3
|
-
> 🌐 **Language:** [Tiếng Việt (GUIDE-VI.md)](./GUIDE-VI.md) | **English** • [⚡ Dedicated Expo Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)
|
|
3
|
+
> 🌐 **Language:** [Tiếng Việt (GUIDE-VI.md)](./GUIDE-VI.md) | **English** • [⚡ Dedicated Expo Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) • [🌐 Web Docs & Live Simulator](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
4
4
|
|
|
5
5
|
Comprehensive guide covering installation, native setup (iOS & Android), and building 100% JavaScript/TypeScript declarative layouts for **Live Activities (Dynamic Island / Lock Screen / Android Live Updates)** and **Interactive Multi-Page Home Screen Widgets**.
|
|
6
6
|
|
|
@@ -37,8 +37,10 @@ Comprehensive guide covering installation, native setup (iOS & Android), and bui
|
|
|
37
37
|
8. [Background API Auto-Sync When App Is Killed (`Widget.setRemoteConfig`)](#8-background-api-auto-sync-when-app-is-killed-widgetsetremoteconfig)
|
|
38
38
|
9. [Managing All 3 Push Token Types (APNs & FCM)](#9-managing-all-3-push-token-types-apns--fcm)
|
|
39
39
|
10. [State Machine & Timed Phases (`phases`)](#10-state-machine--timed-phases-phases)
|
|
40
|
-
11. [Server Push Payload Structure (APNs & FCM)](#
|
|
41
|
-
12. [Troubleshooting](#
|
|
40
|
+
11. [Server Push Payload Structure (APNs & FCM)](#10-server-push-payload-structure-apns--fcm)
|
|
41
|
+
12. [Troubleshooting](#11-troubleshooting)
|
|
42
|
+
13. [Advanced Styling Modifiers, UI IR, Exact Hit Layer & Platform Matrix (v1.2.1)](#12-advanced-styling-modifiers--platform-capability-matrix)
|
|
43
|
+
14. [TypeScript-Driven Swift Codegen & Automated i18n Sync (`widgets.config.ts`)](#14-typescript-driven-swift-codegen--automated-i18n-sync-widgetsconfigts)
|
|
42
44
|
|
|
43
45
|
---
|
|
44
46
|
|
|
@@ -76,32 +78,47 @@ npx expo run:ios # or npx expo run:android
|
|
|
76
78
|
|
|
77
79
|
## 3. Installation & Project Setup
|
|
78
80
|
|
|
79
|
-
###
|
|
80
|
-
|
|
81
|
-
|
|
81
|
+
### 📋 CLI Command Cheat Sheet
|
|
82
|
+
|
|
83
|
+
| Command | Purpose | When to use |
|
|
84
|
+
| :--- | :--- | :--- |
|
|
85
|
+
| `npx react-native-live-widgets init` | **All-in-One Automated Setup**: Configures `app.json` (Expo), Xcode Extension target, Entitlements, App Groups, Podfile, `pod install`, Android permissions, default `widgets.config.ts`, SF Symbols/Material Icons sync, and Swift bundle codegen. | First time setting up the library in your project |
|
|
86
|
+
| `npx react-native-live-widgets codegen` | **Sync & Re-generate**: Re-reads `widgets.config.ts` and syncs `LiveWidgetsBundle.swift`, iOS `Localizable.xcstrings`, Android `strings.xml`, and type definitions. | Whenever you edit `widgets.config.ts` or add new widgets/locales |
|
|
87
|
+
| `npx react-native-live-widgets init --group <name>` | **Custom App Group**: Explicitly specify your App Group identifier (e.g. `group.com.mycompany.app`). | If you prefer a custom group instead of auto-detection |
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
### Option A: For Expo Projects (Managed / CNG)
|
|
82
92
|
|
|
83
93
|
```bash
|
|
84
94
|
# 1. Install package
|
|
85
95
|
npx expo install react-native-live-widgets
|
|
86
96
|
|
|
87
|
-
# 2.
|
|
88
|
-
npx
|
|
97
|
+
# 2. Automated one-command setup (updates app.json, creates widgets.config.ts, syncs icons & bundle)
|
|
98
|
+
npx react-native-live-widgets init
|
|
89
99
|
|
|
90
|
-
# 3.
|
|
91
|
-
npx
|
|
100
|
+
# 3. Launch on Simulator / Emulator
|
|
101
|
+
npx expo run:ios
|
|
102
|
+
# or: npx expo run:android
|
|
92
103
|
```
|
|
93
104
|
|
|
105
|
+
> 👉 **See the dedicated step-by-step guide: [Expo Integration Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)**
|
|
106
|
+
|
|
94
107
|
---
|
|
95
108
|
|
|
96
|
-
###
|
|
97
|
-
|
|
109
|
+
### Option B: For Bare React Native CLI
|
|
110
|
+
|
|
98
111
|
```bash
|
|
112
|
+
# 1. Install package
|
|
99
113
|
npm install react-native-live-widgets
|
|
100
|
-
# or
|
|
101
|
-
|
|
114
|
+
# or: yarn add react-native-live-widgets
|
|
115
|
+
|
|
116
|
+
# 2. Automated one-command setup (links Xcode target, Podfile, pod install, Android permissions, widgets.config.ts, codegen)
|
|
117
|
+
npx react-native-live-widgets init
|
|
102
118
|
|
|
103
|
-
#
|
|
104
|
-
npx react-native-
|
|
119
|
+
# 3. Launch on Simulator / Emulator
|
|
120
|
+
npx react-native run-ios
|
|
121
|
+
# or: npx react-native run-android
|
|
105
122
|
```
|
|
106
123
|
|
|
107
124
|
---
|
|
@@ -536,15 +553,38 @@ UI.Image({
|
|
|
536
553
|
cornerRadius: 8,
|
|
537
554
|
})
|
|
538
555
|
|
|
539
|
-
// 3. System
|
|
556
|
+
// 3. Cross-Platform System Icons (Apple SF Symbols + Google Material Icons)
|
|
557
|
+
// Option A: Automatically mapped on both platforms
|
|
540
558
|
UI.Image({
|
|
541
|
-
systemName: '
|
|
542
|
-
tintColor: '#
|
|
543
|
-
width:
|
|
544
|
-
height:
|
|
559
|
+
systemName: 'bolt',
|
|
560
|
+
tintColor: '#10B981',
|
|
561
|
+
width: 20,
|
|
562
|
+
height: 20,
|
|
563
|
+
})
|
|
564
|
+
|
|
565
|
+
// Option B: Explicitly specify platform-dedicated icons (with 9,500+ SF Symbols & 3,800+ Material Icons Auto-Complete types)
|
|
566
|
+
UI.Image({
|
|
567
|
+
systemNameIos: 'bolt.horizontal.fill', // 9,500+ Apple SF Symbols
|
|
568
|
+
systemNameAndroid: 'bolt', // 3,800+ Google Material Icons (supports snake_case and kebab-case)
|
|
569
|
+
tintColor: '#10B981',
|
|
570
|
+
width: 24,
|
|
571
|
+
height: 24,
|
|
545
572
|
})
|
|
573
|
+
|
|
574
|
+
// Or using React JSX Component syntax:
|
|
575
|
+
<Image
|
|
576
|
+
systemNameIos="person.crop.circle.badge.checkmark"
|
|
577
|
+
systemNameAndroid="verified_user"
|
|
578
|
+
tintColor="#10B981"
|
|
579
|
+
width={24}
|
|
580
|
+
height={24}
|
|
581
|
+
/>
|
|
546
582
|
```
|
|
547
583
|
|
|
584
|
+
> 💡 **Official Icon Catalogs & Galleriy Links:**
|
|
585
|
+
> - 🍏 **Apple SF Symbols (9,500+ Icons)**: Browse and preview symbols at [Apple SF Symbols Official Website](https://developer.apple.com/sf-symbols/). Fully typed via `KnownSFSymbol` auto-complete.
|
|
586
|
+
> - 🤖 **Google Material Icons (3,800+ Icons)**: Browse icon names at [Google Fonts Icons / Material Symbols](https://fonts.google.com/icons). Fully typed via `KnownMaterialIcon`, supporting both `snake_case` (e.g. `battery_charging_full`) and `kebab-case` (`battery-charging-full`).
|
|
587
|
+
|
|
548
588
|
### `UI.Button` (Interactive Widget Buttons)
|
|
549
589
|
Lets users interact directly on the Widget surface (via iOS 17+ `AppIntents` and Android `PendingIntent` hit zones) **without opening the app**:
|
|
550
590
|
```typescript
|
|
@@ -1185,6 +1225,148 @@ Version **v1.2.1** addresses critical real-world interaction challenges on physi
|
|
|
1185
1225
|
|
|
1186
1226
|
---
|
|
1187
1227
|
|
|
1228
|
+
### 12.8. 📱 Extended Widget Families (`extraLarge`, `standBy`, `ControlWidget`) & Complete Live Activity Lifecycle
|
|
1229
|
+
|
|
1230
|
+
#### 1. Extended Widget Families
|
|
1231
|
+
Beyond `small`, `medium`, `large`, and Lock Screen (`accessoryRectangular`, `accessoryCircular`, `accessoryInline`) layouts:
|
|
1232
|
+
- **`extraLarge?: LayoutNode`**: Targets iPadOS (`systemExtraLarge`) and Android tablets (`widgetHeightDp >= 280dp`). Supported in `<WidgetPreview size="extraLarge">`.
|
|
1233
|
+
- **`standBy?: LayoutNode`**: Automatically activated in iOS 17+ StandBy Mode (`family == .systemSmall && !showsWidgetContainerBackground`), alongside `.applyStandByMargins()` and `widgetAccentable` support on `Text`, `Progress`, `Gauge`, and `Image`. Supported in `<WidgetPreview size="standBy">`.
|
|
1234
|
+
- **iOS 18+ Control Widgets & Android Quick Settings Tile (`ControlWidget` / `Widget.setControl`)**: Configure iOS 18 Control Center, Lock Screen controls, and Action Button widgets natively via `ios/Widgets/DynamicControlWidget.swift` (`DynamicControlWidget` & `DynamicControlToggleWidget`) and Android Quick Settings Tiles via `DynamicQuickSettingsTileService.kt`, connected directly to `DynamicWidgetStateStore` and `useWidgetAction`:
|
|
1235
|
+
```typescript
|
|
1236
|
+
import { ControlWidget, UI, WidgetPreview } from 'react-native-live-widgets';
|
|
1237
|
+
|
|
1238
|
+
const shiftControl = ControlWidget.toggle({
|
|
1239
|
+
title: 'Work Shift',
|
|
1240
|
+
subtitle: 'Tap to clock in',
|
|
1241
|
+
checkedTitle: 'On Shift',
|
|
1242
|
+
checkedSubtitle: 'Tap to clock out',
|
|
1243
|
+
systemName: 'clock.badge.checkmark.fill',
|
|
1244
|
+
checked: true,
|
|
1245
|
+
actionId: 'toggle:attendance',
|
|
1246
|
+
});
|
|
1247
|
+
|
|
1248
|
+
await ControlWidget.set('toggle', shiftControl);
|
|
1249
|
+
// Also supports UI.ControlButton({ ... }) and Widget.setControl('main', ...)
|
|
1250
|
+
// Preview in-app: <WidgetPreview size="control" controlConfig={shiftControl} />
|
|
1251
|
+
```
|
|
1252
|
+
|
|
1253
|
+
#### 2. Complete Live Activity Lifecycle API
|
|
1254
|
+
- **Multi-Activity Management**: `LiveActivity.getActiveActivities()`, `LiveActivity.get(activityId)`, `LiveActivity.isActive(activityId)`, and `LiveActivity.endAll()` return user-assigned `activityId`, `systemActivityId`, state flags, and tokens.
|
|
1255
|
+
- **Stale State (`staleTimestamp`, `staleLockScreen`, `staleDynamicIsland`)**: Automatically transitions UI to fallback views when stale (`context.isStale` on iOS 16.2+ / timestamp check on Android).
|
|
1256
|
+
- **Relevance Score (`relevanceScore`)**: Prioritizes ordering in Dynamic Island / Lock Screen (`ActivityContent.relevanceScore`) and Android Notification Shade (`setSortKey`).
|
|
1257
|
+
- **Alert Configuration (`alertConfig`)**: Supports `{ title, body, sound }` via iOS 16.2+ `AlertConfiguration` and Android notification alerts on updates.
|
|
1258
|
+
- **Scheduled End & Auto-Expiration (`scheduledEndTimestamp`, `autoEndAfterSeconds`, `expiredLockScreen`, `expiredDismissalPolicy`)**: Automatically updates or dismisses activities on expiration, plus `LiveActivity.cleanupExpired()` and `LiveActivity.onStateChange((ev) => ...)` emitting `'active' | 'started_by_push' | 'stale' | 'expired' | 'ended' | 'dismissed'`.
|
|
1259
|
+
- **Upgraded `useLiveActivity()` Hook**: Exposes `activities`, `lifecycleState`, `isStale`, `refreshActivities`, and `cleanupExpired`.
|
|
1260
|
+
|
|
1261
|
+
---
|
|
1262
|
+
|
|
1263
|
+
### 12.9. 🔄 Background Data Engine 2.0 & Structured Data Binding
|
|
1264
|
+
|
|
1265
|
+
`Widget.setRemoteConfig` and `Widget.createDataBinding<T>()` provide a complete native background data engine on both iOS WidgetKit Extension and Android even after the main app is force-killed:
|
|
1266
|
+
|
|
1267
|
+
| Category | Native Capabilities (iOS SwiftUI + Android) |
|
|
1268
|
+
| :--- | :--- |
|
|
1269
|
+
| **REST & Auth** | `url`, `method` (`GET`/`POST`/`PUT`), JSON `body`, custom `headers`, and **`authRefresh`** (automatically refreshes tokens on HTTP `401` and retries) |
|
|
1270
|
+
| **Network & Cache** | **`cacheTtlSeconds`** to avoid redundant fetches across timeline reloads, **`enableETag`** (`If-None-Match`/`If-Modified-Since` + HTTP `304 Not Modified`), **`timeoutMs`**, and **`maxRetries` + `retryDelayMs`** (Exponential Backoff) |
|
|
1271
|
+
| **Multi-Source & Transform** | **`sources`** to fetch & namespace multiple APIs (`<sourceKey>.<nested.path>`), recursive JSON Flattener (`user.name`, `items.0.title`), declarative **`mapping`**, and **`schema`** validation (`requiredKeys`, `types`, `defaults`) |
|
|
1272
|
+
| **Error State** | System tokens `{{_syncStatus}}` (`ok` / `partial` / `error`), `{{_syncError}}`, `{{_httpStatus}}`, plus **`errorFallback`** `LayoutNode` while preserving valid cached data on failures |
|
|
1273
|
+
| **Structured Data Binding** | `Widget.createDataBinding<T>()` & `UI.bind(path, pipes)` supporting nested paths & Native Pipes (`default`, `divide`, `multiply`, `add`, `round`, `upper`, `lower`, `currency`, `percent`, `if`) |
|
|
1274
|
+
|
|
1275
|
+
```tsx
|
|
1276
|
+
const data = Widget.createDataBinding<{
|
|
1277
|
+
user: { name: string };
|
|
1278
|
+
attendance: { progress: number };
|
|
1279
|
+
}>({
|
|
1280
|
+
defaults: { user: { name: 'Employee' }, attendance: { progress: 0 } },
|
|
1281
|
+
});
|
|
1282
|
+
|
|
1283
|
+
await Widget.setLayout('main', {
|
|
1284
|
+
medium: (
|
|
1285
|
+
<VStack padding={14} spacing={6}>
|
|
1286
|
+
<Text>{data.user.name}</Text>
|
|
1287
|
+
<Text>{data.attendance.progress}%</Text>
|
|
1288
|
+
<Progress value={data.attendance.progress.divide(100)} />
|
|
1289
|
+
</VStack>
|
|
1290
|
+
),
|
|
1291
|
+
});
|
|
1292
|
+
|
|
1293
|
+
await Widget.setRemoteConfig('main', {
|
|
1294
|
+
cacheTtlSeconds: 300,
|
|
1295
|
+
timeoutMs: 6000,
|
|
1296
|
+
enableETag: true,
|
|
1297
|
+
maxRetries: 2,
|
|
1298
|
+
retryDelayMs: 500,
|
|
1299
|
+
sources: {
|
|
1300
|
+
user: { url: 'https://api.yourapp.com/me' },
|
|
1301
|
+
attendance: { url: 'https://api.yourapp.com/attendance/today' },
|
|
1302
|
+
},
|
|
1303
|
+
schema: { requiredKeys: ['user.name', 'attendance.progress'], types: { 'attendance.progress': 'number' } },
|
|
1304
|
+
authRefresh: { url: 'https://api.yourapp.com/auth/refresh', method: 'POST', tokenPath: 'accessToken' },
|
|
1305
|
+
errorFallback: <Text color="#F87171">Sync error ({{_httpStatus}}): {{_syncError}}</Text>,
|
|
1306
|
+
refreshIntervalMinutes: 15,
|
|
1307
|
+
});
|
|
1308
|
+
```
|
|
1309
|
+
|
|
1310
|
+
> ⚠️ **Important OS Reload Budget Disclaimer:** Exact 15-minute background intervals are **not guaranteed** when the app is terminated. **Apple WidgetKit** enforces a dynamic daily reload budget (typically ~**40–70 reloads/day** depending on user engagement; `refreshIntervalMinutes` maps to `TimelineReloadPolicy.after(...)` as an earliest hint, not an exact cron guarantee). **Android** likewise enforces Doze Mode and App Standby Buckets. For real-time second-by-second updates, pair widgets with server pushes (APNs / FCM).
|
|
1311
|
+
|
|
1312
|
+
---
|
|
1313
|
+
|
|
1314
|
+
## 14. TypeScript-Driven Swift Codegen & Automated i18n Sync (`widgets.config.ts`)
|
|
1315
|
+
|
|
1316
|
+
Starting from version 1.2.1, you don't need to manually modify Swift bundle source files (`LiveWidgetsBundle.swift`) or configure localization files in Xcode. The entire configuration is defined in **100% TypeScript** via `widgets.config.ts` in your project root.
|
|
1317
|
+
|
|
1318
|
+
### 1. Sample `widgets.config.ts`:
|
|
1319
|
+
```typescript
|
|
1320
|
+
import { defineWidgetConfig } from 'react-native-live-widgets';
|
|
1321
|
+
|
|
1322
|
+
export default defineWidgetConfig({
|
|
1323
|
+
bundleName: 'LiveWidgetsBundle',
|
|
1324
|
+
liveActivity: true, // Enable/disable Live Activity Widget
|
|
1325
|
+
controlWidgets: true, // Enable Control Center Widget (iOS 18+)
|
|
1326
|
+
defaultLocale: 'en',
|
|
1327
|
+
locales: {
|
|
1328
|
+
en: {
|
|
1329
|
+
'widgets.main.title': 'Live Widgets Utility',
|
|
1330
|
+
'widgets.main.desc': 'Visual KPI and attendance tracking',
|
|
1331
|
+
},
|
|
1332
|
+
vi: {
|
|
1333
|
+
'widgets.main.title': 'Tiện ích Live Widgets',
|
|
1334
|
+
'widgets.main.desc': 'Theo dõi KPI và chấm công trực quan',
|
|
1335
|
+
},
|
|
1336
|
+
},
|
|
1337
|
+
widgets: [
|
|
1338
|
+
{
|
|
1339
|
+
key: 'main',
|
|
1340
|
+
kind: 'LiveWidget_main',
|
|
1341
|
+
displayName: 'widgets.main.title',
|
|
1342
|
+
description: 'widgets.main.desc',
|
|
1343
|
+
supportedFamilies: ['systemSmall', 'systemMedium', 'systemLarge'],
|
|
1344
|
+
},
|
|
1345
|
+
],
|
|
1346
|
+
});
|
|
1347
|
+
```
|
|
1348
|
+
|
|
1349
|
+
### 2. Execute Codegen CLI:
|
|
1350
|
+
```bash
|
|
1351
|
+
npx react-native-live-widgets codegen
|
|
1352
|
+
```
|
|
1353
|
+
|
|
1354
|
+
This CLI command automatically:
|
|
1355
|
+
1. **Syncs System Icons**: Automatically extracts **9,500+ Apple SF Symbols** from macOS and **3,800+ Google Material Icons** into auto-complete type definition files (`sf-symbols.generated.ts` & `material-icons.generated.ts`), providing full TypeScript IntelliSense.
|
|
1356
|
+
2. **Generates Swift Source Bundle**: Creates `ios/LiveWidgetsExtension/LiveWidgetsBundle.swift` registering all configured Widgets and Control Center widgets.
|
|
1357
|
+
3. **Synchronizes iOS Localization**: Generates modern Apple String Catalog `ios/LiveWidgetsExtension/Localizable.xcstrings` for all defined languages.
|
|
1358
|
+
4. **Synchronizes Android Localization**: Automatically updates `android/app/src/main/res/values/strings.xml` (default locale) and `values-{lang}/strings.xml` for Android AppWidget localized names.
|
|
1359
|
+
|
|
1360
|
+
---
|
|
1361
|
+
|
|
1362
|
+
### 🌐 Online Interactive Web Documentation
|
|
1363
|
+
|
|
1364
|
+
- **Web Documentation & Live Simulator**: [https://react-native-vu.github.io/react-native-live-widgets/](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
1365
|
+
- **AI Agent Quick Reference (`llms.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms.txt](https://react-native-vu.github.io/react-native-live-widgets/llms.txt)
|
|
1366
|
+
- **AI Agent Full Manual (`llms-full.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt](https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt)
|
|
1367
|
+
|
|
1368
|
+
---
|
|
1369
|
+
|
|
1188
1370
|
## 📄 License
|
|
1189
1371
|
MIT © vu-tran
|
|
1190
1372
|
|
package/docs/GUIDE-VI.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP THƯ VIỆN REACT-NATIVE-LIVE-WIDGETS 🚀
|
|
2
2
|
|
|
3
|
-
> 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Hướng dẫn riêng cho Expo (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md)
|
|
3
|
+
> 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md) • [⚡ Hướng dẫn riêng cho Expo (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md) • [🌐 Web Docs & Live Simulator](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
4
4
|
|
|
5
5
|
Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (iOS/Android), xây dựng giao diện động bằng JavaScript/TypeScript cho cả **Live Activities (Dynamic Island / Lock Screen / Android Live Update)** và **Home Screen Widgets (Tiện ích màn hình chính tương tác đa trang)**.
|
|
6
6
|
|
|
@@ -37,8 +37,10 @@ Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (
|
|
|
37
37
|
8. [Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)](#8-đồng-bộ-api-ngầm-cho-widget-kể-cả-khi-kill-app-widgetsetremoteconfig)
|
|
38
38
|
9. [Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity](#9-quản-lý-3-loại-push-token-apns--fcm-cho-live-activity)
|
|
39
39
|
10. [State Machine & Tự động cập nhật theo pha (Phases)](#10-state-machine--tự-động-cập-nhật-theo-pha-phases)
|
|
40
|
-
11. [Cấu trúc Payload Server Push (APNs & FCM)](#
|
|
41
|
-
12. [Xử lý sự cố thường gặp (Troubleshooting)](#
|
|
40
|
+
11. [Cấu trúc Payload Server Push (APNs & FCM)](#10-cấu-trúc-payload-server-push-apns--fcm)
|
|
41
|
+
12. [Xử lý sự cố thường gặp (Troubleshooting)](#11-xử-lý-sự-cố-thường-gặp-troubleshooting)
|
|
42
|
+
13. [Hệ thống Styling Modifiers, UI IR, Exact Hit Layer & Năng lực Nền tảng (v1.2.1)](#12-hệ-thống-styling-modifiers--bảng-năng-lực-nền-tảng-capability--fallback-matrix)
|
|
43
|
+
14. [TypeScript-Driven Swift Codegen & Tự động Đồng bộ Đa ngôn ngữ i18n (`widgets.config.ts`)](#14-typescript-driven-swift-codegen--tự-động-đồng-bộ-đa-ngôn-ngữ-i18n-widgetsconfigts)
|
|
42
44
|
|
|
43
45
|
---
|
|
44
46
|
|
|
@@ -76,32 +78,47 @@ npx expo run:ios # hoặc npx expo run:android
|
|
|
76
78
|
|
|
77
79
|
## 3. Cài đặt và Thiết lập Dự án
|
|
78
80
|
|
|
79
|
-
###
|
|
80
|
-
|
|
81
|
-
|
|
81
|
+
### 📋 Bảng Tra Cứu Các Lệnh CLI Quan Trọng
|
|
82
|
+
|
|
83
|
+
| Lệnh | Chức năng | Thời điểm sử dụng |
|
|
84
|
+
| :--- | :--- | :--- |
|
|
85
|
+
| `npx react-native-live-widgets init` | **Thiết lập tự động All-in-One**: Tự cấu hình `app.json` (Expo), Xcode Target, Entitlements, Podfile, `pod install`, Android permissions, tạo file `widgets.config.ts`, trích xuất 13,000+ icons và biên dịch Swift bundle. | Chạy 1 lần duy nhất khi tích hợp thư viện vào dự án |
|
|
86
|
+
| `npx react-native-live-widgets codegen` | **Đồng bộ Codegen & i18n**: Đọc lại `widgets.config.ts`, cập nhật `LiveWidgetsBundle.swift`, Apple String Catalog (`Localizable.xcstrings`) và Android `strings.xml`. | Mỗi khi sửa `widgets.config.ts` hoặc thêm widget/ngôn ngữ mới |
|
|
87
|
+
| `npx react-native-live-widgets init --group <name>` | **Chỉ định App Group tuỳ chỉnh**: Ví dụ `group.com.yourcompany.app`. | Khi bạn muốn dùng App Group khác với mã bundle tự nhận diện |
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
### Cách 1: Dành cho dự án Expo (Managed / CNG)
|
|
82
92
|
|
|
83
93
|
```bash
|
|
84
|
-
# 1
|
|
94
|
+
# Bước 1: Cài đặt thư viện
|
|
85
95
|
npx expo install react-native-live-widgets
|
|
86
96
|
|
|
87
|
-
# 2
|
|
88
|
-
npx
|
|
97
|
+
# Bước 2: Thiết lập tự động 1 lệnh (tự ghi app.json, tạo widgets.config.ts, sync icons & Swift)
|
|
98
|
+
npx react-native-live-widgets init
|
|
89
99
|
|
|
90
|
-
# 3
|
|
91
|
-
npx
|
|
100
|
+
# Bước 3: Khởi chạy trên thiết bị / máy ảo
|
|
101
|
+
npx expo run:ios
|
|
102
|
+
# hoặc: npx expo run:android
|
|
92
103
|
```
|
|
93
104
|
|
|
105
|
+
> 👉 **Xem hướng dẫn chi tiết từng bước cho Expo tại: [Tài liệu Expo Tích hợp (EXPO-GUIDE-VI.md)](./EXPO-GUIDE-VI.md)**
|
|
106
|
+
|
|
94
107
|
---
|
|
95
108
|
|
|
96
|
-
###
|
|
97
|
-
|
|
109
|
+
### Cách 2: Dành cho Bare React Native CLI
|
|
110
|
+
|
|
98
111
|
```bash
|
|
112
|
+
# Bước 1: Cài đặt thư viện
|
|
99
113
|
npm install react-native-live-widgets
|
|
100
|
-
# hoặc
|
|
101
|
-
|
|
114
|
+
# hoặc: yarn add react-native-live-widgets
|
|
115
|
+
|
|
116
|
+
# Bước 2: Thiết lập tự động 1 lệnh (tự cấu hình Xcode target, Podfile, pod install, Android permissions, widgets.config.ts, Swift bundle)
|
|
117
|
+
npx react-native-live-widgets init
|
|
102
118
|
|
|
103
|
-
#
|
|
104
|
-
npx react-native-
|
|
119
|
+
# Bước 3: Khởi chạy trên thiết bị / máy ảo
|
|
120
|
+
npx react-native run-ios
|
|
121
|
+
# hoặc: npx react-native run-android
|
|
105
122
|
```
|
|
106
123
|
|
|
107
124
|
---
|
|
@@ -536,15 +553,38 @@ UI.Image({
|
|
|
536
553
|
cornerRadius: 8,
|
|
537
554
|
})
|
|
538
555
|
|
|
539
|
-
// 3. Icon hệ thống (SF Symbols
|
|
556
|
+
// 3. Icon hệ thống đa nền tảng (Apple SF Symbols + Google Material Icons)
|
|
557
|
+
// Cách 1: Tự động ánh xạ trên cả 2 nền tảng
|
|
540
558
|
UI.Image({
|
|
541
|
-
systemName: '
|
|
542
|
-
tintColor: '#
|
|
543
|
-
width:
|
|
544
|
-
height:
|
|
559
|
+
systemName: 'bolt',
|
|
560
|
+
tintColor: '#10B981',
|
|
561
|
+
width: 20,
|
|
562
|
+
height: 20,
|
|
563
|
+
})
|
|
564
|
+
|
|
565
|
+
// Cách 2: Chỉ định icon chuyên biệt cho từng hệ điều hành (với gợi ý Type Auto-Complete 9500+ SF Symbols & 3800+ Material Icons)
|
|
566
|
+
UI.Image({
|
|
567
|
+
systemNameIos: 'bolt.horizontal.fill', // 9,500+ Apple SF Symbols chuẩn xịn
|
|
568
|
+
systemNameAndroid: 'bolt', // 3,800+ Google Material Icons (hỗ trợ cả snake_case và kebab-case)
|
|
569
|
+
tintColor: '#10B981',
|
|
570
|
+
width: 24,
|
|
571
|
+
height: 24,
|
|
545
572
|
})
|
|
573
|
+
|
|
574
|
+
// Hoặc sử dụng dạng JSX React Component:
|
|
575
|
+
<Image
|
|
576
|
+
systemNameIos="person.crop.circle.badge.checkmark"
|
|
577
|
+
systemNameAndroid="verified_user"
|
|
578
|
+
tintColor="#10B981"
|
|
579
|
+
width={24}
|
|
580
|
+
height={24}
|
|
581
|
+
/>
|
|
546
582
|
```
|
|
547
583
|
|
|
584
|
+
> 💡 **Tra cứu danh mục Icons chính thức từ Apple & Google:**
|
|
585
|
+
> - 🍏 **Apple SF Symbols (9,500+ Icons)**: Tra cứu và xem trước tại [Apple SF Symbols Official Website](https://developer.apple.com/sf-symbols/). Định nghĩa sẵn type `KnownSFSymbol` với IntelliSense auto-complete.
|
|
586
|
+
> - 🤖 **Google Material Icons (3,800+ Icons)**: Tra cứu tên icon tại [Google Fonts Icons / Material Symbols](https://fonts.google.com/icons). Định nghĩa sẵn type `KnownMaterialIcon`, hỗ trợ cả `snake_case` (ví dụ `battery_charging_full`) và `kebab-case` (`battery-charging-full`).
|
|
587
|
+
|
|
548
588
|
### `UI.Button` (Nút bấm tương tác trực tiếp trên Widget)
|
|
549
589
|
Cho phép người dùng thao tác ngay trên mặt Widget (iOS 17+ `AppIntents` & Android `PendingIntent` Hit Zones) mà **không cần mở ứng dụng**:
|
|
550
590
|
```typescript
|
|
@@ -1209,5 +1249,150 @@ Phiên bản **v1.2.1** giải quyết dứt điểm các bài toán thực tế
|
|
|
1209
1249
|
|
|
1210
1250
|
---
|
|
1211
1251
|
|
|
1252
|
+
### 12.8. 📱 Widget Family Mở rộng (`extraLarge`, `standBy`, `ControlWidget`) & Quản lý Vòng đời Live Activity Hoàn chỉnh
|
|
1253
|
+
|
|
1254
|
+
#### 1. Widget Family Mở rộng
|
|
1255
|
+
Ngoài 3 kích thước cơ bản (`small`, `medium`, `large`) và 3 kiểu Lock Screen (`accessoryRectangular`, `accessoryCircular`, `accessoryInline`), thư viện hỗ trợ thêm:
|
|
1256
|
+
- **`extraLarge?: LayoutNode`**: Dành cho iPadOS (`systemExtraLarge`) và Tablet/Android 4x4+ (`widgetHeightDp >= 280dp`). Hỗ trợ xem trước trực tiếp trong `<WidgetPreview size="extraLarge">`.
|
|
1257
|
+
- **`standBy?: LayoutNode`**: Tự động kích hoạt khi iPhone ở chế độ StandBy iOS 17+ (`family == .systemSmall && !showsWidgetContainerBackground`). Hỗ trợ `widgetAccentable` trên `Text`, `Progress`, `Gauge`, `Image` và `<WidgetPreview size="standBy">`. Widget extension có thể gọi `.applyStandByMargins()` trên `StaticConfiguration` để bật chế độ full-bleed.
|
|
1258
|
+
- **`ControlWidget` iOS 18+ & Android Quick Settings Tile (`ControlWidget` / `Widget.setControl`)**: Điều khiển trực tiếp iOS 18 Control Center, Action Button, Lock Screen Controls thông qua module [`ios/Widgets/DynamicControlWidget.swift`](https://github.com/React-Native-Vu/react-native-live-widgets/blob/dev/ios/Widgets/DynamicControlWidget.swift) (`DynamicControlWidget` & `DynamicControlToggleWidget`) và Android Quick Settings Tile qua `DynamicQuickSettingsTileService.kt` — kết nối trực tiếp vào `DynamicWidgetStateStore` và `useWidgetAction`:
|
|
1259
|
+
```typescript
|
|
1260
|
+
import { ControlWidget, UI, WidgetPreview } from 'react-native-live-widgets';
|
|
1261
|
+
|
|
1262
|
+
const shiftControl = ControlWidget.toggle({
|
|
1263
|
+
title: 'Ca làm việc',
|
|
1264
|
+
subtitle: 'Chạm để chấm công',
|
|
1265
|
+
checkedTitle: 'Đang trong ca',
|
|
1266
|
+
checkedSubtitle: 'Nhấn để kết thúc',
|
|
1267
|
+
systemName: 'clock.badge.checkmark.fill',
|
|
1268
|
+
checked: true,
|
|
1269
|
+
actionId: 'toggle:attendance',
|
|
1270
|
+
});
|
|
1271
|
+
|
|
1272
|
+
await ControlWidget.set('toggle', shiftControl);
|
|
1273
|
+
// Hoặc dùng UI.ControlButton({ ... }) / Widget.setControl('main', ...)
|
|
1274
|
+
|
|
1275
|
+
// Xem trước trực tiếp trong App:
|
|
1276
|
+
// <WidgetPreview size="control" controlConfig={shiftControl} />
|
|
1277
|
+
```
|
|
1278
|
+
|
|
1279
|
+
#### 2. API Quản lý Vòng đời Live Activity Hoàn chỉnh
|
|
1280
|
+
Thư viện chuẩn hóa đầy đủ 8 khả năng quản lý vòng đời cho cả iOS ActivityKit và Android Live Updates:
|
|
1281
|
+
- **Quản lý nhiều phiên đồng thời**: `LiveActivity.getActiveActivities()`, `LiveActivity.get(activityId)`, `LiveActivity.isActive(activityId)`, `LiveActivity.endAll()` — trả về `activityId` chính xác kèm `systemActivityId` và `pushToken`.
|
|
1282
|
+
- **Stale State (`staleTimestamp`, `staleLockScreen`, `staleDynamicIsland`)**: Tự động chuyển sang giao diện dự phòng khi hết độ tươi (`context.isStale` trên iOS 16.2+ / `now >= staleTimestamp` trên Android).
|
|
1283
|
+
- **Relevance Score (`relevanceScore`)**: Ưu tiên thứ tự hiển thị trên Lock Screen / Dynamic Island (iOS `ActivityContent.relevanceScore`) và sắp xếp ưu tiên trên Notification Shade Android (`setSortKey`).
|
|
1284
|
+
- **Alert Configuration (`alertConfig`)**: Hỗ trợ `{ title, body, sound }` (bên cạnh `alertTitle`/`alertBody`) qua `AlertConfiguration` khi gọi `LiveActivity.update()` trên iOS 16.2+ và bật chuông/rung trên Android.
|
|
1285
|
+
- **Scheduled End & Tự động xử lý hết hạn (`scheduledEndTimestamp`, `autoEndAfterSeconds`, `expiredLockScreen`, `expiredDismissalPolicy`)**: Tự động chuyển sang giao diện hết hạn hoặc đóng Activity đúng giờ hẹn, kèm `LiveActivity.cleanupExpired()` và sự kiện `LiveActivity.onStateChange((ev) => ...)` theo dõi các trạng thái `'active' | 'started_by_push' | 'stale' | 'expired' | 'ended' | 'dismissed'`.
|
|
1286
|
+
- **Hook `useLiveActivity` nâng cấp**: Trả về thêm `activities`, `lifecycleState`, `isStale`, `refreshActivities`, và `cleanupExpired`.
|
|
1287
|
+
|
|
1288
|
+
---
|
|
1289
|
+
|
|
1290
|
+
### 12.9. 🔄 Background Data Engine 2.0 & Structured Data Binding
|
|
1291
|
+
|
|
1292
|
+
`Widget.setRemoteConfig` và `Widget.createDataBinding<T>()` cung cấp động cơ đồng bộ dữ liệu nền hoàn chỉnh ngay cả khi người dùng đã vuốt đóng (Force-Kill) ứng dụng chính:
|
|
1293
|
+
|
|
1294
|
+
| Nhóm tính năng | Khả năng hỗ trợ Native (iOS SwiftUI + Android) |
|
|
1295
|
+
| :--- | :--- |
|
|
1296
|
+
| **REST & Auth** | `url`, `method` (`GET`/`POST`/`PUT`), `body` JSON, `headers` tùy biến, **`authRefresh`** tự động lấy Access Token mới khi gặp HTTP `401` |
|
|
1297
|
+
| **Mạng & Cache** | **`cacheTtlSeconds`** chống gọi lặp khi OS reload timeline, **`enableETag`** (`If-None-Match`/`If-Modified-Since` + HTTP `304 Not Modified`), **`timeoutMs`**, **`maxRetries` + `retryDelayMs`** (Exponential Backoff) |
|
|
1298
|
+
| **Đa nguồn & Chuẩn hóa** | **`sources`** gom nhiều API theo tiền tố `<sourceKey>.<nested.path>`, JSON Flattener lồng nhau (`user.name`, `items.0.title`), **`mapping`** & **`schema`** validation (`requiredKeys`, `types`, `defaults`) |
|
|
1299
|
+
| **Error State** | Biến hệ thống `{{_syncStatus}}` (`ok` / `partial` / `error`), `{{_syncError}}`, `{{_httpStatus}}` và **`errorFallback`** LayoutNode dự phòng (giữ nguyên dữ liệu cache hợp lệ khi mạng lỗi) |
|
|
1300
|
+
| **Structured Data Binding** | `Widget.createDataBinding<T>()` & `UI.bind(path, pipes)` hỗ trợ nested path & Pipe Transform (`default`, `divide`, `multiply`, `add`, `round`, `upper`, `lower`, `currency`, `percent`, `if`) |
|
|
1301
|
+
|
|
1302
|
+
```tsx
|
|
1303
|
+
const data = Widget.createDataBinding<{
|
|
1304
|
+
user: { name: string };
|
|
1305
|
+
attendance: { progress: number };
|
|
1306
|
+
}>({
|
|
1307
|
+
defaults: { user: { name: 'Nhân viên' }, attendance: { progress: 0 } },
|
|
1308
|
+
});
|
|
1309
|
+
|
|
1310
|
+
await Widget.setLayout('main', {
|
|
1311
|
+
medium: (
|
|
1312
|
+
<VStack padding={14} spacing={6}>
|
|
1313
|
+
<Text>{data.user.name}</Text>
|
|
1314
|
+
<Text>{data.attendance.progress}%</Text>
|
|
1315
|
+
<Progress value={data.attendance.progress.divide(100)} />
|
|
1316
|
+
</VStack>
|
|
1317
|
+
),
|
|
1318
|
+
});
|
|
1319
|
+
|
|
1320
|
+
await Widget.setRemoteConfig('main', {
|
|
1321
|
+
cacheTtlSeconds: 300,
|
|
1322
|
+
timeoutMs: 6000,
|
|
1323
|
+
enableETag: true,
|
|
1324
|
+
maxRetries: 2,
|
|
1325
|
+
retryDelayMs: 500,
|
|
1326
|
+
sources: {
|
|
1327
|
+
user: { url: 'https://api.yourapp.com/me' },
|
|
1328
|
+
attendance: { url: 'https://api.yourapp.com/attendance/today' },
|
|
1329
|
+
},
|
|
1330
|
+
schema: { requiredKeys: ['user.name', 'attendance.progress'], types: { 'attendance.progress': 'number' } },
|
|
1331
|
+
authRefresh: { url: 'https://api.yourapp.com/auth/refresh', method: 'POST', tokenPath: 'accessToken' },
|
|
1332
|
+
errorFallback: <Text color="#F87171">Lỗi đồng bộ ({{_httpStatus}}): {{_syncError}}</Text>,
|
|
1333
|
+
refreshIntervalMinutes: 15,
|
|
1334
|
+
});
|
|
1335
|
+
```
|
|
1336
|
+
|
|
1337
|
+
> ⚠️ **Lưu ý quan trọng về Ngân sách Reload của Hệ điều hành:** Không cam kết đồng bộ chính xác từng 15 phút khi ứng dụng bị đóng. **Apple WidgetKit** cấp phát ngân sách reload động cho mỗi Widget (thường khoảng **40–70 lần/ngày** tùy mức độ người dùng xem/tương tác; `refreshIntervalMinutes` map sang `TimelineReloadPolicy.after(...)` như mốc thời gian *sớm nhất được đề xuất*, không phải cron timer tuyệt đối). Trên **Android**, Doze Mode và App Standby Buckets có thể gom hoặc trì hoãn tác vụ nền. Với dữ liệu cần tức thì từng giây (giao hàng, tỷ số), hãy kết hợp Push APNs / FCM.
|
|
1338
|
+
|
|
1339
|
+
---
|
|
1340
|
+
|
|
1341
|
+
## 14. TypeScript-Driven Swift Codegen & Tự động Đồng bộ Đa ngôn ngữ i18n (`widgets.config.ts`)
|
|
1342
|
+
|
|
1343
|
+
Từ phiên bản 1.2.1, bạn không cần phải tự tay chỉnh sửa file Swift (`LiveWidgetsBundle.swift`) hay cấu hình thủ công các file dịch `Localizable.strings` trong Xcode. Toàn bộ cấu hình được định nghĩa bằng **100% TypeScript** qua file `widgets.config.ts` ở thư mục gốc của dự án.
|
|
1344
|
+
|
|
1345
|
+
### 1. Cấu hình `widgets.config.ts` mẫu:
|
|
1346
|
+
```typescript
|
|
1347
|
+
import { defineWidgetConfig } from 'react-native-live-widgets';
|
|
1348
|
+
|
|
1349
|
+
export default defineWidgetConfig({
|
|
1350
|
+
bundleName: 'LiveWidgetsBundle',
|
|
1351
|
+
liveActivity: true, // Bật/tắt Widget Live Activity
|
|
1352
|
+
controlWidgets: true, // Bật Control Center Widget (iOS 18+)
|
|
1353
|
+
defaultLocale: 'vi',
|
|
1354
|
+
locales: {
|
|
1355
|
+
vi: {
|
|
1356
|
+
'widgets.main.title': 'Tiện ích Live Widgets',
|
|
1357
|
+
'widgets.main.desc': 'Theo dõi KPI và chấm công trực quan',
|
|
1358
|
+
},
|
|
1359
|
+
en: {
|
|
1360
|
+
'widgets.main.title': 'Live Widgets Utility',
|
|
1361
|
+
'widgets.main.desc': 'Visual KPI and attendance tracking',
|
|
1362
|
+
},
|
|
1363
|
+
},
|
|
1364
|
+
widgets: [
|
|
1365
|
+
{
|
|
1366
|
+
key: 'main',
|
|
1367
|
+
kind: 'LiveWidget_main',
|
|
1368
|
+
displayName: 'widgets.main.title',
|
|
1369
|
+
description: 'widgets.main.desc',
|
|
1370
|
+
supportedFamilies: ['systemSmall', 'systemMedium', 'systemLarge'],
|
|
1371
|
+
},
|
|
1372
|
+
],
|
|
1373
|
+
});
|
|
1374
|
+
```
|
|
1375
|
+
|
|
1376
|
+
### 2. Thực thi lệnh CLI Codegen:
|
|
1377
|
+
```bash
|
|
1378
|
+
npx react-native-live-widgets codegen
|
|
1379
|
+
```
|
|
1380
|
+
|
|
1381
|
+
Lệnh này sẽ tự động:
|
|
1382
|
+
1. **Trích xuất Icons hệ thống**: Tự động lấy hơn **9,500+ Apple SF Symbols** từ hệ thống macOS và hơn **3,800+ Google Material Icons** vào các file type definitions (`sf-symbols.generated.ts` & `material-icons.generated.ts`) giúp lập trình viên có IntelliSense auto-complete đầy đủ.
|
|
1383
|
+
2. **Sinh mã nguồn Swift**: Tạo file `ios/LiveWidgetsExtension/LiveWidgetsBundle.swift` đăng ký đầy đủ các Widget và Control Center Widgets tự động.
|
|
1384
|
+
3. **Đồng bộ đa ngôn ngữ iOS**: Tạo file String Catalog hiện đại `ios/LiveWidgetsExtension/Localizable.xcstrings` với đầy đủ các ngôn ngữ đã cấu hình.
|
|
1385
|
+
4. **Đồng bộ đa ngôn ngữ Android**: Tự động ghi và cập nhật các file `android/app/src/main/res/values/strings.xml` (ngôn ngữ mặc định) và `values-{lang}/strings.xml` cho Android AppWidget.
|
|
1386
|
+
|
|
1387
|
+
---
|
|
1388
|
+
|
|
1389
|
+
### 🌐 Trang Web Tài Liệu Trực Tuyến & Live Simulator
|
|
1390
|
+
|
|
1391
|
+
- **Interactive Web Documentation**: [https://react-native-vu.github.io/react-native-live-widgets/](https://react-native-vu.github.io/react-native-live-widgets/)
|
|
1392
|
+
- **AI Agent Quick Reference (`llms.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms.txt](https://react-native-vu.github.io/react-native-live-widgets/llms.txt)
|
|
1393
|
+
- **AI Agent Full Manual (`llms-full.txt`)**: [https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt](https://react-native-vu.github.io/react-native-live-widgets/llms-full.txt)
|
|
1394
|
+
|
|
1395
|
+
---
|
|
1396
|
+
|
|
1212
1397
|
## 📄 License
|
|
1213
1398
|
MIT © vu-tran
|