react-native-live-widgets 0.0.0-stage → 1.0.0
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 +13 -0
- package/LICENSE +21 -0
- package/README.md +221 -2
- package/android/build.gradle +49 -0
- package/android/src/main/AndroidManifest.xml +38 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +440 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityPackage.kt +17 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +24 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +410 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +67 -0
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicNodeRegistry.kt +64 -0
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +1223 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +120 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +281 -0
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +229 -0
- package/android/src/main/res/layout/rn_live_widget_host.xml +113 -0
- package/android/src/main/res/xml/rn_live_widget_info.xml +14 -0
- package/assets/dashboard_features.png +0 -0
- package/assets/dynamic_island_expanded.png +0 -0
- package/assets/home_widget_interactive.png +0 -0
- package/assets/lock_screen_live_activity.png +0 -0
- package/cli/setup.js +94 -0
- package/docs/GUIDE-EN.md +804 -0
- package/docs/GUIDE-VI.md +802 -0
- package/docs/widgets.md +52 -0
- package/ios/Bridge/LiveActivityModule.m +105 -0
- package/ios/Bridge/LiveActivityModule.swift +957 -0
- package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
- package/ios/Models/DynamicActivityAttributes.swift +22 -0
- package/ios/Models/DynamicLayoutModels.swift +243 -0
- package/ios/Renderer/ColorHexExtension.swift +49 -0
- package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
- package/ios/Renderer/DynamicNodeView.swift +1060 -0
- package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
- package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
- package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
- package/lib/builder.d.ts +60 -0
- package/lib/builder.d.ts.map +1 -0
- package/lib/builder.js +296 -0
- package/lib/builder.js.map +1 -0
- package/lib/dispatcher.d.ts +16 -0
- package/lib/dispatcher.d.ts.map +1 -0
- package/lib/dispatcher.js +23 -0
- package/lib/dispatcher.js.map +1 -0
- package/lib/index.d.ts +199 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +634 -0
- package/lib/index.js.map +1 -0
- package/lib/types.d.ts +489 -0
- package/lib/types.d.ts.map +1 -0
- package/lib/types.js +10 -0
- package/lib/types.js.map +1 -0
- package/package.json +68 -4
- package/react-native-live-widgets.podspec +38 -0
- package/src/builder.ts +409 -0
- package/src/dispatcher.ts +25 -0
- package/src/index.ts +681 -0
- package/src/types.ts +595 -0
package/docs/GUIDE-VI.md
ADDED
|
@@ -0,0 +1,802 @@
|
|
|
1
|
+
# HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP THƯ VIỆN REACT-NATIVE-LIVE-WIDGETS 🚀
|
|
2
|
+
|
|
3
|
+
> 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md)
|
|
4
|
+
|
|
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
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## MỤC LỤC
|
|
10
|
+
1. [Giới thiệu và Kiến trúc](#1-giới-thiệu-và-kiến-trúc)
|
|
11
|
+
2. [Cài đặt và Thiết lập Dự án](#2-cài-đặt-và-thiết-lập-dự-án)
|
|
12
|
+
- [Cài đặt package](#cài-đặt-package)
|
|
13
|
+
- [Thiết lập iOS (Xcode & Widget Extension)](#thiết-lập-ios-xcode--widget-extension)
|
|
14
|
+
- [Thiết lập Android (Gradle, Manifest, MainApplication & Permissions)](#thiết-lập-android-gradle-manifest-mainapplication--permissions)
|
|
15
|
+
- [Cấu trúc Thư mục Native của Thư viện (`ios/` & `android/`)](#cấu-trúc-thư-mục-native-của-thư-viện-ios--android)
|
|
16
|
+
3. [Tài liệu API (Core API Reference)](#3-tài-liệu-api-core-api-reference)
|
|
17
|
+
- [LiveActivity API (Màn hình khóa, Dynamic Island & 3 loại Push Token)](#1-liveactivity-api)
|
|
18
|
+
- [Widget API (Tiện ích màn hình chính, Multi-page & Background Sync)](#2-widget-api)
|
|
19
|
+
- [SharedStorage API (Đồng bộ App Groups & SharedPreferences)](#3-sharedstorage-api)
|
|
20
|
+
4. [Xây dựng Giao diện Động (Declarative UI Engine)](#4-xây-dựng-giao-diện-động-declarative-ui-engine)
|
|
21
|
+
- [UI.VStack & UI.HStack](#uivstack--uihstack)
|
|
22
|
+
- [UI.Text](#uitext)
|
|
23
|
+
- [UI.Timer (Realtime không tốn pin)](#uitimer-realtime-không-tốn-pin)
|
|
24
|
+
- [UI.Progress (Thanh tiến trình bar, segmented, circular)](#uiprogress-thanh-tiến-trình-đa-dạng)
|
|
25
|
+
- [UI.Equalizer (Sóng nhạc chuyển động liên tục)](#uiequalizer-sóng-nhạc-chuyển-động-liên-tục)
|
|
26
|
+
- [UI.Image (URL mạng, Base64, File, Asset & SF Symbols)](#uiimage-url-mạng-base64-file-asset--sf-symbols)
|
|
27
|
+
- [UI.Button (Tương tác chuyển trang, Tick công việc, Refresh API & Deep Link)](#uibutton-nút-bấm-tương-tác-trực-tiếp-trên-widget)
|
|
28
|
+
5. [Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)](#5-cấu-hình-dynamic-island-iphone-14-pro-15-16-17)
|
|
29
|
+
6. [Tạo Home Screen & Lock Screen Widget Đa Dạng bằng JavaScript](#6-tạo-home-screen-widget-đa-trang--tương-tác-bằng-javascript)
|
|
30
|
+
- [Lock Screen Widgets trên iOS (accessoryRectangular, circular, inline)](#lock-screen-widgets-trên-ios)
|
|
31
|
+
- [Ghim Tiện ích vào Màn hình chính trong App (Android In-App Pin)](#ghim-tiện-ích-vào-màn-hình-chính-trong-app-android-in-app-pin)
|
|
32
|
+
7. [Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)](#7-đồng-bộ-api-ngầm-cho-widget-kể-cả-khi-kill-app-widgetsetremoteconfig)
|
|
33
|
+
8. [Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity](#8-quản-lý-3-loại-push-token-apns--fcm-cho-live-activity)
|
|
34
|
+
9. [State Machine & Tự động cập nhật theo pha (Phases)](#9-state-machine--tự-động-cập-nhật-theo-pha-phases)
|
|
35
|
+
10. [Cấu trúc Payload Server Push (APNs & FCM)](#10-cấu-trúc-payload-server-push-apns--fcm)
|
|
36
|
+
11. [Xử lý sự cố thường gặp (Troubleshooting)](#11-xử-lý-sự-cố-thường-gặp-troubleshooting)
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 1. Giới thiệu và Kiến trúc
|
|
41
|
+
|
|
42
|
+
Thư viện **`react-native-live-widgets`** là giải pháp All-in-One cho phép viết **100% giao diện Widget và Live Activity ngay trong code React Native (`App.tsx`)**, tự động ánh xạ sang Native cho cả iOS và Android:
|
|
43
|
+
|
|
44
|
+
- **Live Activity (iOS 16.1+ ActivityKit & Dynamic Island):** Cho sự kiện thời gian thực (chấm công, chuyến xe, giao đồ ăn, bấm giờ Pomodoro).
|
|
45
|
+
- **Live Update (Android API 24 -> Android 16 API 36 `Notification.ProgressStyle`):** Thông báo thời gian thực trên thanh trạng thái Android có hỗ trợ ảnh đại diện (`LargeIcon`), thanh chia chặng (`segmented`) và các nút bấm tương tác (`Action Buttons`).
|
|
46
|
+
- **Home Screen Widgets (iOS WidgetKit & Android AppWidget Canvas Renderer):** Tiện ích ngoài màn hình chính (`small`, `medium`, `large`) hỗ trợ bấm chuyển trang/tab (`pages`), tick hoàn thành công việc (`toggle`), hiển thị ảnh từ URL mạng/Base64 và tự động gọi API ngầm khi ứng dụng bị tắt.
|
|
47
|
+
- **Shared Storage:** Cầu nối lưu trữ tức thời giữa React Native App và Widgets thông qua iOS App Groups và Android `SharedPreferences`.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 2. Cài đặt và Thiết lập Dự án
|
|
52
|
+
|
|
53
|
+
### Cài đặt package
|
|
54
|
+
Trong thư mục gốc của dự án React Native:
|
|
55
|
+
```bash
|
|
56
|
+
npm install react-native-live-widgets
|
|
57
|
+
# hoặc
|
|
58
|
+
yarn add react-native-live-widgets
|
|
59
|
+
|
|
60
|
+
# Tự động cấu hình Info.plist, Entitlements, AndroidManifest và tạo file mẫu Widget
|
|
61
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
### Thiết lập iOS (Xcode & Widget Extension)
|
|
67
|
+
|
|
68
|
+
#### Bước 1: Kích hoạt Live Activities & App Groups
|
|
69
|
+
Lệnh `npx react-native-live-widgets init` đã tự động thêm vào `Info.plist` và `.entitlements`:
|
|
70
|
+
```xml
|
|
71
|
+
<key>NSSupportsLiveActivities</key>
|
|
72
|
+
<true/>
|
|
73
|
+
<key>NSSupportsLiveActivitiesFrequentUpdates</key>
|
|
74
|
+
<true/>
|
|
75
|
+
```
|
|
76
|
+
Và trong `<TênApp>.entitlements` + `LiveWidgetsExtension.entitlements`:
|
|
77
|
+
```xml
|
|
78
|
+
<key>aps-environment</key>
|
|
79
|
+
<string>development</string>
|
|
80
|
+
<key>com.apple.security.application-groups</key>
|
|
81
|
+
<array>
|
|
82
|
+
<string>group.<bundle_id_của_bạn></string>
|
|
83
|
+
</array>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
#### Bước 2: Tạo Widget Extension Target trong Xcode (nếu chưa có)
|
|
87
|
+
1. Mở file `.xcworkspace` bằng Xcode.
|
|
88
|
+
2. Chọn menu: **File -> New -> Target... -> Widget Extension**.
|
|
89
|
+
3. Đặt tên **Product Name:** `LiveWidgets` (hoặc `LiveWidgetsExtension`), bỏ chọn *Include Configuration App Intent*.
|
|
90
|
+
4. Sử dụng nội dung chuẩn từ thư viện cho `LiveWidgetsBundle.swift`:
|
|
91
|
+
```swift
|
|
92
|
+
import WidgetKit
|
|
93
|
+
import SwiftUI
|
|
94
|
+
import react_native_live_widgets
|
|
95
|
+
|
|
96
|
+
@main
|
|
97
|
+
struct LiveWidgetsBundle: WidgetBundle {
|
|
98
|
+
var body: some Widget {
|
|
99
|
+
if #available(iOS 16.1, *) {
|
|
100
|
+
DynamicLiveActivityWidget()
|
|
101
|
+
}
|
|
102
|
+
DynamicHomeScreenWidget()
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
#### Bước 3: Cấu hình `Podfile` và cài đặt Pods
|
|
108
|
+
Trong `ios/Podfile`, đảm bảo target Widget Extension có kế thừa pod `react-native-live-widgets`:
|
|
109
|
+
```ruby
|
|
110
|
+
target 'LiveWidgetsExtension' do
|
|
111
|
+
use_modular_headers!
|
|
112
|
+
pod 'react-native-live-widgets', :path => '../node_modules/react-native-live-widgets'
|
|
113
|
+
end
|
|
114
|
+
```
|
|
115
|
+
Sau đó chạy:
|
|
116
|
+
```bash
|
|
117
|
+
cd ios && pod install
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
### Thiết lập Android (Gradle, Manifest, MainApplication & Permissions)
|
|
123
|
+
|
|
124
|
+
Trên Android, phần lớn cấu hình phức tạp đã được thư viện **tự động hóa sẵn** thông qua cơ chế **Android Manifest Merger** của Gradle. Dưới đây là chi tiết những gì đã có sẵn và những gì bạn cần kiểm tra trong dự án:
|
|
125
|
+
|
|
126
|
+
#### 1. Những thành phần thư viện đã tự động đăng ký (Bạn KHÔNG cần khai báo lại)
|
|
127
|
+
Trong file `AndroidManifest.xml` của thư viện `react-native-live-widgets` đã tích hợp sẵn và tự động gộp vào app của bạn khi build:
|
|
128
|
+
- **Các quyền hệ thống (Permissions):**
|
|
129
|
+
- `android.permission.INTERNET` (tải ảnh từ URL mạng & gọi Background API cho Widget).
|
|
130
|
+
- `android.permission.POST_NOTIFICATIONS` (hiển thị Live Update Notification trên Android 13+).
|
|
131
|
+
- `android.permission.POST_PROMOTED_NOTIFICATIONS` (hiển thị Live Updates chip trên thanh trạng thái Android 16 / API 36).
|
|
132
|
+
- `android.permission.VIBRATE`.
|
|
133
|
+
- **Home Screen Widget Provider (`DynamicHomeScreenWidgetProvider`):** Đã gắn sẵn bộ cấu hình `@xml/rn_live_widgets_info` hỗ trợ kéo giãn tự do (`resizeMode="horizontal|vertical"`).
|
|
134
|
+
- **Broadcast Receiver (`LiveActivityReceiver`):** Tự động bắt các sự kiện bấm nút trên Notification và Widget.
|
|
135
|
+
|
|
136
|
+
#### 2. Bước 1: Kiểm tra phiên bản SDK trong `android/build.gradle`
|
|
137
|
+
Đảm bảo file `android/build.gradle` của dự án có `minSdkVersion >= 24` và `compileSdkVersion >= 35` (hoặc `36` nếu muốn dùng Live Updates chuẩn Android 16):
|
|
138
|
+
```groovy
|
|
139
|
+
buildscript {
|
|
140
|
+
ext {
|
|
141
|
+
buildToolsVersion = "35.0.0"
|
|
142
|
+
minSdkVersion = 24
|
|
143
|
+
compileSdkVersion = 35 // Hoặc 36 cho Android 16
|
|
144
|
+
targetSdkVersion = 35
|
|
145
|
+
ndkVersion = "27.1.12297006"
|
|
146
|
+
kotlinVersion = "2.1.20"
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
#### 3. Bước 2: Kiểm tra `MainApplication.kt`
|
|
152
|
+
Với React Native 0.7x / 0.8x, cơ chế **Autolinking** (`PackageList(this).packages`) sẽ tự động liên kết `LiveActivityPackage`.
|
|
153
|
+
> ⚠️ **Lưu ý quan trọng với React Native 0.80+:** Trong `MainApplication.kt`, bắt buộc phải gọi `loadReactNative(this)` bên trong `onCreate()` để khởi tạo SoLoader/JSI trước khi mở ứng dụng:
|
|
154
|
+
```kotlin
|
|
155
|
+
package com.yourcompany.app
|
|
156
|
+
|
|
157
|
+
import android.app.Application
|
|
158
|
+
import com.facebook.react.PackageList
|
|
159
|
+
import com.facebook.react.ReactApplication
|
|
160
|
+
import com.facebook.react.ReactHost
|
|
161
|
+
import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
|
|
162
|
+
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
|
|
163
|
+
|
|
164
|
+
class MainApplication : Application(), ReactApplication {
|
|
165
|
+
override val reactHost: ReactHost by lazy {
|
|
166
|
+
getDefaultReactHost(
|
|
167
|
+
context = applicationContext,
|
|
168
|
+
packageList = PackageList(this).packages, // LiveActivityPackage() đã tự động được thêm tại đây
|
|
169
|
+
)
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
override fun onCreate() {
|
|
173
|
+
super.onCreate()
|
|
174
|
+
loadReactNative(this) // Bắt buộc trên React Native 0.80+
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
#### 4. Bước 3: Xin quyền Thông báo (Runtime Permission) trên Android 13+ (API 33+)
|
|
180
|
+
Trên Android 13 trở lên, hệ điều hành yêu cầu xin quyền `POST_NOTIFICATIONS` lúc chạy trước khi hiển thị Live Update Notification. Bạn có thể gọi hàm có sẵn của thư viện hoặc dùng `PermissionsAndroid` trong `App.tsx`:
|
|
181
|
+
```typescript
|
|
182
|
+
import { Platform, PermissionsAndroid } from 'react-native';
|
|
183
|
+
import { LiveActivity } from 'react-native-live-widgets';
|
|
184
|
+
|
|
185
|
+
async function ensureAndroidNotificationPermission() {
|
|
186
|
+
if (Platform.OS === 'android' && Platform.Version >= 33) {
|
|
187
|
+
await PermissionsAndroid.request(
|
|
188
|
+
PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
// Hoặc gọi trực tiếp hàm đa nền tảng của thư viện:
|
|
192
|
+
await LiveActivity.registerForPushNotifications();
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
#### 5. Bước 4: Cách thêm và kéo giãn Home Screen Widget trên Android (`small` / `medium` / `large`)
|
|
197
|
+
1. Sau khi gọi `Widget.update('main', { small, medium, large })` trong app, ra màn hình chính (Home Screen) của Android.
|
|
198
|
+
2. **Nhấn giữ vào khoảng trống** trên màn hình chính -> Chọn **Widgets (Tiện ích)** -> Tìm ứng dụng của bạn -> Kéo **Live Widgets** ra màn hình.
|
|
199
|
+
3. **Thay đổi kích thước tự động (Responsive Sizing):** Nhấn giữ vào Widget trên màn hình chính rồi thả tay ra để xuất hiện khung viền 4 chấm tròn:
|
|
200
|
+
- Kéo thu nhỏ về **2×2 ô** (`chiều rộng < 210dp`): Tự động hiển thị giao diện **`small`** (tỷ lệ vuông 1:1).
|
|
201
|
+
- Kéo ngang **4×2 ô** (mặc định): Tự động hiển thị giao diện **`medium`**.
|
|
202
|
+
- Kéo giãn dọc xuống **4×4 ô** (`chiều cao >= 200dp`): Tự động hiển thị giao diện **`large`** đầy đủ chi tiết.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
### Cấu trúc Thư mục Native của Thư viện (`ios/` & `android/`)
|
|
207
|
+
|
|
208
|
+
Mã nguồn native của thư viện được chia theo từng nhóm chức năng rõ ràng để bạn dễ dàng tra cứu hoặc mở rộng khi cần:
|
|
209
|
+
|
|
210
|
+
```text
|
|
211
|
+
react-native-live-widgets/
|
|
212
|
+
├── ios/
|
|
213
|
+
│ ├── Bridge/ # LiveActivityModule.swift/.m (Cầu nối React Native <-> iOS)
|
|
214
|
+
│ ├── Models/ # DynamicLayoutModels.swift, DynamicActivityAttributes.swift
|
|
215
|
+
│ ├── Storage/ # DynamicWidgetStateStore.swift, DynamicWidgetImageCache.swift
|
|
216
|
+
│ ├── Intents/ # DynamicWidgetActionIntent.swift (Xử lý nút bấm iOS 17+)
|
|
217
|
+
│ ├── Renderer/ # DynamicNodeView.swift, ColorHexExtension.swift (Vẽ SwiftUI từ JSON)
|
|
218
|
+
│ └── Widgets/ # DynamicHomeScreenWidget.swift, DynamicLiveActivityWidget.swift
|
|
219
|
+
└── android/src/main/java/com/reactnativeliveactivity/
|
|
220
|
+
├── bridge/ # LiveActivityModule.kt, LiveActivityPackage.kt
|
|
221
|
+
├── storage/ # DynamicWidgetStateStore.kt, DynamicWidgetImageCache.kt
|
|
222
|
+
├── renderer/ # DynamicWidgetCanvasRenderer.kt (Vẽ Canvas 2D + tính vùng bấm HitBox)
|
|
223
|
+
├── widgets/ # DynamicHomeScreenWidgetProvider.kt (Quản lý AppWidget Small/Medium/Large)
|
|
224
|
+
└── liveactivity/ # LiveActivityNotifier.kt, LiveActivityReceiver.kt (Android 8 -> 16 Live Update)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 3. Tài liệu API (Core API Reference)
|
|
230
|
+
|
|
231
|
+
```typescript
|
|
232
|
+
import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widgets';
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### 1. `LiveActivity` API
|
|
236
|
+
- `LiveActivity.start(options)`: Khởi chạy Live Activity (iOS) / Live Update Notification (Android). Trả về `{ activityId, activityPushToken }`.
|
|
237
|
+
- `LiveActivity.update(options)`: Cập nhật giao diện và nội dung mới cho `activityId`.
|
|
238
|
+
- `LiveActivity.end(activityId)`: Kết thúc 1 phiên đang chạy.
|
|
239
|
+
- `LiveActivity.endAll()`: Kết thúc toàn bộ các phiên đang chạy.
|
|
240
|
+
- `LiveActivity.registerForPushNotifications()`: Yêu cầu hệ điều hành cấp quyền thông báo và đăng ký APNs Device Token.
|
|
241
|
+
- `LiveActivity.getAllPushTokens(activityId?)`: Lấy trọn bộ 3 loại Push Token (`devicePushToken`, `pushToStartToken`, `activityUpdateToken`).
|
|
242
|
+
- `LiveActivity.getDevicePushToken()`: Lấy APNs Device Token (iOS) hoặc FCM Token đã lưu (Android).
|
|
243
|
+
- `LiveActivity.getPushToStartToken()`: Lấy APNs Push-to-Start Token (iOS 17.2+).
|
|
244
|
+
- `LiveActivity.getActivityPushToken(activityId?)`: Lấy APNs Activity Update Token của phiên đang chạy.
|
|
245
|
+
- `LiveActivity.setDevicePushToken(token)`: Lưu FCM Token trên Android vào bộ quản lý chung.
|
|
246
|
+
- `LiveActivity.onDevicePushTokenChange(cb)` / `onPushToStartTokenChange(cb)` / `onActivityUpdateTokenChange(cb)`: Lắng nghe sự kiện xoay token theo thời gian thực.
|
|
247
|
+
|
|
248
|
+
### 2. `Widget` API (Tiện ích Màn hình chính & Màn hình khóa)
|
|
249
|
+
- `Widget.setLayout(widgetKey, layoutConfig, appGroup?)`: Cập nhật giao diện động (`small`, `medium`, `large` cho Home Screen; `accessoryRectangular`, `accessoryCircular`, `accessoryInline` cho Lock Screen; `pages`, `initialPage` cho Widget đa trang). Tự động nén và tải trước toàn bộ ảnh từ URL mạng.
|
|
250
|
+
- `Widget.requestPin()`: *(Android 8.0+)* Mở hộp thoại hệ thống cho phép người dùng bấm ghim trực tiếp Tiện ích ra Màn hình chính ngay từ trong ứng dụng mà không cần ra launcher nhấn giữ kéo thả thủ công!
|
|
251
|
+
- `Widget.isPinSupported()`: Kiểm tra xem Launcher của thiết bị hiện tại có hỗ trợ ghim Tiện ích trực tiếp hay không.
|
|
252
|
+
- `Widget.setRemoteConfig(config, widgetKey?, appGroup?)`: Cấu hình URL API để Widget tự động gọi ngầm cập nhật dữ liệu mới kể cả khi người dùng đã vuốt tắt (Kill) App.
|
|
253
|
+
- `Widget.reloadAll()`: Yêu cầu iOS/Android vẽ lại toàn bộ Widget ngay lập tức.
|
|
254
|
+
- `Widget.reload(kind)`: Vẽ lại 1 Widget cụ thể.
|
|
255
|
+
- `Widget.getInteractiveState(widgetKey?, appGroup?)`: Đọc trạng thái tương tác hiện tại trên Widget (`activePage`, `toggledItems`, `lastSyncTime`, `remoteVariables`).
|
|
256
|
+
- `Widget.onWidgetAction(cb)`: Lắng nghe khi người dùng bấm nút trên Widget hoặc Notification.
|
|
257
|
+
|
|
258
|
+
### 3. `SharedStorage` API
|
|
259
|
+
- `SharedStorage.set(key, value, appGroup?)`: Lưu chuỗi hoặc JSON vào bộ nhớ chung App Group / SharedPreferences.
|
|
260
|
+
- `SharedStorage.get<T>(key, appGroup?)`: Đọc dữ liệu từ bộ nhớ chung.
|
|
261
|
+
- `SharedStorage.remove(key, appGroup?)`: Xóa 1 khóa.
|
|
262
|
+
- `SharedStorage.clear(appGroup?)`: Xóa sạch dữ liệu chung (dùng khi Logout).
|
|
263
|
+
|
|
264
|
+
### 4. `AudioPlayer` API (Phát nhạc & Kiểm thử sóng Equalizer)
|
|
265
|
+
- `AudioPlayer.play(url)`: Phát bài nhạc trực tiếp từ URL (`.mp3`, `.m4a`, `.aac`, `.wav`) qua loa máy (iOS `AVPlayer` / Android `MediaPlayer`).
|
|
266
|
+
- `AudioPlayer.pause()`: Tạm dừng bài nhạc.
|
|
267
|
+
- `AudioPlayer.resume()`: Tiếp tục phát bài nhạc.
|
|
268
|
+
- `AudioPlayer.stop()`: Dừng bài nhạc và giải phóng bộ nhớ.
|
|
269
|
+
- `AudioPlayer.getStatus()`: Lấy trạng thái phát (`{ isPlaying, currentTime, duration }`).
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## 4. Xây dựng Giao diện Động (Declarative UI Engine)
|
|
274
|
+
|
|
275
|
+
### `UI.StyleSheet` & Tái sử dụng Style (`StyleProp`)
|
|
276
|
+
Tương tự như `StyleSheet.create` trong React Native, bạn có thể gom nhóm các style định dạng lại để tái sử dụng nhiều nơi, giữ code sạch sẽ và hỗ trợ truyền mảng style có điều kiện:
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
import { UI } from 'react-native-live-widgets';
|
|
280
|
+
|
|
281
|
+
const styles = UI.StyleSheet.create({
|
|
282
|
+
card: {
|
|
283
|
+
padding: 14,
|
|
284
|
+
backgroundColor: '#0F172A',
|
|
285
|
+
borderRadius: 14,
|
|
286
|
+
spacing: 8,
|
|
287
|
+
},
|
|
288
|
+
headerText: {
|
|
289
|
+
fontSize: 10,
|
|
290
|
+
fontWeight: 'bold',
|
|
291
|
+
color: '#38BDF8',
|
|
292
|
+
},
|
|
293
|
+
titleText: {
|
|
294
|
+
fontSize: 15,
|
|
295
|
+
fontWeight: 'bold',
|
|
296
|
+
color: '#F8FAFC',
|
|
297
|
+
},
|
|
298
|
+
errorText: {
|
|
299
|
+
color: '#EF4444',
|
|
300
|
+
},
|
|
301
|
+
});
|
|
302
|
+
|
|
303
|
+
// Sử dụng đơn lẻ hoặc mảng có điều kiện (conditional styling):
|
|
304
|
+
UI.VStack(
|
|
305
|
+
styles.card,
|
|
306
|
+
UI.Text('TIÊU ĐỀ BÁO CÁO', styles.headerText),
|
|
307
|
+
UI.Text('Trạng thái ca làm', [styles.titleText, isError && styles.errorText])
|
|
308
|
+
);
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### `UI.VStack` & `UI.HStack`
|
|
312
|
+
Khối bố cục dọc (`VStack`) và ngang (`HStack`):
|
|
313
|
+
```typescript
|
|
314
|
+
UI.VStack(
|
|
315
|
+
{
|
|
316
|
+
padding: 14,
|
|
317
|
+
backgroundColor: '#1A1D24',
|
|
318
|
+
borderRadius: 16,
|
|
319
|
+
spacing: 8,
|
|
320
|
+
alignItems: 'leading', // 'leading' | 'center' | 'trailing'
|
|
321
|
+
},
|
|
322
|
+
// Các phần tử con...
|
|
323
|
+
)
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
### `UI.Text`
|
|
327
|
+
Hiển thị văn bản hỗ trợ tự động thay thế biến động `{{field}}` từ Background API và tự gạch ngang chữ khi gắn `strikethroughWhenToggled`:
|
|
328
|
+
```typescript
|
|
329
|
+
UI.Text('Check-in lúc {{checkinTime}}', {
|
|
330
|
+
color: '#FFFFFF',
|
|
331
|
+
fontSize: 15,
|
|
332
|
+
fontWeight: 'bold',
|
|
333
|
+
maxLines: 1,
|
|
334
|
+
strikethroughWhenToggled: 'task_1', // Tự động gạch ngang và làm mờ khi 'task_1' được tick!
|
|
335
|
+
})
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### `UI.Timer` (Realtime không tốn pin)
|
|
339
|
+
Đồng hồ đếm ngược (`countdown`) hoặc đếm lên (`countup`) tự chạy mượt mà trên cả Lock Screen, Dynamic Island và Home Screen Widget:
|
|
340
|
+
```typescript
|
|
341
|
+
UI.Timer(targetTimestampInSeconds, {
|
|
342
|
+
mode: 'countdown',
|
|
343
|
+
color: '#FFA500',
|
|
344
|
+
fontSize: 16,
|
|
345
|
+
fontWeight: 'bold',
|
|
346
|
+
showsHours: false, // Tắt hiển thị giờ để gọn gàng trên Dynamic Island Compact
|
|
347
|
+
})
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
### `UI.Progress` (Thanh tiến trình đa dạng)
|
|
351
|
+
Hỗ trợ 3 kiểu dáng: `'bar'` (thanh liền), `'segmented'` (thanh chia nhiều chặng kiểu giao hàng/ca làm việc), và `'circular'` (vòng tròn tiến độ):
|
|
352
|
+
```typescript
|
|
353
|
+
// 1. Thanh chia 4 chặng (Segmented)
|
|
354
|
+
UI.Progress({
|
|
355
|
+
style: 'segmented',
|
|
356
|
+
segments: 4,
|
|
357
|
+
currentSegment: 3, // Hoặc truyền value: 0.75
|
|
358
|
+
tintColor: '#10B981',
|
|
359
|
+
trackColor: '#374151',
|
|
360
|
+
segmentSpacing: 6,
|
|
361
|
+
height: 8,
|
|
362
|
+
})
|
|
363
|
+
|
|
364
|
+
// 2. Vòng tròn tiến độ (Circular)
|
|
365
|
+
UI.Progress({
|
|
366
|
+
style: 'circular',
|
|
367
|
+
value: 0.68,
|
|
368
|
+
tintColor: '#10B981',
|
|
369
|
+
trackColor: '#064E3B',
|
|
370
|
+
height: 64,
|
|
371
|
+
showPercentage: true,
|
|
372
|
+
})
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
### `UI.Equalizer` (Sóng nhạc chuyển động liên tục)
|
|
376
|
+
Component sóng nhạc / âm thanh động chuyên dụng. Trên Dynamic Island và Live Activity màn hình khóa (iOS), component tự động chạy nhịp sóng dao động liên tục thời gian thực (Native TimelineView Animation) mượt mà mà không tốn pin; trên Android và Home Screen hiển thị các thanh sóng nhạc trực quan:
|
|
377
|
+
```typescript
|
|
378
|
+
// 1. Dùng trong Dynamic Island (compactTrailing hoặc minimal)
|
|
379
|
+
UI.Equalizer({
|
|
380
|
+
isPlaying: true, // true: sóng nhảy liên tục | false: đứng yên
|
|
381
|
+
barCount: 4, // Số thanh sóng nhạc (2 đến 8)
|
|
382
|
+
tintColor: '#10B981', // Màu sắc thanh sóng (Spotify / Apple Music green)
|
|
383
|
+
height: 14, // Chiều cao thanh
|
|
384
|
+
barWidth: 3, // Độ rộng mỗi thanh
|
|
385
|
+
spacing: 2, // Khoảng cách giữa các thanh
|
|
386
|
+
})
|
|
387
|
+
|
|
388
|
+
// 2. Dùng trong Widget nghe nhạc ngoài Home Screen / Lock Screen
|
|
389
|
+
UI.Equalizer({
|
|
390
|
+
isPlaying: true,
|
|
391
|
+
barCount: 5,
|
|
392
|
+
tintColor: '#FFFFFF',
|
|
393
|
+
height: 18,
|
|
394
|
+
})
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
### `UI.Image` (URL mạng, Base64, File, Asset & SF Symbols)
|
|
398
|
+
Hỗ trợ truyền ảnh từ **5 nguồn khác nhau** trên cả iOS và Android. Khi truyền `url` (`https://...`), thư viện sẽ tự động tải ngầm, nén ảnh tối ưu RAM (`maxDimension = 360px` để không bao giờ vượt giới hạn 30MB của iOS WidgetKit) và lưu vào bộ nhớ đệm:
|
|
399
|
+
```typescript
|
|
400
|
+
// 1. Ảnh từ URL mạng (Avatar tròn có viền)
|
|
401
|
+
UI.Image({
|
|
402
|
+
url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=300&q=80',
|
|
403
|
+
width: 44,
|
|
404
|
+
height: 44,
|
|
405
|
+
cornerRadius: 999, // 999 = Bo tròn hoàn toàn (Circle)
|
|
406
|
+
contentMode: 'fill', // 'fill' | 'fit'
|
|
407
|
+
borderColor: '#60A5FA', // Màu viền
|
|
408
|
+
borderWidth: 2, // Độ dày viền
|
|
409
|
+
})
|
|
410
|
+
|
|
411
|
+
// 2. Ảnh từ chuỗi Base64 (QR Code, Barcode, Badge...)
|
|
412
|
+
UI.Image({
|
|
413
|
+
base64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...',
|
|
414
|
+
width: 36,
|
|
415
|
+
height: 36,
|
|
416
|
+
cornerRadius: 8,
|
|
417
|
+
})
|
|
418
|
+
|
|
419
|
+
// 3. Icon hệ thống (SF Symbols trên iOS / Vector Mapping trên Android)
|
|
420
|
+
UI.Image({
|
|
421
|
+
systemName: 'bicycle',
|
|
422
|
+
tintColor: '#FB923C',
|
|
423
|
+
width: 18,
|
|
424
|
+
height: 18,
|
|
425
|
+
})
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
### `UI.Button` (Nút bấm tương tác trực tiếp trên Widget)
|
|
429
|
+
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**:
|
|
430
|
+
```typescript
|
|
431
|
+
// 1. Nút chuyển sang trang/tab khác trên Widget
|
|
432
|
+
UI.Button({
|
|
433
|
+
title: 'Việc cần làm →',
|
|
434
|
+
actionId: 'page:tasks', // Hoặc 'page:next' / 'page:prev'
|
|
435
|
+
backgroundColor: '#2563EB',
|
|
436
|
+
color: '#FFFFFF',
|
|
437
|
+
fontSize: 11,
|
|
438
|
+
paddingHorizontal: 10,
|
|
439
|
+
paddingVertical: 5,
|
|
440
|
+
borderRadius: 8,
|
|
441
|
+
})
|
|
442
|
+
|
|
443
|
+
// 2. Nút Tick hoàn thành công việc ngay trên Widget
|
|
444
|
+
UI.Button({
|
|
445
|
+
title: 'Duyệt PR module chấm công',
|
|
446
|
+
actionId: 'toggle:task_1', // Tự động đổi [ ] <-> [✓]
|
|
447
|
+
backgroundColor: '#F8FAFC',
|
|
448
|
+
activeBackgroundColor: '#DCFCE7',
|
|
449
|
+
color: '#1E293B',
|
|
450
|
+
activeColor: '#15803D',
|
|
451
|
+
})
|
|
452
|
+
|
|
453
|
+
// 3. Nút gọi API làm mới dữ liệu ngầm ngay lập tức
|
|
454
|
+
UI.Button({
|
|
455
|
+
title: '↻ Làm mới',
|
|
456
|
+
actionId: 'refresh',
|
|
457
|
+
backgroundColor: '#1E293B',
|
|
458
|
+
color: '#60A5FA',
|
|
459
|
+
})
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Bố cục nâng cao)
|
|
463
|
+
```typescript
|
|
464
|
+
// 1. ZStack: Xếp chồng các lớp (Overlay)
|
|
465
|
+
UI.ZStack(
|
|
466
|
+
{ zAlignment: 'bottomTrailing' },
|
|
467
|
+
UI.Image('https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200', { width: 44, height: 44, borderRadius: 22 }),
|
|
468
|
+
UI.Badge('●', { backgroundColor: '#10B981', textColor: '#FFFFFF', fontSize: 8 })
|
|
469
|
+
)
|
|
470
|
+
|
|
471
|
+
// 2. Grid: Chia lưới nhiều cột đều nhau (Bảng thống kê 2x2 KPI)
|
|
472
|
+
UI.Grid(
|
|
473
|
+
{ columns: 2, columnSpacing: 8, rowSpacing: 8 },
|
|
474
|
+
UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Doanh thu', { fontSize: 10, color: '#94A3B8' }), UI.Text('4.85 Tỷ', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' })),
|
|
475
|
+
UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Đơn hàng', { fontSize: 10, color: '#94A3B8' }), UI.Text('1,420', { fontSize: 14, fontWeight: 'bold', color: '#34D399' }))
|
|
476
|
+
)
|
|
477
|
+
|
|
478
|
+
// 3. Divider: Đường kẻ phân cách ngang/dọc
|
|
479
|
+
UI.Divider({ color: '#334155', thickness: 1, marginVertical: 4 })
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
### `UI.Gauge` & `UI.Chart` (Đồng hồ đo KPI & Biểu đồ Cột / Đường Sparkline)
|
|
483
|
+
```typescript
|
|
484
|
+
// 1. Đồng hồ đo tốc độ / KPI cung tròn 240° (Gauge)
|
|
485
|
+
UI.Gauge(0.86, {
|
|
486
|
+
size: 66,
|
|
487
|
+
tintColor: '#38BDF8',
|
|
488
|
+
trackColor: '#1E293B',
|
|
489
|
+
textColor: '#F8FAFC',
|
|
490
|
+
labelColor: '#94A3B8',
|
|
491
|
+
valueText: '86%',
|
|
492
|
+
label: 'KPI Quý',
|
|
493
|
+
})
|
|
494
|
+
|
|
495
|
+
// 2. Biểu đồ Cột ('bar') hoặc Đường xu hướng ('line')
|
|
496
|
+
UI.Chart([42, 58, 51, 74, 68, 92, 108], {
|
|
497
|
+
style: 'bar', // 'bar' | 'line'
|
|
498
|
+
labels: ['T2', 'T3', 'T4', 'T5', 'T6', 'T7', 'CN'],
|
|
499
|
+
tintColor: '#38BDF8',
|
|
500
|
+
secondaryColor: '#1E3A8A',
|
|
501
|
+
labelColor: '#94A3B8',
|
|
502
|
+
height: 48,
|
|
503
|
+
})
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
### `UI.Toggle`, `UI.Badge` & `UI.Link`
|
|
507
|
+
```typescript
|
|
508
|
+
// 1. Toggle: Ô tích Checkbox hoặc Công tắc gạt Switch ngay trên mặt Widget
|
|
509
|
+
UI.Toggle('Duyệt báo cáo doanh thu tuần', {
|
|
510
|
+
actionId: 'toggle:kpi_approve',
|
|
511
|
+
style: 'checkbox', // 'checkbox' | 'switch'
|
|
512
|
+
tintColor: '#38BDF8',
|
|
513
|
+
textColor: '#F8FAFC',
|
|
514
|
+
})
|
|
515
|
+
|
|
516
|
+
// 2. Badge: Nhãn trạng thái dạng viên thuốc (Pill / Capsule)
|
|
517
|
+
UI.Badge('+18% Vượt chỉ tiêu', {
|
|
518
|
+
backgroundColor: '#064E3B',
|
|
519
|
+
textColor: '#34D399',
|
|
520
|
+
fontSize: 10,
|
|
521
|
+
})
|
|
522
|
+
|
|
523
|
+
// 3. Link: Biến cả một khối giao diện thành vùng bấm mở Deep Link hoặc chạy Action
|
|
524
|
+
UI.Link(
|
|
525
|
+
{ deepLink: 'livewidgets://analytics/q4', padding: 10, backgroundColor: '#1E293B', borderRadius: 10 },
|
|
526
|
+
UI.Text('Xem chi tiết báo cáo →', { fontSize: 12, fontWeight: 'bold', color: '#38BDF8' })
|
|
527
|
+
)
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
### `UI.Custom` & `DynamicNodeRegistry` (Tự mở rộng Component Native tùy ý bằng Swift / Kotlin)
|
|
531
|
+
Nếu bạn muốn tự viết một Component riêng bằng **SwiftUI** hoặc **Kotlin Canvas** mà không cần sửa code lõi của thư viện:
|
|
532
|
+
|
|
533
|
+
1. **Đăng ký bên iOS (Swift — trong `LiveWidgetsBundle.swift`):**
|
|
534
|
+
```swift
|
|
535
|
+
import SwiftUI
|
|
536
|
+
import react_native_live_widgets
|
|
537
|
+
|
|
538
|
+
// Đăng ký Custom View theo tên "WeatherCard"
|
|
539
|
+
DynamicNodeRegistry.shared.registerView("WeatherCard") { node in
|
|
540
|
+
let city = node.props?["city"]?.stringValue ?? "Hà Nội"
|
|
541
|
+
let temp = node.props?["temp"]?.stringValue ?? "28°C"
|
|
542
|
+
HStack {
|
|
543
|
+
Image(systemName: "sun.max.fill").foregroundColor(.yellow)
|
|
544
|
+
Text("\(city): \(temp)").font(.headline)
|
|
545
|
+
}
|
|
546
|
+
}
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
2. **Đăng ký bên Android (Kotlin — trong `MainApplication.onCreate()`):**
|
|
550
|
+
```kotlin
|
|
551
|
+
import com.reactnativeliveactivity.DynamicNodeRegistry
|
|
552
|
+
|
|
553
|
+
DynamicNodeRegistry.register(
|
|
554
|
+
componentName = "WeatherCard",
|
|
555
|
+
heightDp = { 44f },
|
|
556
|
+
drawer = { context, canvas, rect, props, density ->
|
|
557
|
+
// Tự vẽ tự do lên Android Canvas
|
|
558
|
+
}
|
|
559
|
+
)
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
3. **Gọi trực tiếp từ React Native (`App.tsx`):**
|
|
563
|
+
```typescript
|
|
564
|
+
UI.Custom('WeatherCard', { city: 'TP.HCM', temp: '31°C' })
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
---
|
|
568
|
+
|
|
569
|
+
## 5. Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)
|
|
570
|
+
|
|
571
|
+
```typescript
|
|
572
|
+
dynamicIsland: {
|
|
573
|
+
compactLeading: UI.HStack(
|
|
574
|
+
{ spacing: 4 },
|
|
575
|
+
UI.Image({
|
|
576
|
+
url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200&q=80',
|
|
577
|
+
width: 18,
|
|
578
|
+
height: 18,
|
|
579
|
+
cornerRadius: 999,
|
|
580
|
+
}),
|
|
581
|
+
UI.Text('08:02', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' })
|
|
582
|
+
),
|
|
583
|
+
compactTrailing: UI.Timer(shiftEndTimestamp, {
|
|
584
|
+
mode: 'countdown',
|
|
585
|
+
color: '#60A5FA',
|
|
586
|
+
fontSize: 12,
|
|
587
|
+
fontWeight: 'bold',
|
|
588
|
+
showsHours: false,
|
|
589
|
+
}),
|
|
590
|
+
minimal: UI.Image({ systemName: 'clock.fill', tintColor: '#60A5FA', width: 14, height: 14 }),
|
|
591
|
+
expanded: {
|
|
592
|
+
leading: UI.Text('ĐANG TRONG CA', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' }),
|
|
593
|
+
trailing: UI.Timer(shiftEndTimestamp, { mode: 'countdown', color: '#FFFFFF', fontSize: 14, fontWeight: 'bold' }),
|
|
594
|
+
bottom: UI.VStack(
|
|
595
|
+
{ spacing: 6 },
|
|
596
|
+
UI.Progress({ style: 'segmented', segments: 4, value: 0.75, tintColor: '#3B82F6', height: 6 }),
|
|
597
|
+
UI.Text('Check-in: Văn phòng Quận 1', { color: '#94A3B8', fontSize: 11 })
|
|
598
|
+
),
|
|
599
|
+
},
|
|
600
|
+
}
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
---
|
|
604
|
+
|
|
605
|
+
## 6. Tạo Home Screen Widget Đa Trang & Tương Tác bằng JavaScript
|
|
606
|
+
|
|
607
|
+
Bạn có thể truyền thuộc tính `pages` vào `Widget.setLayout` để tạo nhiều màn hình (Tabs/Pages) ngay bên trong 1 Widget duy nhất:
|
|
608
|
+
|
|
609
|
+
```typescript
|
|
610
|
+
await Widget.setLayout('main', {
|
|
611
|
+
initialPage: 'overview',
|
|
612
|
+
// Mặc định (trang Tổng quan)
|
|
613
|
+
medium: overviewPageNode,
|
|
614
|
+
// Khai báo các trang để chuyển qua lại bằng actionId: 'page:<tên_trang>'
|
|
615
|
+
pages: {
|
|
616
|
+
overview: {
|
|
617
|
+
small: overviewSmallNode,
|
|
618
|
+
medium: overviewMediumNode,
|
|
619
|
+
large: overviewLargeNode,
|
|
620
|
+
},
|
|
621
|
+
tasks: {
|
|
622
|
+
small: tasksSmallNode,
|
|
623
|
+
medium: tasksMediumNode,
|
|
624
|
+
large: tasksLargeNode,
|
|
625
|
+
},
|
|
626
|
+
stats: {
|
|
627
|
+
small: statsSmallNode,
|
|
628
|
+
medium: statsMediumNode,
|
|
629
|
+
large: statsLargeNode,
|
|
630
|
+
},
|
|
631
|
+
},
|
|
632
|
+
});
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
### Lock Screen Widgets trên iOS
|
|
636
|
+
Từ iOS 16+, WidgetKit hỗ trợ 3 kích thước đặc biệt trên màn hình khóa (Lock Screen):
|
|
637
|
+
- `accessoryRectangular`: Khung chữ nhật nằm ngang phía dưới đồng hồ.
|
|
638
|
+
- `accessoryCircular`: Biểu tượng / chỉ số tròn nhỏ.
|
|
639
|
+
- `accessoryInline`: Dòng chữ vắn tắt nằm ngay phía trên đồng hồ.
|
|
640
|
+
|
|
641
|
+
> [!NOTE]
|
|
642
|
+
> Thư viện tự động loại bỏ nền opaque (`backgroundColor`) và căn chỉnh padding chuẩn xác để widget màn hình khóa hiển thị tự nhiên với hệ số trong suốt (vibrancy) của iOS.
|
|
643
|
+
|
|
644
|
+
```typescript
|
|
645
|
+
await Widget.setLayout('main', {
|
|
646
|
+
// Widget Home Screen
|
|
647
|
+
small: smallNode,
|
|
648
|
+
medium: mediumNode,
|
|
649
|
+
large: largeNode,
|
|
650
|
+
|
|
651
|
+
// Widget Lock Screen (iOS 16+)
|
|
652
|
+
accessoryRectangular: UI.HStack(
|
|
653
|
+
{ spacing: 6 },
|
|
654
|
+
UI.VStack(
|
|
655
|
+
{ spacing: 2 },
|
|
656
|
+
UI.Text('Starboy', { fontSize: 13, fontWeight: 'bold', color: '#FFFFFF' }),
|
|
657
|
+
UI.Text('The Weeknd', { fontSize: 11, color: '#CCCCCC' })
|
|
658
|
+
),
|
|
659
|
+
UI.Spacer(),
|
|
660
|
+
UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 16 })
|
|
661
|
+
),
|
|
662
|
+
accessoryCircular: UI.VStack(
|
|
663
|
+
{ spacing: 2 },
|
|
664
|
+
UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 18 }),
|
|
665
|
+
UI.Text('MUSIC', { fontSize: 8, fontWeight: 'bold', color: '#FFFFFF' })
|
|
666
|
+
),
|
|
667
|
+
accessoryInline: UI.Text('♪ Starboy • The Weeknd', { fontSize: 12, fontWeight: 'medium' }),
|
|
668
|
+
});
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
### Ghim Tiện ích vào Màn hình chính trong App (Android In-App Pin)
|
|
672
|
+
Trên Android 8.0+ (API 26+), bạn có thể hiển thị nút trong ứng dụng để người dùng bấm ghim ngay tiện ích ra màn hình chính mà không cần hướng dẫn người dùng nhấn giữ màn hình thủ công:
|
|
673
|
+
|
|
674
|
+
```typescript
|
|
675
|
+
import { Widget } from 'react-native-live-widgets';
|
|
676
|
+
|
|
677
|
+
// Kiểm tra xem Launcher hiện tại có hỗ trợ ghim hay không
|
|
678
|
+
const isSupported = await Widget.isPinSupported();
|
|
679
|
+
|
|
680
|
+
if (isSupported) {
|
|
681
|
+
// Yêu cầu hệ điều hành hiện hộp thoại ghim Widget
|
|
682
|
+
const success = await Widget.requestPin();
|
|
683
|
+
if (success) {
|
|
684
|
+
console.log('Hệ thống đã nhận yêu cầu ghim tiện ích');
|
|
685
|
+
}
|
|
686
|
+
}
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
---
|
|
690
|
+
|
|
691
|
+
## 7. Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)
|
|
692
|
+
|
|
693
|
+
Khi ứng dụng bị người dùng vuốt tắt hoàn toàn (Kill App), JavaScript thread của React Native sẽ dừng. Để Widget vẫn luôn có dữ liệu mới từ Server:
|
|
694
|
+
|
|
695
|
+
```typescript
|
|
696
|
+
await Widget.setRemoteConfig({
|
|
697
|
+
url: 'https://api.yourcompany.com/v1/widget-summary',
|
|
698
|
+
method: 'GET',
|
|
699
|
+
headers: {
|
|
700
|
+
Authorization: `Bearer ${accessToken}`,
|
|
701
|
+
},
|
|
702
|
+
intervalMinutes: 15, // Tự động đồng bộ mỗi 15 phút ở tầng OS (WidgetKit Timeline / Android AlarmManager)
|
|
703
|
+
});
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
- **Cách hoạt động:**
|
|
707
|
+
- Trên **iOS**: `DynamicWidgetProvider` tự động gọi API ngầm mỗi `intervalMinutes` (hoặc ngay lập tức khi bấm nút `actionId: 'refresh'`), lấy JSON trả về và điền vào các biến `{{ten_bien}}` trong cây UI DSL.
|
|
708
|
+
- Trên **Android**: `AlarmManager` tự động đánh thức `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), tải JSON mới và vẽ lại `DynamicHomeScreenWidgetProvider`.
|
|
709
|
+
- Biến đặc biệt `{{_lastSyncTime}}` luôn tự động cập nhật thành giờ đồng bộ mới nhất (`HH:mm:ss`).
|
|
710
|
+
|
|
711
|
+
---
|
|
712
|
+
|
|
713
|
+
## 8. Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity
|
|
714
|
+
|
|
715
|
+
Để hệ thống Backend có thể điều khiển Live Activity từ xa:
|
|
716
|
+
1. **`devicePushToken`**: APNs Device Token (iOS) / FCM Token (Android) cho thông báo đẩy thường.
|
|
717
|
+
2. **`pushToStartToken` (iOS 17.2+)**: Token cho phép Server tự bật mới một Live Activity từ xa khi App đang tắt.
|
|
718
|
+
3. **`activityUpdateToken`**: Token riêng của từng phiên Live Activity đang chạy để Server đẩy bản cập nhật hoặc kết thúc phiên đó.
|
|
719
|
+
|
|
720
|
+
```typescript
|
|
721
|
+
// 1. Xin quyền và đăng ký nhận token
|
|
722
|
+
await LiveActivity.registerForPushNotifications();
|
|
723
|
+
|
|
724
|
+
// 2. Lấy toàn bộ 3 loại token hiện có
|
|
725
|
+
const tokens = await LiveActivity.getAllPushTokens();
|
|
726
|
+
console.log(tokens.devicePushToken, tokens.pushToStartToken, tokens.activityUpdateToken);
|
|
727
|
+
|
|
728
|
+
// 3. Lắng nghe token mới được cấp hoặc xoay tự động
|
|
729
|
+
const sub1 = LiveActivity.onDevicePushTokenChange(({ token }) => {
|
|
730
|
+
api.syncDeviceToken(token);
|
|
731
|
+
});
|
|
732
|
+
const sub2 = LiveActivity.onPushToStartTokenChange((token) => {
|
|
733
|
+
api.syncPushToStartToken(token);
|
|
734
|
+
});
|
|
735
|
+
const sub3 = LiveActivity.onActivityUpdateTokenChange(({ activityId, token }) => {
|
|
736
|
+
api.syncActivityUpdateToken(activityId, token);
|
|
737
|
+
});
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
---
|
|
741
|
+
|
|
742
|
+
## 9. State Machine & Tự động cập nhật theo pha (Phases)
|
|
743
|
+
|
|
744
|
+
```typescript
|
|
745
|
+
phases: [
|
|
746
|
+
{
|
|
747
|
+
id: 'warning_phase',
|
|
748
|
+
triggerTimestamp: targetTimestamp - 300, // Trước 5 phút
|
|
749
|
+
alertTitle: 'Sắp trễ ca!',
|
|
750
|
+
alertBody: 'Chỉ còn 5 phút nữa là vào ca làm!',
|
|
751
|
+
},
|
|
752
|
+
{
|
|
753
|
+
id: 'late_phase',
|
|
754
|
+
triggerTimestamp: targetTimestamp, // Đã đến giờ
|
|
755
|
+
alertTitle: 'Đã trễ ca!',
|
|
756
|
+
alertBody: 'Bạn đã quá giờ ca làm việc!',
|
|
757
|
+
},
|
|
758
|
+
]
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
---
|
|
762
|
+
|
|
763
|
+
## 10. Cấu trúc Payload Server Push (APNs & FCM)
|
|
764
|
+
|
|
765
|
+
### Headers gửi lên APNs (iOS Live Activity):
|
|
766
|
+
- `apns-push-type`: `liveactivity`
|
|
767
|
+
- `apns-topic`: `<bundle_id>.push-type.liveactivity`
|
|
768
|
+
- `apns-priority`: `10`
|
|
769
|
+
|
|
770
|
+
### Body JSON gửi lên APNs:
|
|
771
|
+
```json
|
|
772
|
+
{
|
|
773
|
+
"aps": {
|
|
774
|
+
"timestamp": 1711890000,
|
|
775
|
+
"event": "update",
|
|
776
|
+
"content-state": {
|
|
777
|
+
"layoutJson": "{\"lockScreen\":{...},\"dynamicIsland\":{...}}"
|
|
778
|
+
},
|
|
779
|
+
"alert": {
|
|
780
|
+
"title": "Đơn hàng đã giao!",
|
|
781
|
+
"body": "Chúc bạn ngon miệng."
|
|
782
|
+
}
|
|
783
|
+
}
|
|
784
|
+
}
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
---
|
|
788
|
+
|
|
789
|
+
## 11. Xử lý sự cố thường gặp (Troubleshooting)
|
|
790
|
+
|
|
791
|
+
1. **Widget ngoài màn hình chính hiển thị chữ "Chọn 1 mẫu UI trong app để hiển thị":**
|
|
792
|
+
- Kiểm tra App Group ID giữa Main App và Widget Extension đã khớp nhau chưa (mặc định thư viện tự động dò `group.<bundle_id>`).
|
|
793
|
+
- Đảm bảo đã gọi `await Widget.setLayout('main', ...)` trong code React Native.
|
|
794
|
+
2. **Dynamic Island Compact bị tràn chiều ngang khi dùng `UI.Timer`:**
|
|
795
|
+
- Truyền `showsHours: false` vào `UI.Timer` ở `compactTrailing`. Thư viện đã tự động giới hạn khung `compactWidth` để không làm giãn viên thuốc Dynamic Island.
|
|
796
|
+
3. **Ảnh từ URL mạng (`https://...`) không hiện trên Widget:**
|
|
797
|
+
- Đảm bảo URL ảnh là `https://` hợp lệ. Thư viện sẽ tự động tải, nén xuống `360px` và reload lại Widget ngay khi tải xong.
|
|
798
|
+
|
|
799
|
+
---
|
|
800
|
+
|
|
801
|
+
## 📄 License
|
|
802
|
+
MIT © vu-tran
|