ArkTS Development
Build HarmonyOS applications using ArkTS and the ArkUI declarative UI framework.
Quick Start
Create a basic component:
typescript
@Entry
@Component
struct HelloWorld {
@State message: string = 'Hello, ArkTS!';
build() {
Column() {
Text(this.message)
.fontSize(30)
.fontWeight(FontWeight.Bold)
Button('Click Me')
.onClick(() => { this.message = 'Button Clicked!'; })
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
State Management Decorators
V1 (Traditional)
| Decorator | Usage | Description |
|---|
| | Component internal state |
| | Parent → Child (one-way) |
| | Parent ↔ Child (two-way, use ) |
| Cross-level | Ancestor → Descendant |
| Nested objects | Deep object observation |
V2 (Recommended - API 12+)
| Decorator | Usage | Description |
|---|
| @ComponentV2 struct MyComp
| Enable V2 state management |
| | Internal state (no external init) |
| @Param title: string = ""
| Parent → Child (one-way, efficient) |
| @Event onChange: () => void
| Child → Parent (callback) |
| | Class observation |
| | Property-level tracking |
| | Cached computed properties |
| | Watch changes with before/after |
| Cross-level | Two-way sync across tree |
See references/state-management-v2.md for complete V2 guide.
Common Layouts
typescript
// Vertical
Column({ space: 10 }) { Text('A'); Text('B'); }
.alignItems(HorizontalAlign.Center)
// Horizontal
Row({ space: 10 }) { Text('A'); Text('B'); }
.justifyContent(FlexAlign.SpaceBetween)
// Stack (overlay)
Stack({ alignContent: Alignment.Center }) {
Image($r('app.media.bg'))
Text('Overlay')
}
// List with ForEach
List({ space: 10 }) {
ForEach(this.items, (item: string) => {
ListItem() { Text(item) }
}, (item: string) => item)
}
Component Lifecycle
typescript
@Entry
@Component
struct Page {
aboutToAppear() { /* Init data */ }
onPageShow() { /* Page visible */ }
onPageHide() { /* Page hidden */ }
aboutToDisappear() { /* Cleanup */ }
build() { Column() { Text('Page') } }
}
Navigation
typescript
import { router } from '@kit.ArkUI';
// Push
router.pushUrl({ url: 'pages/Detail', params: { id: 123 } });
// Replace
router.replaceUrl({ url: 'pages/New' });
// Back
router.back();
// Get params
interface RouteParams {
id: number;
title?: string;
}
const params = router.getParams() as RouteParams;
Network Request
typescript
import { http } from '@kit.NetworkKit';
const req = http.createHttp();
const res = await req.request('https://api.example.com/data', {
method: http.RequestMethod.GET,
header: { 'Content-Type': 'application/json' }
});
if (res.responseCode === 200) {
const data = JSON.parse(res.result as string);
}
req.destroy();
Local Storage
typescript
import { preferences } from '@kit.ArkData';
const prefs = await preferences.getPreferences(this.context, 'store');
await prefs.put('key', 'value');
await prefs.flush();
const val = await prefs.get('key', 'default');
ArkTS Language Constraints
ArkTS enforces stricter rules than TypeScript for performance and safety:
| Prohibited | Use Instead |
|---|
| , | Explicit types, interfaces |
| , |
| Dynamic property access | Fixed object structure |
| , , | , array methods |
| keyword |
| Structural typing | Explicit / |
See references/migration-guide.md for complete TypeScript → ArkTS migration details.
Command Line Build (hvigorw)
hvigorw is the Hvigor wrapper tool for command-line builds.
bash
# Common build tasks
hvigorw clean # Clean build directory
hvigorw assembleHap -p buildMode=debug # Build Hap (debug)
hvigorw assembleApp -p buildMode=release # Build App (release)
hvigorw assembleHar # Build Har library
hvigorw assembleHsp # Build Hsp
# Build specific module
hvigorw assembleHap -p module=entry@default --mode module
# Run tests
hvigorw onDeviceTest -p module=entry -p coverage=true
hvigorw test -p module=entry # Local test
# CI/CD recommended
hvigorw assembleApp -p buildMode=release --no-daemon
Common parameters:
| Parameter | Description |
|---|
-p buildMode={debug|release}
| Build mode |
| Target product (default: default) |
-p module={name}@{target}
| Target module (with ) |
| Disable daemon (recommended for CI) |
| Enable build analysis |
--optimization-strategy=memory
| Memory-optimized build |
See references/hvigor-commandline.md for complete command reference.
Code Linter (codelinter)
codelinter is the code checking and fixing tool for ArkTS/TS files.
bash
# Basic usage
codelinter # Check current project
codelinter /path/to/project # Check specified project
codelinter -c ./code-linter.json5 # Use custom rules
# Check and auto-fix
codelinter --fix
codelinter -c ./code-linter.json5 --fix
# Output formats
codelinter -f json -o ./report.json # JSON report
codelinter -f html -o ./report.html # HTML report
# Incremental check (Git changes only)
codelinter -i
# CI/CD with exit codes
codelinter --exit-on error,warn # Non-zero exit on error/warn
| Parameter | Description |
|---|
| Specify rules config file |
| Auto-fix supported issues |
| Output format: default/json/xml/html |
| Save result to file |
| Check only Git changed files |
| Specify product |
| Exit code levels: error,warn,suggestion |
See references/codelinter.md for complete reference.
Stack Trace Parser (hstack)
hstack parses obfuscated crash stacks from Release builds back to source code locations.
bash
# Parse crash files directory
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
# Parse with C++ symbols
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir
# Parse single crash stack
hstack -c "at func (entry|entry|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir
| Parameter | Description |
|---|
| Crash files directory |
| Single crash stack string |
| Output directory (or file with ) |
| Sourcemap files directory |
| Shared object (.so) files directory |
| NameCache files directory |
Requirements:
- Must provide either or (not both)
- Must provide at least or
- For method name restoration, provide both and
See references/hstack.md for complete reference.
Code Obfuscation (ArkGuard)
json
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": true,
"files": ["./obfuscation-rules.txt"]
}
}
}
text
-enable-property-obfuscation # Property name obfuscation
-enable-toplevel-obfuscation # Top-level scope obfuscation
-enable-filename-obfuscation # Filename obfuscation
-keep-property-name apiKey # Whitelist specific names
See references/arkguard-obfuscation.md for complete guide.
Reference Files
- State Management V2: references/state-management-v2.md - Complete guide to V2 state management (@ComponentV2, @Local, @Param, @Event, @ObservedV2, @Trace, @Computed, @Monitor, @Provider, @Consumer)
- Migration Guide: references/migration-guide.md - Complete TypeScript to ArkTS migration rules and examples
- Component Patterns: references/component-patterns.md - Advanced component patterns and best practices
- API Reference: references/api-reference.md - Common HarmonyOS APIs
- ArkGuard Obfuscation: references/arkguard-obfuscation.md - Code obfuscation configuration and troubleshooting
- Hvigor Command Line: references/hvigor-commandline.md - Complete hvigorw build tool reference
- CodeLinter: references/codelinter.md - Code checking and fixing tool
- Hstack: references/hstack.md - Crash stack trace parser for Release builds
Development Environment
- IDE: DevEco Studio
- SDK: HarmonyOS SDK
- Simulator: Built-in DevEco Studio emulator
Related Skills
- Build & Deploy: See skill for building, packaging, and device installation