0
# NativeScript Core Modules
1
2
NativeScript Core Modules (`tns-core-modules`) is a compatibility package that provides the complete NativeScript framework API for building native iOS and Android mobile applications using JavaScript, TypeScript, and CSS. It delivers true native performance without WebViews by bridging JavaScript to native APIs, enabling access to platform-specific functionality through unified cross-platform interfaces.
3
4
## Package Information
5
6
- **Package Name**: tns-core-modules
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install tns-core-modules`
10
11
## Core Imports
12
13
```typescript
14
// Application lifecycle and utilities
15
import { Application, ApplicationSettings } from "tns-core-modules";
16
17
// UI components and layouts
18
import { Page, StackLayout, Button, Label } from "tns-core-modules";
19
20
// Data handling
21
import { Observable, ObservableArray } from "tns-core-modules";
22
23
// File system and HTTP
24
import { File, Folder, Http } from "tns-core-modules";
25
26
// Performance monitoring and debugging
27
import { Profiling, Trace } from "tns-core-modules";
28
29
// Utility functions and platform services
30
import { Utils, Connectivity, Color } from "tns-core-modules";
31
32
// XML parsing
33
import { XmlParser, ParserEventType } from "tns-core-modules";
34
```
35
36
For CommonJS:
37
38
```javascript
39
const { Application, Page, Button } = require("tns-core-modules");
40
```
41
42
## Basic Usage
43
44
```typescript
45
import { Application, Page, StackLayout, Button, Label } from "tns-core-modules";
46
47
// Application setup
48
Application.run({ moduleName: "main-page" });
49
50
// Create a simple page with UI
51
export function createPage() {
52
const page = new Page();
53
const stack = new StackLayout();
54
55
const label = new Label();
56
label.text = "Hello NativeScript!";
57
58
const button = new Button();
59
button.text = "Click Me";
60
button.on("tap", () => {
61
label.text = "Button tapped!";
62
});
63
64
stack.addChild(label);
65
stack.addChild(button);
66
page.content = stack;
67
68
return page;
69
}
70
```
71
72
## Architecture
73
74
NativeScript Core Modules provides several key architectural components:
75
76
- **Application Layer**: Lifecycle management, navigation, and app-wide utilities
77
- **UI Framework**: 30+ native UI components with cross-platform abstractions
78
- **Data Binding**: Observable pattern with two-way data binding capabilities
79
- **Platform Services**: File system, HTTP client, device APIs, and system integrations
80
- **Styling System**: CSS-like styling with platform-specific adaptations
81
- **Native Bridge**: Direct access to iOS and Android native APIs
82
83
## Capabilities
84
85
### Application Management
86
87
Core application lifecycle, navigation, and configuration management for NativeScript apps.
88
89
```typescript { .api }
90
namespace Application {
91
// Application lifecycle events
92
const launchEvent: string;
93
const suspendEvent: string;
94
const resumeEvent: string;
95
const exitEvent: string;
96
97
// Core application functions
98
function run(entry?: any): void;
99
function getRootView(): View;
100
function orientation(): string;
101
function hasLaunched(): boolean;
102
103
// Platform-specific instances
104
const android: AndroidApplication;
105
const ios: iOSApplication;
106
}
107
108
namespace ApplicationSettings {
109
function setString(key: string, value: string): void;
110
function getString(key: string, defaultValue?: string): string;
111
function setBoolean(key: string, value: boolean): void;
112
function getBoolean(key: string, defaultValue?: boolean): boolean;
113
function clear(): void;
114
}
115
```
116
117
[Application Management](./application.md)
118
119
### UI Components and Layouts
120
121
Comprehensive set of native UI components including buttons, labels, inputs, and advanced controls like lists and navigation.
122
123
```typescript { .api }
124
// Core UI base classes
125
class ViewBase {
126
id: string;
127
className: string;
128
style: Style;
129
parent: ViewBase;
130
isLoaded: boolean;
131
132
on(eventName: string, callback: Function): void;
133
off(eventName: string, callback?: Function): void;
134
}
135
136
class View extends ViewBase {
137
width: number | string;
138
height: number | string;
139
visibility: string;
140
opacity: number;
141
}
142
143
// Layout containers
144
class StackLayout extends LayoutBase {
145
orientation: string;
146
}
147
148
class GridLayout extends LayoutBase {
149
columns: string;
150
rows: string;
151
}
152
153
// UI controls
154
class Button extends View {
155
text: string;
156
tap: string; // event name
157
}
158
159
class Label extends View {
160
text: string;
161
textWrap: boolean;
162
}
163
```
164
165
[UI Components](./ui-components.md)
166
167
### Data Binding and Observables
168
169
Reactive data handling with Observable pattern supporting two-way data binding and change notifications.
170
171
```typescript { .api }
172
class Observable {
173
constructor(obj?: any);
174
175
get(name: string): any;
176
set(name: string, value: any): void;
177
on(eventName: string, callback: Function): void;
178
off(eventName: string, callback?: Function): void;
179
notify(data: PropertyChangeData): void;
180
}
181
182
class ObservableArray<T> extends Array<T> {
183
constructor(...items: T[]);
184
185
push(...items: T[]): number;
186
pop(): T;
187
splice(start: number, deleteCount?: number, ...items: T[]): T[];
188
189
on(eventName: string, callback: Function): void;
190
}
191
192
interface PropertyChangeData {
193
object: Observable;
194
propertyName: string;
195
value: any;
196
oldValue: any;
197
}
198
```
199
200
[Data Binding](./data-binding.md)
201
202
### File System Operations
203
204
Cross-platform file system access for reading, writing, and managing files and folders on mobile devices.
205
206
```typescript { .api }
207
class File extends FileSystemEntity {
208
static fromPath(path: string): File;
209
210
readText(encoding?: string): Promise<string>;
211
writeText(content: string, encoding?: string): Promise<void>;
212
readTextSync(encoding?: string): string;
213
writeTextSync(content: string, encoding?: string): void;
214
}
215
216
class Folder extends FileSystemEntity {
217
static fromPath(path: string): Folder;
218
219
getFile(name: string): File;
220
getFolder(name: string): Folder;
221
getEntities(): Promise<FileSystemEntity[]>;
222
eachEntity(onEntity: Function): void;
223
}
224
225
namespace knownFolders {
226
const documents: Folder;
227
const temp: Folder;
228
const currentApp: Folder;
229
}
230
```
231
232
[File System](./file-system.md)
233
234
### HTTP Client
235
236
Full-featured HTTP client for REST API calls, file downloads, and network communication.
237
238
```typescript { .api }
239
namespace Http {
240
function request(options: HttpRequestOptions): Promise<HttpResponse>;
241
function getJSON<T>(url: string): Promise<T>;
242
function getString(url: string): Promise<string>;
243
function getFile(url: string, destinationFilePath?: string): Promise<File>;
244
function getImage(url: string): Promise<ImageSource>;
245
}
246
247
interface HttpRequestOptions {
248
url: string;
249
method?: string;
250
headers?: any;
251
content?: string | any;
252
timeout?: number;
253
}
254
255
interface HttpResponse {
256
statusCode: number;
257
content: HttpContent;
258
headers: any;
259
}
260
```
261
262
[HTTP Client](./http-client.md)
263
264
### Image Handling
265
266
Comprehensive image loading, manipulation, and caching capabilities for mobile applications.
267
268
```typescript { .api }
269
class ImageSource {
270
static fromFile(path: string): ImageSource;
271
static fromData(data: any): ImageSource;
272
static fromBase64(source: string): ImageSource;
273
274
saveToFile(path: string, format: string, quality?: number): boolean;
275
toBase64String(format: string, quality?: number): string;
276
}
277
278
class ImageAsset {
279
constructor(asset: any);
280
281
getImage(options?: ImageAssetOptions): Promise<ImageSource>;
282
}
283
284
interface ImageAssetOptions {
285
maxWidth?: number;
286
maxHeight?: number;
287
aspectRatio?: string;
288
autoScaleFactor?: boolean;
289
}
290
```
291
292
[Image Handling](./image-handling.md)
293
294
### Platform Utilities
295
296
Device information, platform detection, and native utility functions for iOS and Android integration.
297
298
```typescript { .api }
299
// Platform detection
300
function isAndroid(): boolean;
301
function isIOS(): boolean;
302
303
// Device information
304
interface Device {
305
model: string;
306
deviceType: string;
307
os: string;
308
osVersion: string;
309
sdkVersion: string;
310
language: string;
311
region: string;
312
}
313
314
// Screen information
315
interface Screen {
316
mainScreen: ScreenMetrics;
317
widthDIPs: number;
318
heightDIPs: number;
319
scale: number;
320
}
321
322
// Utility functions
323
namespace Utils {
324
function executeOnMainThread(func: Function): void;
325
function isMainThread(): boolean;
326
function openUrl(url: string): boolean;
327
function openFile(filePath: string): boolean;
328
}
329
```
330
331
[Platform Utilities](./platform-utils.md)
332
333
### Performance Profiling
334
335
Performance monitoring and profiling tools for measuring method execution times, memory usage, and application performance metrics.
336
337
```typescript { .api }
338
namespace Profiling {
339
// Core profiling controls
340
function enable(type?: InstrumentationMode): void;
341
function disable(): void;
342
function isRunning(name: string): boolean;
343
344
// Timer functions
345
function time(): number;
346
function uptime(): number;
347
function start(name: string): void;
348
function stop(name: string): TimerInfo;
349
350
// Profile management
351
function dumpProfiles(): void;
352
function resetProfiles(): void;
353
function profile(name?: string): MethodDecorator;
354
function profile<F extends Function>(fn: F): F;
355
function profile<F extends Function>(name: string, fn: F): F;
356
357
// CPU profiling (Android)
358
function startCPUProfile(name: string): void;
359
function stopCPUProfile(name: string): void;
360
}
361
362
type InstrumentationMode = "counters" | "timeline" | "lifecycle";
363
364
interface TimerInfo {
365
totalTime: number;
366
count: number;
367
}
368
```
369
370
### Debug Tracing
371
372
Debug tracing and logging system with category-based filtering and multiple output writers for comprehensive application debugging.
373
374
```typescript { .api }
375
namespace Trace {
376
// Core trace controls
377
function enable(): void;
378
function disable(): void;
379
function isEnabled(): boolean;
380
381
// Writer management
382
function addWriter(writer: TraceWriter): void;
383
function removeWriter(writer: TraceWriter): void;
384
function clearWriters(): void;
385
386
// Category management
387
function setCategories(categories: string): void;
388
function addCategories(categories: string): void;
389
390
// Logging functions
391
function write(message: any, category: string, type?: number): void;
392
function error(error: string | Error): void;
393
394
// Event handling
395
function setErrorHandler(handler: ErrorHandler): void;
396
397
// Predefined categories
398
const categories: {
399
VisualTreeEvents: string;
400
Layout: string;
401
Style: string;
402
ViewHierarchy: string;
403
NativeLifecycle: string;
404
Debug: string;
405
Navigation: string;
406
Test: string;
407
Binding: string;
408
Error: string;
409
Animation: string;
410
Transition: string;
411
All: string;
412
};
413
414
// Message types
415
const messageType: {
416
log: number;
417
info: number;
418
warn: number;
419
error: number;
420
};
421
}
422
423
interface TraceWriter {
424
write(message: any, category: string, type?: number): void;
425
}
426
427
interface ErrorHandler {
428
handlerError(error: Error): void;
429
}
430
```
431
432
### Network Connectivity
433
434
Network connection monitoring and detection capabilities for managing network-dependent application behavior.
435
436
```typescript { .api }
437
namespace Connectivity {
438
// Connection detection
439
function getConnectionType(): number;
440
function startMonitoring(callback: (newConnectionType: number) => void): void;
441
function stopMonitoring(): void;
442
443
// Connection types
444
const connectionType: {
445
none: 0;
446
wifi: 1;
447
mobile: 2;
448
ethernet: 3;
449
bluetooth: 4;
450
vpn: 5;
451
};
452
}
453
```
454
455
### Color Management
456
457
Color creation and manipulation utilities supporting multiple color formats and platform-specific representations.
458
459
```typescript { .api }
460
class Color {
461
constructor(knownColor: string);
462
constructor(hex: string);
463
constructor(argb: number);
464
constructor(alpha: number, red: number, green: number, blue: number);
465
466
// Color components (read-only)
467
readonly a: number; // Alpha (0-255)
468
readonly r: number; // Red (0-255)
469
readonly g: number; // Green (0-255)
470
readonly b: number; // Blue (0-255)
471
472
// Color representations (read-only)
473
readonly hex: string;
474
readonly argb: number;
475
readonly name: string;
476
readonly android: number;
477
readonly ios: any; // UIColor
478
479
// Utility methods
480
equals(value: Color): boolean;
481
static equals(value1: Color, value2: Color): boolean;
482
static isValid(value: any): boolean;
483
}
484
```
485
486
### XML Parsing
487
488
SAX-based XML parsing with event-driven processing and namespace support for handling XML data and documents.
489
490
```typescript { .api }
491
class XmlParser {
492
constructor(
493
onEvent: (event: ParserEvent) => void,
494
onError?: (error: Error, position: Position) => void,
495
processNamespaces?: boolean,
496
angularSyntax?: boolean
497
);
498
499
parse(xmlString: string): void;
500
}
501
502
class ParserEventType {
503
static StartElement: string;
504
static EndElement: string;
505
static Text: string;
506
static CDATA: string;
507
static Comment: string;
508
}
509
510
interface ParserEvent {
511
eventType: string;
512
position: Position;
513
prefix?: string;
514
namespace?: string;
515
elementName?: string;
516
attributes?: any;
517
data?: string;
518
toString(): string;
519
}
520
521
interface Position {
522
line: number;
523
column: number;
524
}
525
```