arkts-skills/arkts-development/references/api-reference.md

HarmonyOS API Reference

Common HarmonyOS APIs for ArkTS development.

Table of Contents

1. Router Navigation
2. HTTP Networking
3. Preferences Storage
4. File Operations
5. Device Info
6. Prompt & Dialog
7. Media

---

Router Navigation

import { router } from '@kit.ArkUI';

Push Page

router.pushUrl({
  url: 'pages/DetailPage',
  params: {
    id: 123,
    title: 'Detail'
  }
});

Push with Mode

// Standard mode (default) - adds to stack
router.pushUrl({
  url: 'pages/Page',
}, router.RouterMode.Standard);

// Single mode - reuses if exists
router.pushUrl({
  url: 'pages/Page',
}, router.RouterMode.Single);

Replace Page

router.replaceUrl({
  url: 'pages/NewPage'
});

Back Navigation

// Back to previous
router.back();

// Back to specific page
router.back({
  url: 'pages/HomePage'
});

// Back with result
router.back({
  url: 'pages/HomePage',
  params: { result: 'success' }
});

Get Parameters

// In target page
aboutToAppear(): void {
  const params = router.getParams() as Record<string, Object>;
  if (params) {
    const id = params['id'] as number;
    const title = params['title'] as string;
  }
}

Get Router State

const state = router.getState();
console.log('Current page:', state.name);
console.log('Page path:', state.path);
console.log('Stack index:', state.index);

Clear Router Stack

router.clear();

---

HTTP Networking

import { http } from '@kit.NetworkKit';

GET Request

async function getData(): Promise<void> {
  const httpRequest = http.createHttp();
  
  try {
    const response = await httpRequest.request(
      'https://api.example.com/data',
      {
        method: http.RequestMethod.GET,
        header: {
          'Content-Type': 'application/json'
        },
        connectTimeout: 60000,
        readTimeout: 60000
      }
    );
    
    if (response.responseCode === 200) {
      const data = JSON.parse(response.result as string);
      console.log('Data:', JSON.stringify(data));
    }
  } catch (error) {
    console.error('Request failed:', error);
  } finally {
    httpRequest.destroy();
  }
}

POST Request

async function postData(body: object): Promise<void> {
  const httpRequest = http.createHttp();
  
  try {
    const response = await httpRequest.request(
      'https://api.example.com/submit',
      {
        method: http.RequestMethod.POST,
        header: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer token'
        },
        extraData: JSON.stringify(body)
      }
    );
    
    console.log('Response code:', response.responseCode);
  } finally {
    httpRequest.destroy();
  }
}

Request Options

interface HttpRequestOptions {
  method: http.RequestMethod;  // GET, POST, PUT, DELETE, etc.
  header?: Object;             // Request headers
  extraData?: string | Object; // Request body
  connectTimeout?: number;     // Connection timeout (ms)
  readTimeout?: number;        // Read timeout (ms)
  expectDataType?: http.HttpDataType;
}

---

Preferences Storage

import { preferences } from '@kit.ArkData';

Get Preferences Instance

// In component with context
const dataPreferences = await preferences.getPreferences(
  this.context, 
  'myPreferencesStore'
);

Write Data

await dataPreferences.put('username', 'John');
await dataPreferences.put('age', 25);
await dataPreferences.put('isVip', true);
await dataPreferences.put('scores', [90, 85, 92]);
await dataPreferences.flush();  // Persist to disk

Read Data

// With default values
const username = await dataPreferences.get('username', '') as string;
const age = await dataPreferences.get('age', 0) as number;
const isVip = await dataPreferences.get('isVip', false) as boolean;

Check Key Exists

const hasKey = await dataPreferences.has('username');

Delete Data

await dataPreferences.delete('username');
await dataPreferences.flush();

Clear All

await dataPreferences.clear();
await dataPreferences.flush();

Delete Preferences File

await preferences.deletePreferences(this.context, 'myPreferencesStore');

---

File Operations

import { fileIo as fs } from '@kit.CoreFileKit';

Get Application Paths

// In AbilityStage or UIAbility
const filesDir = this.context.filesDir;      // /data/app/.../files
const cacheDir = this.context.cacheDir;      // /data/app/.../cache
const tempDir = this.context.tempDir;        // /data/app/.../temp

Write File

const filePath = `${this.context.filesDir}/data.txt`;
const file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
fs.writeSync(file.fd, 'Hello, HarmonyOS!');
fs.closeSync(file);

