react-native-live-widgets 1.2.0 → 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 +34 -0
- package/README.md +129 -50
- 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 +529 -59
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +53 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +684 -83
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +129 -57
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicQuickSettingsTileService.kt +120 -0
- package/android/src/main/res/layout/rn_live_widget_hit_zone.xml +16 -0
- package/android/src/main/res/layout/rn_live_widget_host.xml +16 -87
- 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 +444 -21
- package/docs/GUIDE-VI.md +473 -22
- package/docs/index.html +2263 -265
- package/docs/llms-full.txt +41 -0
- package/docs/llms.txt +24 -7
- package/ios/Bridge/LiveActivityModule.swift +333 -44
- package/ios/Intents/DynamicWidgetActionIntent.swift +57 -2
- package/ios/Models/DynamicLayoutModels.swift +120 -5
- package/ios/Renderer/DynamicNodeView.swift +184 -20
- package/ios/Storage/DynamicWidgetStateStore.swift +649 -38
- package/ios/Widgets/DynamicControlWidget.swift +63 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +104 -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 +391 -29
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.js +16 -10
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.d.ts +13 -9
- package/lib/hooks.d.ts.map +1 -1
- package/lib/hooks.js +105 -42
- package/lib/hooks.js.map +1 -1
- package/lib/index.d.ts +96 -8
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +415 -97
- package/lib/index.js.map +1 -1
- package/lib/ir.d.ts +15 -0
- package/lib/ir.d.ts.map +1 -0
- package/lib/ir.js +386 -0
- package/lib/ir.js.map +1 -0
- package/lib/jsx.d.ts +19 -7
- package/lib/jsx.d.ts.map +1 -1
- package/lib/jsx.js +179 -95
- 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 -27
- package/lib/preview.d.ts.map +1 -1
- package/lib/preview.js +456 -119
- 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 +506 -30
- package/lib/types.d.ts.map +1 -1
- package/lib/types.js +2 -1
- package/lib/types.js.map +1 -1
- package/package.json +7 -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 +439 -26
- package/src/hooks.ts +88 -12
- package/src/index.ts +385 -57
- package/src/ir.ts +436 -0
- package/src/jsx.tsx +99 -21
- package/src/material-icons.generated.ts +3844 -0
- package/src/preview.tsx +533 -55
- package/src/react-native-env.d.ts +1 -0
- package/src/sf-symbols.generated.ts +9533 -0
- package/src/types.ts +601 -31
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
|
|
@@ -943,5 +983,416 @@ phases: [
|
|
|
943
983
|
|
|
944
984
|
---
|
|
945
985
|
|
|
986
|
+
---
|
|
987
|
+
|
|
988
|
+
## 12. Hệ thống Styling Modifiers & Bảng Năng lực Nền tảng (Capability & Fallback Matrix)
|
|
989
|
+
|
|
990
|
+
### 12.1. Styling Modifiers nâng cao
|
|
991
|
+
Bộ thuộc tính thiết kế nền tảng giúp Widget và Live Activity đạt chuẩn giao diện iOS & Android chuyên nghiệp:
|
|
992
|
+
|
|
993
|
+
1. **🌈 Gradient (Dải màu chuyển sắc)**:
|
|
994
|
+
```tsx
|
|
995
|
+
<VStack
|
|
996
|
+
gradient={{
|
|
997
|
+
colors: ['#1E3A8A', '#3B82F6'],
|
|
998
|
+
startPoint: { x: 0, y: 0 },
|
|
999
|
+
endPoint: { x: 1, y: 1 },
|
|
1000
|
+
angle: 45
|
|
1001
|
+
}}
|
|
1002
|
+
padding={16}
|
|
1003
|
+
>
|
|
1004
|
+
<Text typography="headline" color="#FFFFFF">Thẻ chuyển sắc</Text>
|
|
1005
|
+
</VStack>
|
|
1006
|
+
```
|
|
1007
|
+
> [!TIP]
|
|
1008
|
+
> **Graceful Fallback**: Nếu hệ điều hành hoặc thiết bị cũ không hỗ trợ vẽ gradient, engine tự động lấy màu đầu tiên trong danh sách `colors` làm màu nền đơn sắc (`backgroundColor`) thay thế, hoàn toàn không gây lỗi giao diện.
|
|
1009
|
+
|
|
1010
|
+
2. **🔲 Border & Dashed Lines (Đường viền nét đứt)**:
|
|
1011
|
+
```tsx
|
|
1012
|
+
<VStack
|
|
1013
|
+
borderWidth={1.5}
|
|
1014
|
+
borderColor="#38BDF8"
|
|
1015
|
+
borderStyle="dashed"
|
|
1016
|
+
borderRadius={12}
|
|
1017
|
+
padding={12}
|
|
1018
|
+
>
|
|
1019
|
+
<Text fontSize={12} color="#94A3B8">Khu vực kéo thả hoặc ghi chú</Text>
|
|
1020
|
+
</VStack>
|
|
1021
|
+
```
|
|
1022
|
+
|
|
1023
|
+
3. **🌑 Shadow (Đổ bóng có chiều sâu)**:
|
|
1024
|
+
```tsx
|
|
1025
|
+
<Button
|
|
1026
|
+
title="Xác nhận"
|
|
1027
|
+
backgroundColor="#2563EB"
|
|
1028
|
+
shadowColor="#2563EB"
|
|
1029
|
+
shadowRadius={6}
|
|
1030
|
+
shadowOpacity={0.4}
|
|
1031
|
+
shadowOffset={{ x: 0, y: 3 }}
|
|
1032
|
+
/>
|
|
1033
|
+
```
|
|
1034
|
+
|
|
1035
|
+
4. **🔤 Typography & Dynamic Type (Cỡ chữ chuẩn & Trợ năng)**:
|
|
1036
|
+
- Các bậc cỡ chữ chuẩn: `largeTitle` (34), `title1` (28), `title2` (22), `title3` (20), `headline` (17 bold), `body` (17 regular), `callout` (16), `subheadline` (15), `footnote` (13), `caption1` (12), `caption2` (11).
|
|
1037
|
+
- `fontDesign`: `'default' | 'monospaced' | 'rounded' | 'serif'`.
|
|
1038
|
+
- `dynamicType`: Mặc định `true` — tự động co giãn theo cỡ chữ Trợ năng mà người dùng cài đặt trong Cài đặt hệ thống (Accessibility Font Size).
|
|
1039
|
+
|
|
1040
|
+
5. **🌗 Tinted / Dark Mode (Chế độ đổi màu iOS 18 & Material You)**:
|
|
1041
|
+
```tsx
|
|
1042
|
+
<Text color={{ light: '#0F172A', dark: '#F8FAFC', tinted: '#38BDF8' }}>
|
|
1043
|
+
Nội dung tự thích ứng màu sắc
|
|
1044
|
+
</Text>
|
|
1045
|
+
```
|
|
1046
|
+
|
|
1047
|
+
6. **🌍 Hỗ trợ bố cục quốc tế hoá RTL**:
|
|
1048
|
+
```tsx
|
|
1049
|
+
<HStack direction="rtl" isRTL={true} spacing={8}>
|
|
1050
|
+
<Text>مرحبا بك</Text>
|
|
1051
|
+
</HStack>
|
|
1052
|
+
```
|
|
1053
|
+
|
|
1054
|
+
---
|
|
1055
|
+
|
|
1056
|
+
### 12.2. Bảng Tra cứu Năng lực Nền tảng (Platform Capability & Fallback Matrix)
|
|
1057
|
+
|
|
1058
|
+
Thay vì tuyên bố chung chung "100% parity", engine phân định rõ ràng các tính năng thực tế được hỗ trợ trên từng hệ điều hành và cơ chế tự động chuyển đổi an toàn (Graceful Fallback):
|
|
1059
|
+
|
|
1060
|
+
| Tính năng / Thuộc tính | iOS WidgetKit | iOS Live Activity | Android Ongoing Notification | Android Home Widget | Cơ chế Graceful Fallback khi không hỗ trợ |
|
|
1061
|
+
| :--- | :---: | :---: | :---: | :---: | :--- |
|
|
1062
|
+
| **Bố cục Khai báo (`VStack`/`HStack`/`Grid`)** | ✅ SwiftUI | ✅ SwiftUI | ✅ Canvas | ✅ 2D Canvas | Tương thích pixel 100% hai hệ máy |
|
|
1063
|
+
| **Linear / Radial Gradient** | ✅ SwiftUI | ✅ SwiftUI | ✅ Shader | ✅ Shader | Tự động lấy màu đầu tiên trong `colors` làm màu nền đơn sắc |
|
|
1064
|
+
| **Bóng đổ Thẻ / Chữ (Shadow)** | ✅ SwiftUI | ✅ SwiftUI | ⚠️ Text Shadow | ✅ `setShadowLayer` | Tự động hạ cấp sang viền mỏng hoặc Android Elevation |
|
|
1065
|
+
| **Viền nét đứt (Dashed / Dotted)** | ✅ StrokeStyle | ✅ StrokeStyle | ⚠️ Nét liền | ✅ `DashPathEffect` | Tự động hiển thị viền nét liền `solid` |
|
|
1066
|
+
| **Dynamic Type (Cỡ chữ Trợ năng)** | ✅ Native | ✅ Native | ✅ `fontScale` | ✅ `fontScale` | Tự động nhân tỉ lệ fontScale của hệ điều hành |
|
|
1067
|
+
| **Đảo chiều RTL (Ả Rập, Hebrew)** | ✅ Native | ✅ Native | ✅ RTL | ✅ RTL | Tự động đảo thứ tự hàng ngang sang `row-reverse` |
|
|
1068
|
+
| **Accessibility (TalkBack / VoiceOver)** | ✅ Native VoiceOver | ✅ Native VoiceOver | ✅ Notification Text | ✅ A11y Summary + Hit-Zones | Tổng hợp ngữ nghĩa toàn cây gán vào `contentDescription` |
|
|
1069
|
+
| **Chế độ Tinted (iOS 18+)** | ✅ Accentable | Không áp dụng | Không áp dụng | ✅ Material You | Tự động dùng màu `dark`/`light` trên iOS 17 trở xuống |
|
|
1070
|
+
| **Nút bấm tương tác chạy ngầm** | ✅ iOS 17+ AppIntent | ✅ iOS 17+ | ✅ PendingIntent | ✅ PendingIntent | Lưu trạng thái SharedStorage và kích hoạt làm mới giao diện |
|
|
1071
|
+
|
|
1072
|
+
---
|
|
1073
|
+
|
|
1074
|
+
### 12.3. ♿ Lớp Trợ năng & Ngữ nghĩa (Accessibility Fallback Layer)
|
|
1075
|
+
|
|
1076
|
+
Để đảm bảo người khiếm thị hoặc người sử dụng công cụ đọc màn hình (**VoiceOver trên iOS**, **TalkBack trên Android**) tiếp cận được đầy đủ thông tin trên Widget, engine cung cấp các thuộc tính Trợ năng chuẩn:
|
|
1077
|
+
|
|
1078
|
+
```tsx
|
|
1079
|
+
<VStack padding={16} backgroundColor="#0F172A">
|
|
1080
|
+
{/* Tiêu đề với vai trò Header */}
|
|
1081
|
+
<Text
|
|
1082
|
+
typography="title2"
|
|
1083
|
+
accessibilityRole="header"
|
|
1084
|
+
accessibilityLabel="Bảng điều khiển chấm công"
|
|
1085
|
+
>
|
|
1086
|
+
BẢNG ĐIỀU KHIỂN CHẤM CÔNG
|
|
1087
|
+
</Text>
|
|
1088
|
+
|
|
1089
|
+
{/* Chỉ số tiến độ với nhãn và giá trị âm thanh */}
|
|
1090
|
+
<Progress
|
|
1091
|
+
value={0.86}
|
|
1092
|
+
accessibilityLabel="Tiến độ hoàn thành ca làm việc"
|
|
1093
|
+
accessibilityValue="86 phần trăm"
|
|
1094
|
+
/>
|
|
1095
|
+
|
|
1096
|
+
{/* Nút bấm với nhãn và gợi ý hành động */}
|
|
1097
|
+
<Button
|
|
1098
|
+
title="Check-in vào ca"
|
|
1099
|
+
actionId="CHECK_IN"
|
|
1100
|
+
accessibilityRole="button"
|
|
1101
|
+
accessibilityLabel="Check-in vào ca"
|
|
1102
|
+
accessibilityHint="Chạm hai lần để gửi yêu cầu chấm công"
|
|
1103
|
+
/>
|
|
1104
|
+
|
|
1105
|
+
{/* Phần tử trang trí (không đọc lên TalkBack/VoiceOver) */}
|
|
1106
|
+
<Image systemName="sparkles" accessible={false} />
|
|
1107
|
+
</VStack>
|
|
1108
|
+
```
|
|
1109
|
+
|
|
1110
|
+
#### Cơ chế hoạt động của Accessibility Fallback Layer (Phase 1):
|
|
1111
|
+
1. **Trên iOS**: Map trực tiếp sang SwiftUI `.accessibilityLabel()`, `.accessibilityHint()`, `.accessibilityValue()`, `.accessibilityAddTraits()`. Nếu `accessible={false}`, áp dụng `.accessibilityHidden(true)`.
|
|
1112
|
+
2. **Trên Android (Canvas 2D)**:
|
|
1113
|
+
- Toàn bộ cây DSL được duyệt đệ quy để trích xuất một bản tóm tắt âm thanh thông minh (`extractAccessibilitySummary`) và gán vào `contentDescription` của Canvas `ImageView`.
|
|
1114
|
+
- Các nút bấm tương tác (Hit-Zones) được gán `contentDescription` riêng rẽ kèm `accessibilityHint`, giúp TalkBack phát âm chuẩn xác khi người dùng chạm vào từng nút.
|
|
1115
|
+
3. **Trong In-App Preview**: Tự động ánh xạ sang `accessible`, `accessibilityLabel`, `accessibilityHint`, `accessibilityRole` của React Native Web/Mobile.
|
|
1116
|
+
|
|
1117
|
+
---
|
|
1118
|
+
|
|
1119
|
+
### 12.4. Kiểm tra năng lực thiết bị qua code (`Widget.getCapabilities`)
|
|
1120
|
+
```typescript
|
|
1121
|
+
const caps = await Widget.getCapabilities();
|
|
1122
|
+
console.log(`Đang chạy trên: ${caps.platform} (OS: ${caps.osVersion})`);
|
|
1123
|
+
|
|
1124
|
+
if (caps.supportsDynamicIsland) {
|
|
1125
|
+
console.log('Thiết bị có Dynamic Island (iPhone 14 Pro/15/16)!');
|
|
1126
|
+
}
|
|
1127
|
+
|
|
1128
|
+
if (caps.supportsTintedMode) {
|
|
1129
|
+
console.log('Hỗ trợ chế độ Tinted Home Screen của iOS 18!');
|
|
1130
|
+
}
|
|
1131
|
+
```
|
|
1132
|
+
|
|
1133
|
+
---
|
|
1134
|
+
|
|
1135
|
+
### 12.5. 🌲 UI Intermediate Representation (IR) & Semantic Tree (Phase 2)
|
|
1136
|
+
|
|
1137
|
+
Thay vì đi thẳng từ `DSL ➔ Canvas Bitmap`, kiến trúc v1.2 giới thiệu tầng **UI Intermediate Representation (IR)** và bộ điều phối **Renderer Planner**:
|
|
1138
|
+
|
|
1139
|
+
```
|
|
1140
|
+
React Native DSL (JSX / UI.*)
|
|
1141
|
+
↓
|
|
1142
|
+
UI Intermediate Representation (IR v2.0)
|
|
1143
|
+
├── UI Tree (gán ID duy nhất cho từng Node)
|
|
1144
|
+
├── Semantic Tree (độc lập hoàn toàn với Renderer)
|
|
1145
|
+
├── State Bindings (toggle:<key>, page:<id>)
|
|
1146
|
+
└── Renderer Planner (phân loại Native RemoteViews vs Canvas Bitmap)
|
|
1147
|
+
↓
|
|
1148
|
+
├── [NATIVE] RemoteViews (TextView, Button, ProgressBar)
|
|
1149
|
+
└── [CANVAS] Canvas 2D Bitmap (Gauge 240°, Equalizer, Shader)
|
|
1150
|
+
```
|
|
1151
|
+
|
|
1152
|
+
#### Sử dụng API `Widget.inspectIR` và `Widget.compileIR`:
|
|
1153
|
+
```typescript
|
|
1154
|
+
import { Widget, UI } from 'react-native-live-widgets';
|
|
1155
|
+
|
|
1156
|
+
const layout = UI.VStack({
|
|
1157
|
+
padding: 16,
|
|
1158
|
+
backgroundColor: '#0F172A',
|
|
1159
|
+
children: [
|
|
1160
|
+
UI.Text('BẢNG ĐIỀU KHIỂN CHẤM CÔNG', { typography: 'title2' }),
|
|
1161
|
+
UI.Progress({ value: 0.86, accessibilityLabel: 'Tiến độ hoàn thành ca' }),
|
|
1162
|
+
UI.Button({ title: 'Check In', actionId: 'toggle:attendance' }),
|
|
1163
|
+
UI.Gauge({ value: 0.92, label: 'Hiệu suất' })
|
|
1164
|
+
]
|
|
1165
|
+
});
|
|
1166
|
+
|
|
1167
|
+
// 1. Phân tích kiến trúc và kế hoạch kết xuất
|
|
1168
|
+
console.log(Widget.inspectIR(layout));
|
|
1169
|
+
/*
|
|
1170
|
+
Output:
|
|
1171
|
+
🌲 Widget IR v2.0
|
|
1172
|
+
📊 Chiến lược kết xuất: NATIVE_FIRST_HYBRID
|
|
1173
|
+
- Native RemoteViews nodes: 4
|
|
1174
|
+
- Canvas Bitmap nodes: 1
|
|
1175
|
+
|
|
1176
|
+
♿ Tóm tắt âm thanh Trợ năng:
|
|
1177
|
+
"BẢNG ĐIỀU KHIỂN CHẤM CÔNG. Tiến độ hoàn thành ca 86%. Nút Check In (Kích hoạt hành động toggle:attendance). Hiệu suất: 92%"
|
|
1178
|
+
|
|
1179
|
+
🎯 Kế hoạch phân bổ (Render Plan Tree):
|
|
1180
|
+
[NATIVE] 0.0 <Text> role=header label="BẢNG ĐIỀU KHIỂN CHẤM CÔNG"
|
|
1181
|
+
[NATIVE] 0.1 <Progress> role=progressbar label="Tiến độ hoàn thành ca"
|
|
1182
|
+
[NATIVE] 0.2 <Button> role=button label="Check In" (Action: toggle:attendance)
|
|
1183
|
+
[CANVAS] 0.3 <Gauge> role=progressbar label="Hiệu suất"
|
|
1184
|
+
|
|
1185
|
+
⚡ Liên kết trạng thái (State Bindings):
|
|
1186
|
+
- [TOGGLE] action=toggle:attendance target=attendance
|
|
1187
|
+
*/
|
|
1188
|
+
|
|
1189
|
+
// 2. Biên dịch trực tiếp sang IR Object
|
|
1190
|
+
const ir = Widget.compileIR(layout);
|
|
1191
|
+
console.log(ir.semanticSummary);
|
|
1192
|
+
```
|
|
1193
|
+
|
|
1194
|
+
---
|
|
1195
|
+
|
|
1196
|
+
### 12.6. ⚡ Đồng bộ Trạng thái Native, Tối ưu Sub-renderer & Bộ Kiểm thử Tự động
|
|
1197
|
+
|
|
1198
|
+
#### 1. Đồng bộ Trạng thái Hai chiều Native (Phase 4 State Synchronization):
|
|
1199
|
+
- Khi người dùng chạm nút hoặc đổi toggle trên Widget, Android Native (`LiveActivityReceiver.kt` & `DynamicWidgetStateStore`) **ngay lập tức lưu trạng thái mới vào SharedPreferences** và kích hoạt re-render widget ngay tức khắc, không có độ trễ và không bị lệch trạng thái kể cả khi App đã bị tắt (Force-Killed).
|
|
1200
|
+
- Khi App React Native mở lên, hook `useWidgetStorage` và `useWidgetAction` tự động đồng bộ lại state mới nhất từ Native Store.
|
|
1201
|
+
|
|
1202
|
+
#### 2. Tối ưu Canvas Sub-renderer (Phase 5 RAM & Binder Protection):
|
|
1203
|
+
- Thay vì vẽ một tấm Bitmap khổng lồ chiếm hàng Megabyte cho toàn bộ màn hình, phương thức `renderSubNodeBitmap` chỉ vẽ đúng kích thước khung hình hộp bao của thành phần đồ họa (ví dụ Gauge 64dp chỉ tốn ~40KB bitmap).
|
|
1204
|
+
- Triệt tiêu hoàn toàn nguy cơ chạm trần bộ nhớ Binder IPC (`TransactionTooLargeException`) trên Android.
|
|
1205
|
+
|
|
1206
|
+
#### 3. Bộ linh kiện Nâng cao & Kiểm thử Tự động (Phase 6):
|
|
1207
|
+
- Bổ sung các thẻ JSX: `<Toggle>`, `<Switch>`, `<Checkbox>` với trạng thái `checked`/`isChecked`, tự động đổi màu `tintColor` và gạch ngang chữ `strikethroughOnCheck`.
|
|
1208
|
+
- Bộ kiểm thử tự động 100% assertions:
|
|
1209
|
+
```bash
|
|
1210
|
+
npm test
|
|
1211
|
+
```
|
|
1212
|
+
Xác minh tự động:
|
|
1213
|
+
- Cây IR AST và gán ID duy nhất.
|
|
1214
|
+
- Lọc bỏ phần tử trang trí (`accessible: false`).
|
|
1215
|
+
- Phân loại Native-first vs Canvas-when-needed.
|
|
1216
|
+
- Trích xuất Two-Way State Bindings.
|
|
1217
|
+
- Tổng hợp câu âm thanh trợ năng TalkBack.
|
|
1218
|
+
|
|
1219
|
+
---
|
|
1220
|
+
|
|
1221
|
+
### 12.7. 🎯 Exact Dynamic Hit Layer, Live Chronometer Countdown & Tương thích Swift 6 (v1.2.1)
|
|
1222
|
+
|
|
1223
|
+
Phiên bản **v1.2.1** giải quyết dứt điểm các bài toán thực tế khi triển khai Widget tương tác phức tạp trên thiết bị người dùng thật:
|
|
1224
|
+
|
|
1225
|
+
#### 1. Vùng Bấm Động Từng Pixel (Exact Dynamic Hit Layer)
|
|
1226
|
+
* **Vấn đề trước đây**: Khi dùng lưới tọa độ cố định, nếu các thành phần trong layout co giãn hoặc nằm lệch dòng, người dùng bấm vào một nút có thể bị ăn sang nút khác, hoặc bấm vào vùng trống lại kích hoạt nhầm sự kiện.
|
|
1227
|
+
* **Giải pháp v1.2.1**:
|
|
1228
|
+
- Toàn bộ lưới cố định được thay bằng container `FrameLayout` động (`rn_hit_layer` kết hợp `rn_live_widget_hit_zone.xml`).
|
|
1229
|
+
- Giải thuật **`computeCanvasMapping`** tự động tính toán bù trừ tỷ lệ co giãn (`fitCenter` letterboxing) giữa kích thước Canvas Bitmap thật và màn hình widget Launcher.
|
|
1230
|
+
- Mỗi phần tử tương tác (Button, Checkbox, Switch, Link) được sinh một vùng RemoteViews độc lập khớp chính xác 100% với bounding box được vẽ trên Bitmap.
|
|
1231
|
+
- Vùng trống hoàn toàn không nhận sự kiện, triệt tiêu mọi cú chạm ảo (ghost clicks / phantom taps).
|
|
1232
|
+
|
|
1233
|
+
#### 2. Native Live Countdown Chronometer (`android.widget.Chronometer`)
|
|
1234
|
+
* **Vấn đề trước đây**: Vẽ chữ đếm ngược tĩnh trên Canvas đòi hỏi phải gửi broadcast và render lại bitmap mỗi giây. Điều này gây hao pin, chậm phản hồi và hệ điều hành Android có thể chặn vì spam update quá tần suất.
|
|
1235
|
+
* **Giải pháp v1.2.1**:
|
|
1236
|
+
- Tích hợp thành phần native `android.widget.Chronometer` trong layout host widget.
|
|
1237
|
+
- Tự động cấu hình `setChronometerCountDown(true)` và tính toán `baseMillis = SystemClock.elapsedRealtime() + remainingMillis`.
|
|
1238
|
+
- Renderer tự động ẩn dòng chữ đếm ngược tĩnh trên Bitmap khi có Chronometer hoạt động. Widget đếm ngược mượt mà từng giây trực tiếp từ hệ thống Android mà không cần vẽ lại Bitmap.
|
|
1239
|
+
|
|
1240
|
+
#### 3. Nội suy biến động (Template Interpolation) & Quản lý Trạng thái Khởi tạo
|
|
1241
|
+
* **Nội suy chuỗi biến số**: Hỗ trợ cú pháp template `{{id}}`, `{{title}}`, và giá trị bộ đếm phẳng `counterVal`. Bạn có thể truyền động mã phiếu, tiêu đề công việc hoặc số lượt đếm từ API vào layout JSON.
|
|
1242
|
+
* **Xử lý `defaultChecked`**: Trong `DynamicWidgetStateStore`, trạng thái ban đầu của switch (`checked: true`) được tự động lưu vào store ngay lần kết xuất đầu tiên. Người dùng có thể tắt switch ngay từ lần chạm đầu tiên mà không bị reset về trạng thái mặc định.
|
|
1243
|
+
|
|
1244
|
+
#### 4. Tương thích Toàn diện Swift 6 Language Mode (iOS Xcode)
|
|
1245
|
+
* **Loại bỏ lỗi `type '()' cannot conform to 'View'`**:
|
|
1246
|
+
- Đóng gói toàn bộ logic tính `Font` trong `renderText()` vào closure độc lập `{ ... }()`, ngăn compiler Swift 6 hiểu nhầm các câu lệnh điều kiện `if/switch` là View `Void`.
|
|
1247
|
+
- Tách logic phân giải `DynamicNodeAccessibilityModifier` sang hàm helper thuần `buildAccessibilityView(content:) -> AnyView`, tránh xung đột với `@ViewBuilder` ngầm định của protocol `ViewModifier`.
|
|
1248
|
+
- Đóng gói `strokeStyle` và bổ sung nhánh fallback `else { EmptyView() }` cho `backgroundView` và `borderOverlay` trong `ContainerStyleModifier`.
|
|
1249
|
+
|
|
1250
|
+
---
|
|
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
|
+
|
|
946
1397
|
## 📄 License
|
|
947
1398
|
MIT © vu-tran
|