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/src/types.ts
CHANGED
|
@@ -200,6 +200,8 @@ export interface TextStyle extends ShadowProps, AccessibilityProps {
|
|
|
200
200
|
redacted?: boolean;
|
|
201
201
|
/** Hiệu ứng cuộn lật số mượt mà kiểu Odometer (iOS 16+ numericText animation) khi số liệu thay đổi */
|
|
202
202
|
numericAnimation?: boolean;
|
|
203
|
+
/** Cho phép text tự đổi màu theo chế độ StandBy / Tinted iOS 17+ / iOS 18 */
|
|
204
|
+
widgetAccentable?: boolean;
|
|
203
205
|
}
|
|
204
206
|
|
|
205
207
|
export type StyleProp<T> = T | null | undefined | false | StyleProp<T>[];
|
|
@@ -248,8 +250,8 @@ export interface ProgressNode extends BaseNode {
|
|
|
248
250
|
startTimestamp?: number;
|
|
249
251
|
/** Mốc kết thúc (epoch giây) */
|
|
250
252
|
targetTimestamp?: number;
|
|
251
|
-
/** Giá trị cố định từ 0.0 đến 1.0
|
|
252
|
-
value?: number
|
|
253
|
+
/** Giá trị cố định từ 0.0 đến 1.0 hoặc biểu thức binding (vd '{{attendance.progress|divide:100}}') */
|
|
254
|
+
value?: number | string | DataBindingField<any>;
|
|
253
255
|
|
|
254
256
|
// ── 2. Kiểu dáng hiển thị (Style & Shape) ───────────────────
|
|
255
257
|
/** 'bar': thanh liền mạch | 'segmented': thanh nhiều chặng | 'circular': vòng tròn % */
|
|
@@ -296,9 +298,27 @@ export interface ProgressNode extends BaseNode {
|
|
|
296
298
|
/** Có hiển thị chữ phần trăm ở góc không (ví dụ "75%") */
|
|
297
299
|
showPercentage?: boolean;
|
|
298
300
|
percentageColor?: DynamicColor;
|
|
301
|
+
/** Cho phép thanh tiến trình đổi màu theo StandBy / Tinted iOS 17+ / iOS 18 */
|
|
302
|
+
widgetAccentable?: boolean;
|
|
299
303
|
};
|
|
300
304
|
}
|
|
301
305
|
|
|
306
|
+
import type { KnownSFSymbol } from './sf-symbols.generated';
|
|
307
|
+
import type { KnownMaterialIcon } from './material-icons.generated';
|
|
308
|
+
|
|
309
|
+
/**
|
|
310
|
+
* Biểu tượng hệ thống SF Symbols trên iOS (tự động đồng bộ từ Apple Xcode/SF Symbols).
|
|
311
|
+
* Hỗ trợ Auto-Complete hơn 9,500+ biểu tượng chuẩn và cho phép nhập chuỗi tùy ý nhờ `(string & {})`.
|
|
312
|
+
*/
|
|
313
|
+
export type SFSymbolName = KnownSFSymbol | (string & {});
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Danh sách gợi ý toàn bộ hơn 3,800+ biểu tượng Google Material Symbols & Icons chính thức trên Android.
|
|
317
|
+
* Tự động kích hoạt gợi ý Auto-Complete / IntelliSense trong IDE (VS Code, Cursor, WebStorm)
|
|
318
|
+
* và vẫn cho phép nhập bất kỳ tên Material Symbol nào khác nhờ `(string & {})`.
|
|
319
|
+
*/
|
|
320
|
+
export type MaterialIconName = KnownMaterialIcon | (string & {});
|
|
321
|
+
|
|
302
322
|
export interface ImageNode extends BaseNode {
|
|
303
323
|
type: 'Image';
|
|
304
324
|
props: AccessibilityProps & {
|
|
@@ -308,12 +328,26 @@ export interface ImageNode extends BaseNode {
|
|
|
308
328
|
base64?: string;
|
|
309
329
|
/** Tên ảnh trong Xcode Assets.xcassets hoặc Android drawable */
|
|
310
330
|
assetName?: string;
|
|
331
|
+
/** Tên ảnh riêng cho iOS trong Assets.xcassets */
|
|
332
|
+
iosAssetName?: string;
|
|
333
|
+
/** Tên ảnh riêng cho Android trong res/drawable */
|
|
334
|
+
androidAssetName?: string;
|
|
311
335
|
/** Tên icon hệ thống SF Symbols trên iOS (ví dụ 'person.crop.circle.fill', 'flame.fill', 'cart.fill') */
|
|
312
|
-
systemName?:
|
|
336
|
+
systemName?: SFSymbolName;
|
|
337
|
+
/** Tên icon SF Symbol riêng biệt cho iOS (ưu tiên cao hơn systemName trên iOS) */
|
|
338
|
+
iosSystemName?: SFSymbolName;
|
|
339
|
+
/** Alias cho iosSystemName */
|
|
340
|
+
systemNameIos?: SFSymbolName;
|
|
341
|
+
/** Tên icon Google Material Symbols riêng biệt cho Android (ưu tiên cao hơn systemName trên Android) */
|
|
342
|
+
androidSystemName?: MaterialIconName;
|
|
343
|
+
/** Alias cho androidSystemName */
|
|
344
|
+
systemNameAndroid?: MaterialIconName;
|
|
345
|
+
/** Tên icon Google Material Symbols (tương đương androidSystemName) */
|
|
346
|
+
materialName?: MaterialIconName;
|
|
313
347
|
/** Đường dẫn file cục bộ trong máy */
|
|
314
348
|
filePath?: string;
|
|
315
349
|
/** Icon SF Symbol dự phòng khi ảnh mạng chưa tải xong hoặc lỗi */
|
|
316
|
-
fallbackSystemName?:
|
|
350
|
+
fallbackSystemName?: SFSymbolName;
|
|
317
351
|
width?: number;
|
|
318
352
|
height?: number;
|
|
319
353
|
/** 'fill': phủ kín khung ảnh (crop) | 'fit': vừa khung ảnh */
|
|
@@ -434,8 +468,8 @@ export interface DividerNode extends BaseNode {
|
|
|
434
468
|
export interface GaugeNode extends BaseNode {
|
|
435
469
|
type: 'Gauge';
|
|
436
470
|
props: AccessibilityProps & {
|
|
437
|
-
/** Giá trị tiến độ từ 0.0 đến 1.0 */
|
|
438
|
-
value: number
|
|
471
|
+
/** Giá trị tiến độ từ 0.0 đến 1.0 hoặc biểu thức binding */
|
|
472
|
+
value: number | string | DataBindingField<any>;
|
|
439
473
|
/** Chuỗi hiển thị chính giữa đồng hồ (vd "85%", "120 km/h", "420") */
|
|
440
474
|
valueText?: string;
|
|
441
475
|
/** Nhãn phụ bên dưới đồng hồ (vd "KPI", "Kcal", "AQI") */
|
|
@@ -454,6 +488,8 @@ export interface GaugeNode extends BaseNode {
|
|
|
454
488
|
strokeWidth?: number;
|
|
455
489
|
/** Tự động ẩn hoặc làm mờ đồng hồ khi màn hình khóa */
|
|
456
490
|
privacySensitive?: boolean;
|
|
491
|
+
/** Cho phép đồng hồ đổi màu theo StandBy / Tinted iOS 17+ / iOS 18 */
|
|
492
|
+
widgetAccentable?: boolean;
|
|
457
493
|
};
|
|
458
494
|
}
|
|
459
495
|
|
|
@@ -501,7 +537,12 @@ export interface BadgeNode extends BaseNode {
|
|
|
501
537
|
type: 'Badge';
|
|
502
538
|
props: {
|
|
503
539
|
text: string;
|
|
504
|
-
systemName?:
|
|
540
|
+
systemName?: SFSymbolName;
|
|
541
|
+
iosSystemName?: SFSymbolName;
|
|
542
|
+
androidSystemName?: MaterialIconName;
|
|
543
|
+
systemNameIos?: SFSymbolName;
|
|
544
|
+
systemNameAndroid?: MaterialIconName;
|
|
545
|
+
materialName?: MaterialIconName;
|
|
505
546
|
backgroundColor?: string;
|
|
506
547
|
textColor?: string;
|
|
507
548
|
borderColor?: string;
|
|
@@ -586,14 +627,14 @@ export type LayoutNode =
|
|
|
586
627
|
| CustomNode;
|
|
587
628
|
|
|
588
629
|
export interface DynamicIslandConfig {
|
|
589
|
-
compactLeading: LayoutNode;
|
|
590
|
-
compactTrailing: LayoutNode;
|
|
591
|
-
minimal?: LayoutNode;
|
|
630
|
+
compactLeading: LayoutNode | React.ReactNode;
|
|
631
|
+
compactTrailing: LayoutNode | React.ReactNode;
|
|
632
|
+
minimal?: LayoutNode | React.ReactNode;
|
|
592
633
|
expanded?: {
|
|
593
|
-
leading?: LayoutNode;
|
|
594
|
-
trailing?: LayoutNode;
|
|
595
|
-
bottom?: LayoutNode;
|
|
596
|
-
center?: LayoutNode;
|
|
634
|
+
leading?: LayoutNode | React.ReactNode;
|
|
635
|
+
trailing?: LayoutNode | React.ReactNode;
|
|
636
|
+
bottom?: LayoutNode | React.ReactNode;
|
|
637
|
+
center?: LayoutNode | React.ReactNode;
|
|
597
638
|
};
|
|
598
639
|
}
|
|
599
640
|
|
|
@@ -605,14 +646,53 @@ export interface PhaseConfig {
|
|
|
605
646
|
alertBody?: string;
|
|
606
647
|
}
|
|
607
648
|
|
|
649
|
+
export interface AlertConfig {
|
|
650
|
+
title: string;
|
|
651
|
+
body: string;
|
|
652
|
+
sound?: 'default' | string;
|
|
653
|
+
}
|
|
654
|
+
|
|
655
|
+
export type LiveActivityLifecycleState =
|
|
656
|
+
| 'active'
|
|
657
|
+
| 'started_by_push'
|
|
658
|
+
| 'stale'
|
|
659
|
+
| 'expired'
|
|
660
|
+
| 'ended'
|
|
661
|
+
| 'dismissed';
|
|
662
|
+
|
|
663
|
+
export interface LiveActivityStateEvent {
|
|
664
|
+
activityId: string;
|
|
665
|
+
systemActivityId?: string;
|
|
666
|
+
state: LiveActivityLifecycleState;
|
|
667
|
+
timestamp: number;
|
|
668
|
+
pushToken?: string;
|
|
669
|
+
}
|
|
670
|
+
|
|
608
671
|
export interface StartActivityOptions {
|
|
609
672
|
activityId: string;
|
|
610
673
|
lockScreen: LayoutNode;
|
|
611
674
|
dynamicIsland?: DynamicIslandConfig;
|
|
612
675
|
phases?: PhaseConfig[];
|
|
676
|
+
/** Epoch timestamp (giây hoặc ms) mà từ thời điểm đó Activity bị coi là cũ (Stale) */
|
|
613
677
|
staleTimestamp?: number;
|
|
678
|
+
/** Giao diện Lock Screen dự phòng hiển thị khi Activity chuyển sang trạng thái Stale */
|
|
679
|
+
staleLockScreen?: LayoutNode;
|
|
680
|
+
/** Giao diện Dynamic Island dự phòng hiển thị khi Activity chuyển sang trạng thái Stale */
|
|
681
|
+
staleDynamicIsland?: DynamicIslandConfig;
|
|
682
|
+
/** Điểm ưu tiên hiển thị trên Lock Screen & Dynamic Island khi có nhiều Live Activity (0.0 -> 100.0) */
|
|
683
|
+
relevanceScore?: number;
|
|
684
|
+
/** Cấu hình cảnh báo chuông / banner khi khởi chạy hoặc cập nhật */
|
|
685
|
+
alertConfig?: AlertConfig;
|
|
614
686
|
alertTitle?: string;
|
|
615
687
|
alertBody?: string;
|
|
688
|
+
/** Epoch timestamp (giây hoặc ms) tự động kết thúc Activity khi đến hạn */
|
|
689
|
+
scheduledEndTimestamp?: number;
|
|
690
|
+
/** Hoặc số giây tự động kết thúc tính từ lúc gọi start() */
|
|
691
|
+
autoEndAfterSeconds?: number;
|
|
692
|
+
/** Giao diện Lock Screen tổng kết tự động hiển thị khi Activity hết hạn (Scheduled End) */
|
|
693
|
+
expiredLockScreen?: LayoutNode;
|
|
694
|
+
/** Chính sách dọn dẹp sau khi hết hạn tự động */
|
|
695
|
+
expiredDismissalPolicy?: 'immediate' | 'default' | 'afterDate';
|
|
616
696
|
}
|
|
617
697
|
|
|
618
698
|
export interface UpdateActivityOptions {
|
|
@@ -620,8 +700,16 @@ export interface UpdateActivityOptions {
|
|
|
620
700
|
lockScreen?: LayoutNode;
|
|
621
701
|
dynamicIsland?: DynamicIslandConfig;
|
|
622
702
|
staleTimestamp?: number;
|
|
703
|
+
staleLockScreen?: LayoutNode;
|
|
704
|
+
staleDynamicIsland?: DynamicIslandConfig;
|
|
705
|
+
relevanceScore?: number;
|
|
706
|
+
alertConfig?: AlertConfig;
|
|
623
707
|
alertTitle?: string;
|
|
624
708
|
alertBody?: string;
|
|
709
|
+
scheduledEndTimestamp?: number;
|
|
710
|
+
autoEndAfterSeconds?: number;
|
|
711
|
+
expiredLockScreen?: LayoutNode;
|
|
712
|
+
expiredDismissalPolicy?: 'immediate' | 'default' | 'afterDate';
|
|
625
713
|
}
|
|
626
714
|
|
|
627
715
|
export interface EndActivityOptions {
|
|
@@ -644,6 +732,10 @@ export interface WidgetSinglePageConfig {
|
|
|
644
732
|
small?: LayoutNode;
|
|
645
733
|
medium?: LayoutNode;
|
|
646
734
|
large?: LayoutNode;
|
|
735
|
+
/** Tiện ích cỡ cực đại cho iPadOS / Tablet (systemExtraLarge) & Android 4x4+ */
|
|
736
|
+
extraLarge?: LayoutNode;
|
|
737
|
+
/** Chế độ iOS 17+ StandBy Mode (hiển thị chữ/số lớn khi đặt ngang sạc pin đầu giường) */
|
|
738
|
+
standBy?: LayoutNode;
|
|
647
739
|
/** Màn hình khóa iOS 16+: Tiện ích hình chữ nhật bo góc dưới đồng hồ */
|
|
648
740
|
accessoryRectangular?: LayoutNode;
|
|
649
741
|
/** Màn hình khóa iOS 16+: Tiện ích ô tròn nhỏ dưới đồng hồ (Gauge / Circular Progress / Icon) */
|
|
@@ -652,6 +744,20 @@ export interface WidgetSinglePageConfig {
|
|
|
652
744
|
accessoryInline?: LayoutNode;
|
|
653
745
|
}
|
|
654
746
|
|
|
747
|
+
/** Cấu hình Control Widget (iOS 18+ Control Center / Action Button & Android Quick Settings Tile) */
|
|
748
|
+
export interface ControlWidgetConfig {
|
|
749
|
+
type?: 'button' | 'toggle';
|
|
750
|
+
title: string;
|
|
751
|
+
subtitle?: string;
|
|
752
|
+
checkedTitle?: string;
|
|
753
|
+
checkedSubtitle?: string;
|
|
754
|
+
systemName?: SFSymbolName;
|
|
755
|
+
tintColor?: string;
|
|
756
|
+
checked?: boolean;
|
|
757
|
+
actionId: string;
|
|
758
|
+
deepLink?: string;
|
|
759
|
+
}
|
|
760
|
+
|
|
655
761
|
export interface WidgetLayoutConfig extends WidgetSinglePageConfig {
|
|
656
762
|
/**
|
|
657
763
|
* Danh sách các trang/tab của Widget để chuyển qua lại ngay trên mặt Widget (không mở App).
|
|
@@ -681,6 +787,8 @@ export interface WidgetTimelineEntry {
|
|
|
681
787
|
date: number | string;
|
|
682
788
|
/** Cấu hình layout tại mốc thời gian tương ứng */
|
|
683
789
|
layout: WidgetLayoutConfig;
|
|
790
|
+
/** Dữ liệu Data Binding (tùy chọn) để nội suy sẵn vào layout tại mốc thời gian này */
|
|
791
|
+
data?: Record<string, any>;
|
|
684
792
|
}
|
|
685
793
|
|
|
686
794
|
export interface WidgetTimelineConfig {
|
|
@@ -704,19 +812,121 @@ export interface WidgetConfigOption {
|
|
|
704
812
|
icon?: string;
|
|
705
813
|
}
|
|
706
814
|
|
|
707
|
-
export interface
|
|
708
|
-
/**
|
|
815
|
+
export interface WidgetDataSchema {
|
|
816
|
+
/** Danh sách các key bắt buộc phải có trong dữ liệu sau khi flatten (vd ['user.name', 'attendance.progress']) */
|
|
817
|
+
requiredKeys?: string[];
|
|
818
|
+
/** Kiểm tra kiểu giá trị cơ bản của các key */
|
|
819
|
+
types?: Record<string, 'string' | 'number' | 'boolean'>;
|
|
820
|
+
/** Giá trị mặc định bù vào nếu key bị thiếu hoặc null */
|
|
821
|
+
defaults?: Record<string, string | number | boolean>;
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
export interface WidgetAuthRefreshConfig {
|
|
825
|
+
/** Endpoint cấp lại Access Token khi request chính gặp HTTP 401 */
|
|
709
826
|
url: string;
|
|
827
|
+
method?: 'POST' | 'GET';
|
|
828
|
+
headers?: Record<string, string>;
|
|
829
|
+
body?: string | Record<string, any>;
|
|
830
|
+
/** Đường dẫn JSON lấy token mới từ phản hồi (mặc định 'accessToken' hoặc 'token') */
|
|
831
|
+
tokenPath?: string;
|
|
832
|
+
/** Tên header gắn token mới (mặc định 'Authorization') */
|
|
833
|
+
headerName?: string;
|
|
834
|
+
/** Tiền tố giá trị header (mặc định 'Bearer ') */
|
|
835
|
+
headerPrefix?: string;
|
|
836
|
+
}
|
|
837
|
+
|
|
838
|
+
export interface WidgetRemoteSourceConfig {
|
|
839
|
+
url: string;
|
|
840
|
+
method?: 'GET' | 'POST' | 'PUT';
|
|
841
|
+
headers?: Record<string, string>;
|
|
842
|
+
body?: string | Record<string, any>;
|
|
843
|
+
timeoutMs?: number;
|
|
844
|
+
enableETag?: boolean;
|
|
845
|
+
}
|
|
846
|
+
|
|
847
|
+
export interface WidgetRemoteConfig {
|
|
848
|
+
/** URL API chính mà Widget Extension sẽ tự gọi ngầm (kể cả khi App chính đã bị kill) */
|
|
849
|
+
url?: string;
|
|
710
850
|
/** HTTP Method (mặc định 'GET') */
|
|
711
|
-
method?: 'GET' | 'POST';
|
|
851
|
+
method?: 'GET' | 'POST' | 'PUT';
|
|
852
|
+
/** Payload gửi kèm cho POST / PUT */
|
|
853
|
+
body?: string | Record<string, any>;
|
|
712
854
|
/** Headers xác thực (ví dụ { Authorization: 'Bearer ...' }) */
|
|
713
855
|
headers?: Record<string, string>;
|
|
714
|
-
/**
|
|
856
|
+
/** Thời gian chờ phản hồi mạng tính bằng mili-giây (mặc định 8000ms) */
|
|
857
|
+
timeoutMs?: number;
|
|
858
|
+
/** Thời gian sống của cache (giây) để tránh gọi API liên tục khi OS reload timeline */
|
|
859
|
+
cacheTtlSeconds?: number;
|
|
860
|
+
/** Bật Conditional Request qua header If-None-Match / If-Modified-Since & HTTP 304 */
|
|
861
|
+
enableETag?: boolean;
|
|
862
|
+
/** Số lần thử lại tối đa khi lỗi mạng hoặc HTTP 5xx (mặc định 0, exponential backoff) */
|
|
863
|
+
maxRetries?: number;
|
|
864
|
+
/** Độ trễ gốc (ms) cho lần retry đầu tiên (mặc định 500ms) */
|
|
865
|
+
retryDelayMs?: number;
|
|
866
|
+
/** Gọi đồng thời nhiều nguồn API, biến được gộp theo tiền tố `<sourceKey>.<path>` */
|
|
867
|
+
sources?: Record<string, WidgetRemoteSourceConfig>;
|
|
868
|
+
/** Ánh xạ tên biến đích: { targetKey: 'source.path|pipe' } */
|
|
869
|
+
mapping?: Record<string, string>;
|
|
870
|
+
/** Kiểm định dữ liệu trước khi cập nhật biến hiển thị trên Widget */
|
|
871
|
+
schema?: WidgetDataSchema;
|
|
872
|
+
/** Cấu hình tự động làm mới token nếu API trả HTTP 401 */
|
|
873
|
+
authRefresh?: WidgetAuthRefreshConfig;
|
|
874
|
+
/** Layout hiển thị dự phòng khi đồng bộ lỗi (hoặc dùng biến `{{_syncStatus}}`, `{{_syncError}}`, `{{_httpStatus}}`) */
|
|
875
|
+
errorFallback?: LayoutNode;
|
|
876
|
+
/**
|
|
877
|
+
* Mốc thời gian đề xuất sớm nhất (phút) cho OS tải lại timeline.
|
|
878
|
+
* Lưu ý: iOS WidgetKit dùng ngân sách động (~40–70 lần/ngày) và Android có Doze Mode,
|
|
879
|
+
* nên đây không phải cam kết đồng bộ chính xác từng phút khi app đóng.
|
|
880
|
+
*/
|
|
715
881
|
refreshIntervalMinutes?: number;
|
|
716
882
|
/** Alias ngắn gọn cho refreshIntervalMinutes */
|
|
717
883
|
intervalMinutes?: number;
|
|
718
884
|
}
|
|
719
885
|
|
|
886
|
+
// ─── 13B. STRUCTURED DATA BINDING ────────────────────────────────────────────
|
|
887
|
+
|
|
888
|
+
export interface WidgetDataPipeOptions {
|
|
889
|
+
default?: string | number | boolean;
|
|
890
|
+
divide?: number;
|
|
891
|
+
multiply?: number;
|
|
892
|
+
add?: number;
|
|
893
|
+
round?: number;
|
|
894
|
+
upper?: boolean;
|
|
895
|
+
lower?: boolean;
|
|
896
|
+
currency?: string;
|
|
897
|
+
percent?: number;
|
|
898
|
+
ifTruthy?: [string | number, (string | number)?];
|
|
899
|
+
}
|
|
900
|
+
|
|
901
|
+
export interface DataBindingMethods<V = any> {
|
|
902
|
+
readonly __isDataBinding: true;
|
|
903
|
+
readonly __bindingPath: string;
|
|
904
|
+
readonly __bindingPipes: string[];
|
|
905
|
+
toToken(): string;
|
|
906
|
+
toString(): string;
|
|
907
|
+
valueOf(): string;
|
|
908
|
+
toJSON(): string;
|
|
909
|
+
default(fallback: string | number | boolean): DataBindingField<V>;
|
|
910
|
+
divide(divisor: number): DataBindingField<number>;
|
|
911
|
+
multiply(factor: number): DataBindingField<number>;
|
|
912
|
+
add(offset: number): DataBindingField<number>;
|
|
913
|
+
round(decimals?: number): DataBindingField<number>;
|
|
914
|
+
upper(): DataBindingField<string>;
|
|
915
|
+
lower(): DataBindingField<string>;
|
|
916
|
+
currency(symbol?: string): DataBindingField<string>;
|
|
917
|
+
percent(decimals?: number): DataBindingField<string>;
|
|
918
|
+
ifTruthy(thenValue: string | number, elseValue?: string | number): DataBindingField<string>;
|
|
919
|
+
}
|
|
920
|
+
|
|
921
|
+
export type DataBindingField<T = any> = DataBindingMethods<T> &
|
|
922
|
+
(T extends Array<infer U>
|
|
923
|
+
? { readonly [index: number]: DataBindingField<U> }
|
|
924
|
+
: T extends object
|
|
925
|
+
? { readonly [K in keyof T]-?: DataBindingField<T[K]> }
|
|
926
|
+
: unknown);
|
|
927
|
+
|
|
928
|
+
export type DataBindingProxy<T = Record<string, any>> = DataBindingField<T>;
|
|
929
|
+
|
|
720
930
|
export interface LiveActivityPushTokens {
|
|
721
931
|
/** Token APNs của thiết bị (Device Token 64-hex chars) dùng cho Push Notification / Silent Push */
|
|
722
932
|
devicePushToken: string | null;
|
|
@@ -730,6 +940,12 @@ export interface LiveActivityPushTokens {
|
|
|
730
940
|
|
|
731
941
|
export interface ActiveActivityInfo {
|
|
732
942
|
activityId: string;
|
|
943
|
+
systemActivityId?: string;
|
|
944
|
+
activityState?: 'active' | 'stale' | 'ended' | 'dismissed' | 'expired' | string;
|
|
945
|
+
isStale?: boolean;
|
|
946
|
+
relevanceScore?: number;
|
|
947
|
+
staleTimestamp?: number;
|
|
948
|
+
scheduledEndTimestamp?: number;
|
|
733
949
|
pushToken?: string;
|
|
734
950
|
}
|
|
735
951
|
|
|
@@ -841,3 +1057,117 @@ export interface WidgetIR {
|
|
|
841
1057
|
};
|
|
842
1058
|
stateBindings: StateBinding[];
|
|
843
1059
|
}
|
|
1060
|
+
|
|
1061
|
+
/**
|
|
1062
|
+
* Danh sách kích thước Widget Family được WidgetKit hỗ trợ trên iOS:
|
|
1063
|
+
*/
|
|
1064
|
+
export type WidgetFamily =
|
|
1065
|
+
| 'systemSmall'
|
|
1066
|
+
| 'systemMedium'
|
|
1067
|
+
| 'systemLarge'
|
|
1068
|
+
| 'systemExtraLarge'
|
|
1069
|
+
| 'accessoryCircular'
|
|
1070
|
+
| 'accessoryRectangular'
|
|
1071
|
+
| 'accessoryInline';
|
|
1072
|
+
|
|
1073
|
+
/**
|
|
1074
|
+
* Cấu hình hệ thống đa ngôn ngữ (i18n) cho Widgets.
|
|
1075
|
+
* Tự động đồng bộ các bản dịch JSON (i18next) sang Apple String Catalog (Localizable.xcstrings / Localizable.strings).
|
|
1076
|
+
*/
|
|
1077
|
+
export interface WidgetsI18nConfig {
|
|
1078
|
+
/**
|
|
1079
|
+
* Đường dẫn tới thư mục chứa các file ngôn ngữ (ví dụ: './src/locales' hoặc './locales').
|
|
1080
|
+
* Hệ thống sẽ tự động quét các file .json như vi.json, en.json, ja.json...
|
|
1081
|
+
*/
|
|
1082
|
+
localesDir?: string;
|
|
1083
|
+
|
|
1084
|
+
/**
|
|
1085
|
+
* Ngôn ngữ nguồn / mặc định (mặc định: 'vi')
|
|
1086
|
+
*/
|
|
1087
|
+
defaultLocale?: string;
|
|
1088
|
+
|
|
1089
|
+
/**
|
|
1090
|
+
* Khai báo bản đồ dịch trực tiếp (inline translations) thay cho hoặc bổ trợ cho file JSON.
|
|
1091
|
+
* Ví dụ: { vi: { 'widgets.title': 'Tiêu đề' }, en: { 'widgets.title': 'Title' } }
|
|
1092
|
+
*/
|
|
1093
|
+
translations?: Record<string, Record<string, any>>;
|
|
1094
|
+
}
|
|
1095
|
+
|
|
1096
|
+
/**
|
|
1097
|
+
* Kiểu chuỗi bản địa hóa đa ngôn ngữ: có thể là 1 string đơn, 1 i18n key hoặc 1 object đa ngôn ngữ.
|
|
1098
|
+
*/
|
|
1099
|
+
export type LocalizedString = string | Record<string, string>;
|
|
1100
|
+
|
|
1101
|
+
/**
|
|
1102
|
+
* Cấu hình một Widget trên Màn hình chính (Home Screen Widget)
|
|
1103
|
+
*/
|
|
1104
|
+
export interface WidgetDefinition {
|
|
1105
|
+
/**
|
|
1106
|
+
* Tên định danh Struct trong Swift (ví dụ: 'DynamicHomeScreenWidget', 'ShiftAttendanceHomeScreenWidget')
|
|
1107
|
+
* Nếu không chỉ định, sẽ tự động sinh từ key (ví dụ: 'shift' -> 'ShiftHomeScreenWidget')
|
|
1108
|
+
*/
|
|
1109
|
+
kind?: string;
|
|
1110
|
+
|
|
1111
|
+
/**
|
|
1112
|
+
* Khóa định danh phân vùng dữ liệu / state của Widget (ví dụ: 'main', 'counter', 'shift', 'pro', 'workspace')
|
|
1113
|
+
* Mặc định là 'main'
|
|
1114
|
+
*/
|
|
1115
|
+
key?: string;
|
|
1116
|
+
|
|
1117
|
+
/**
|
|
1118
|
+
* Tên hiển thị của Widget trong thư viện Widget trên iOS / Android.
|
|
1119
|
+
* Có thể truyền:
|
|
1120
|
+
* - Một i18n key (ví dụ: 'widgets.counter.title')
|
|
1121
|
+
* - Hoặc chuỗi hiển thị trực tiếp
|
|
1122
|
+
* - Hoặc Object đa ngôn ngữ: { vi: '...', en: '...', ja: '...' }
|
|
1123
|
+
*/
|
|
1124
|
+
displayName: LocalizedString;
|
|
1125
|
+
|
|
1126
|
+
/**
|
|
1127
|
+
* Mô tả tính năng của Widget hiển thị cho người dùng khi chọn thêm vào Màn hình chính.
|
|
1128
|
+
* Có thể truyền key i18n, chuỗi trực tiếp hoặc Object đa ngôn ngữ.
|
|
1129
|
+
*/
|
|
1130
|
+
description?: LocalizedString;
|
|
1131
|
+
|
|
1132
|
+
/**
|
|
1133
|
+
* Các kích thước Widget được phép thêm (mặc định hỗ trợ tất cả các cỡ system + accessory)
|
|
1134
|
+
*/
|
|
1135
|
+
supportedFamilies?: WidgetFamily[];
|
|
1136
|
+
|
|
1137
|
+
/**
|
|
1138
|
+
* Có hỗ trợ căn lề StandBy Mode (iOS 17+) không (tự che viền khi ở chế độ cắm sạc ban đêm)
|
|
1139
|
+
*/
|
|
1140
|
+
standbyMargins?: boolean;
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1143
|
+
/**
|
|
1144
|
+
* Cấu hình toàn bộ hệ thống Widgets cho ứng dụng (dùng trong widgets.config.ts)
|
|
1145
|
+
*/
|
|
1146
|
+
export interface WidgetsProjectConfig {
|
|
1147
|
+
/**
|
|
1148
|
+
* Tên bundle Swift (mặc định: 'LiveWidgetsBundle')
|
|
1149
|
+
*/
|
|
1150
|
+
bundleName?: string;
|
|
1151
|
+
|
|
1152
|
+
/**
|
|
1153
|
+
* Cấu hình đa ngôn ngữ i18n (tự động đồng bộ với i18next JSON hoặc Object đa ngôn ngữ)
|
|
1154
|
+
*/
|
|
1155
|
+
i18n?: WidgetsI18nConfig;
|
|
1156
|
+
|
|
1157
|
+
/**
|
|
1158
|
+
* Bật tiện ích Live Activity & Dynamic Island (iOS 16.1+)
|
|
1159
|
+
* Mặc định: true
|
|
1160
|
+
*/
|
|
1161
|
+
liveActivity?: boolean;
|
|
1162
|
+
|
|
1163
|
+
/**
|
|
1164
|
+
* Bật tiện ích Điều khiển Trung tâm Control Center (iOS 18.0+)
|
|
1165
|
+
* Mặc định: true
|
|
1166
|
+
*/
|
|
1167
|
+
controlWidgets?: boolean;
|
|
1168
|
+
|
|
1169
|
+
/**
|
|
1170
|
+
* Danh sách các Widget trên Màn hình chính (Home Screen Widgets)
|
|
1171
|
+
*/
|
|
1172
|
+
widgets: WidgetDefinition[];
|
|
1173
|
+
}
|