Read File

const filePath = `${this.context.filesDir}/data.txt`;
const file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
const buffer = new ArrayBuffer(4096);
const readLen = fs.readSync(file.fd, buffer);
const content = String.fromCharCode(...new Uint8Array(buffer.slice(0, readLen)));
fs.closeSync(file);

Check File Exists

const exists = fs.accessSync(filePath);

Delete File

fs.unlinkSync(filePath);

List Directory

const files = fs.listFileSync(this.context.filesDir);
files.forEach((file: string) => {
  console.log('File:', file);
});

---

Device Info

import { deviceInfo } from '@kit.BasicServicesKit';

Get Device Information

const brand = deviceInfo.brand;           // e.g., "HUAWEI"
const model = deviceInfo.productModel;    // e.g., "Mate 60"
const osVersion = deviceInfo.osFullName;  // e.g., "HarmonyOS 5.0"
const sdkVersion = deviceInfo.sdkApiVersion;  // e.g., 12
const deviceType = deviceInfo.deviceType; // e.g., "phone", "tablet"

---

Prompt & Dialog

import { promptAction } from '@kit.ArkUI';

Toast

promptAction.showToast({
  message: 'Operation successful',
  duration: 2000,
  bottom: 80
});

Alert Dialog

promptAction.showDialog({
  title: 'Confirm',
  message: 'Are you sure you want to delete?',
  buttons: [
    { text: 'Cancel', color: '#999999' },
    { text: 'Delete', color: '#FF0000' }
  ]
}).then((result) => {
  if (result.index === 1) {
    // Delete confirmed
  }
});

Action Sheet

promptAction.showActionMenu({
  title: 'Select Option',
  buttons: [
    { text: 'Camera', color: '#000000' },
    { text: 'Gallery', color: '#000000' },
    { text: 'Cancel', color: '#999999' }
  ]
}).then((result) => {
  switch (result.index) {
    case 0: // Camera
      break;
    case 1: // Gallery
      break;
  }
});

Custom Dialog

@CustomDialog
struct ConfirmDialog {
  controller: CustomDialogController;
  title: string = '';
  onConfirm: () => void = () => {};
  
  build() {
    Column() {
      Text(this.title).fontSize(20).margin({ bottom: 20 })
      Row({ space: 20 }) {
        Button('Cancel')
          .onClick(() => { this.controller.close(); })
        Button('Confirm')
          .onClick(() => {
            this.onConfirm();
            this.controller.close();
          })
      }
    }
    .padding(20)
  }
}

// Usage in component
@Entry
@Component
struct DialogExample {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: ConfirmDialog({
      title: 'Delete Item?',
      onConfirm: () => { this.handleDelete(); }
    }),
    autoCancel: true
  });
  
  handleDelete(): void {
    // Delete logic
  }
  
  build() {
    Button('Show Dialog')
      .onClick(() => { this.dialogController.open(); })
  }
}

---

Media

Image Picker

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { picker } from '@kit.CoreFileKit';

async function pickImage(): Promise<string | null> {
  const photoPicker = new picker.PhotoViewPicker();
  
  try {
    const result = await photoPicker.select({
      MIMEType: picker.PhotoViewMIMETypes.IMAGE_TYPE,
      maxSelectNumber: 1
    });
    
    if (result.photoUris.length > 0) {
      return result.photoUris[0];
    }
  } catch (error) {
    console.error('Pick image failed:', error);
  }
  
  return null;
}

Camera Capture

import { camera } from '@kit.CameraKit';

// Request camera permission first
// Then use camera APIs for capture

Audio Playback

import { media } from '@kit.MediaKit';

async function playAudio(uri: string): Promise<void> {
  const player = await media.createAVPlayer();
  
  player.on('stateChange', (state: string) => {
    if (state === 'prepared') {
      player.play();
    }
  });
  
  player.url = uri;
}

---

Common Import Patterns

// UI Kit
import { router, promptAction } from '@kit.ArkUI';

// Network Kit
import { http } from '@kit.NetworkKit';

// Data Kit
import { preferences } from '@kit.ArkData';

// File Kit
import { fileIo as fs, picker } from '@kit.CoreFileKit';

// Basic Services
import { deviceInfo } from '@kit.BasicServicesKit';

// Media Kit
import { media } from '@kit.MediaKit';