name: arkts-syntax-assistant
description: |-
ArkTS syntax, migration, and optimization guide for HarmonyOS/OpenHarmony development.
Triggers on: .ets files, ArkTS keywords, HarmonyOS/OpenHarmony context, @ohos packages.
Help with syntax reference, TypeScript migration, performance optimization,
compile errors, state management, component development, and language-specific questions.
license: MIT
tags:
- arkts
- harmonyos
- typescript
- migration
- development
- syntax

ArkTS Syntax Assistant

中文文档

Overview

ArkTS is the default development language for OpenHarmony applications. It builds
upon TypeScript with enhanced static typing to improve program stability and
performance.

Core Features

• Static Typing: All types determined at compile time, reducing runtime checks
• No Dynamic Object Layout: Object structure fixed at compile time, cannot be
  modified at runtime
• Restricted Operators: Some operator behaviors are restricted to encourage
  clearer code semantics
• No Structural Typing: Structural typing is currently not supported

Reference Documentation

Workflows

1. Syntax Questions

User Question -> Identify Question Type -> Consult Documentation -> Provide Code Example

Common Syntax Questions:
- Variable declaration -> Use let/const with explicit type or inference
- Function definition -> Supports optional parameters, defaults, rest parameters,
arrow functions
- Classes and interfaces -> Must initialize fields, supports inheritance and
implementation
- Generics -> Supports constraints and default values
- Null safety -> Nullable types T | null, non-null assertion !, optional
chaining ?.

2. TypeScript Migration

Identify TS Code -> Check Incompatible Features -> Consult Migration Rules -> Provide ArkTS Alternative

Key Migration Rules Quick Reference:

3. Performance Optimization

Analyze Code -> Identify Performance Issues -> Consult Optimization Guide -> Provide Solutions

High-Performance Programming Key Points:

• Declarations: Use const for invariants; avoid mixing integer and float
• Loops: Extract loop invariants; avoid numeric overflow
• Functions: Parameter passing preferred over closures; avoid optional
  parameters
• Arrays: Use TypedArray for numeric values; avoid sparse arrays and union
  type arrays
• Exceptions: Avoid throwing in loops; use return values instead

4. Compile Error Resolution

Get Error Message -> Search Migration Rules -> Find Related Case -> Provide Fix

Common Questions

Q: How to handle JSON.parse return value?

// Error
let data = JSON.parse(str);

// Correct
let data: Record<string, Object> = JSON.parse(str);

Q: How to define object types?

// TypeScript syntax (not supported in ArkTS)
type Person = { name: string, age: number }

// ArkTS syntax
interface Person {
  name: string;
  age: number;
}

// Using object literal
let p: Person = { name: 'John', age: 25 };

Q: How to replace globalThis?

// Error
globalThis.value = 'xxx';

// Use singleton pattern
export class GlobalContext {
  private constructor() {}
  private static instance: GlobalContext;
  private _objects = new Map<string, Object>();

  public static getContext(): GlobalContext {
    if (!GlobalContext.instance) {
      GlobalContext.instance = new GlobalContext();
    }
    return GlobalContext.instance;
  }

  getObject(key: string): Object | undefined {
    return this._objects.get(key);
  }

  setObject(key: string, value: Object): void {
    this._objects.set(key, value);
  }
}

Q: How to handle error types in catch?

// Error
try {} catch (e: BusinessError) {}

// Correct
try {} catch (error) {
  let e: BusinessError = error as BusinessError;
}

Q: How to use Record type?

// TypeScript index signature
function foo(data: { [key: string]: string }) {}

// ArkTS Record
function foo(data: Record<string, string>) {}

// Usage example
let map: Record<string, number> = {
  'John': 25,
  'Mary': 21,
};

Q: How to replace constructor signatures with factory functions?

// TypeScript constructor signature
type ControllerCtor = {
  new (value: string): Controller;
}

// ArkTS factory function
type ControllerFactory = () => Controller;

class Menu {
  createController: ControllerFactory = () => {
    return new Controller('default');
  }
}

Prohibited Standard Library APIs

The following are prohibited in ArkTS:

• Global: eval
• Object: __proto__, defineProperty, freeze, getPrototypeOf, etc.
• Reflect: apply, construct, defineProperty, etc.
• Proxy: All handler methods

Build Scripts

The scripts directory provides quick compilation scripts for ArkTS projects
(including dependency installation):

Usage:

# macOS/Linux
bash scripts/run.sh

# Windows PowerShell
.\scripts\run.ps1

Script execution steps:
1. Install dependencies (ohpm install --all)
2. Build project (hvigorw assembleApp)

Mandatory Requirements

CRITICAL: When this skill generates ArkTS code, the following workflow MUST be followed:

1. Compilation Verification: After generating code, you MUST compile the project using the build scripts:
2. macOS/Linux: bash scripts/run.sh

3. Windows: .\scripts\run.ps1

4. Retry Strategy: If compilation fails:

5. Analyze the error output
6. Fix the issue and retry compilation

7. Maximum of 3 compilation attempts

8. User Intervention: After 3 failed compilation attempts, use AskUserQuestion:
   ```
   Question: Compilation failed after 3 attempts. How would you like to proceed?
   Options:

9. Continue retrying (attempt another fix)
10. Manual intervention (I'll wait for your guidance)

11. Skip compilation (proceed without verification)
    ```

12. Error Reporting: Always show the full compilation error output when failures occur.

Answer Guidelines

1. Prioritize code examples: Show correct vs incorrect syntax comparison
2. Reference official documentation: For detailed explanations, guide users to
   consult corresponding documents in references/
3. Explain reasons: Explain why ArkTS has this restriction (performance,
   stability)
4. Provide alternatives: For unsupported features, provide feasible
   alternatives

License

MIT License - see LICENSE.txt