deveco-harness 0.1.0

package/skills/arkts-error-fixes/reference/context_type_errors.md

@@ -0,0 +1,260 @@
+# Context 类型错误解决方案
+
+## 问题描述
+
+在 HarmonyOS ArkUI 开发中，使用 `this.getUIContext().getHostContext()` 获取的 Context 类型为 `Context | undefined`，直接传递给需要 `Context` 类型参数的函数会触发类型错误：
+
+```
+Argument of type 'Context | undefined' is not assignable to parameter of type 'Context'.
+```
+
+## 问题示例
+
+```typescript
+// ❌ 错误：Context 可能为 undefined
+const context = this.getUIContext().getHostContext();
+await window.getLastWindow(context);  // 类型错误
+```
+
+## 推荐解决方案
+
+### 方案 1: 添加 null 检查
+
+```typescript
+// ✅ 推荐：添加 null 检查
+const context = this.getUIContext().getHostContext();
+if (context) {
+  await window.getLastWindow(context);
+}
+```
+
+### 方案 2: 使用类型断言
+
+```typescript
+// ✅ 可选：使用类型断言
+const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
+await window.getLastWindow(context);
+```
+
+### 方案 3: 使用可选链和空值合并
+
+```typescript
+// ✅ 可选：使用可选链
+const context = this.getUIContext().getHostContext();
+if (context) {
+  await window.getLastWindow(context);
+}
+```
+
+## 迁移步骤
+
+### 1. 识别 Context 类型错误
+
+```typescript
+// 查找代码中的 Context 使用
+const context = this.getUIContext().getHostContext();
+window.getLastWindow(context);  // 类型错误
+```
+
+### 2. 添加 null 检查
+
+```typescript
+const context = this.getUIContext().getHostContext();
+if (context) {
+  window.getLastWindow(context);  // 正确
+}
+```
+
+### 3. 使用类型断言（可选）
+
+```typescript
+const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
+window.getLastWindow(context);  // 正确
+```
+
+## 完整示例
+
+```typescript
+import { window } from '@kit.ArkUI';
+import { common } from '@kit.AbilityKit';
+
+@Entry
+@Component
+struct ContextTypeExample {
+  @State windowWidth: number = 0;
+  @State windowHeight: number = 0;
+
+  async aboutToAppear() {
+    // ✅ 正确：添加 null 检查
+    const context = this.getUIContext().getHostContext();
+    if (context) {
+      await this.getWindowSize(context as common.UIAbilityContext);
+    }
+  }
+
+  private async getWindowSize(context: common.UIAbilityContext) {
+    try {
+      const win = await window.getLastWindow(context);
+      const properties = win.getWindowProperties();
+      this.windowWidth = properties.windowRect.width;
+      this.windowHeight = properties.windowRect.height;
+    } catch (err) {
+      console.error('获取窗口大小失败:', err);
+    }
+  }
+
+  build() {
+    Column() {
+      Text(`窗口大小: ${this.windowWidth} x ${this.windowHeight}`)
+        .fontSize(16)
+    }
+    .width('100%')
+    .height('100%')
+    .padding(16)
+  }
+}
+```
+
+> [查看完整示例](../assets/ContextTypeError.ets)
+
+## 使用场景
+
+### 1. 窗口操作
+
+```typescript
+async operateWindow() {
+  const context = this.getUIContext().getHostContext();
+  if (context) {
+    const win = await window.getLastWindow(context);
+    await win.resize(800, 600);
+  }
+}
+```
+
+### 2. 媒体查询
+
+```typescript
+setupMediaQuery() {
+  const context = this.getUIContext().getHostContext();
+  if (context) {
+    const mediaQuery = this.getUIContext().getMediaQuery();
+    const listener = mediaQuery.matchMediaSync('(min-width: 600vp)');
+    listener.on('change', (result) => {
+      console.info(`Matches: ${result.matches}`);
+    });
+  }
+}
+```
+
+### 3. 文件操作
+
+```typescript
+async readFile() {
+  const context = this.getUIContext().getHostContext();
+  if (context) {
+    const filesDir = context.filesDir;
+    // 读取文件操作
+  }
+}
+```
+
+## 最佳实践
+
+### 1. 始终添加 null 检查
+
+```typescript
+const context = this.getUIContext().getHostContext();
+if (!context) {
+  console.error('Context is undefined');
+  return;
+}
+// 使用 context
+```
+
+### 2. 使用类型断言明确类型
+
+```typescript
+const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
+```
+
+### 3. 封装 Context 获取
+
+```typescript
+private getSafeContext(): common.UIAbilityContext | null {
+  const context = this.getUIContext().getHostContext();
+  return context ? context as common.UIAbilityContext : null;
+}
+
+async operateWindow() {
+  const context = this.getSafeContext();
+  if (context) {
+    const win = await window.getLastWindow(context);
+    // 操作窗口
+  }
+}
+```
+
+### 4. 处理异步操作
+
+```typescript
+async asyncOperation() {
+  const context = this.getUIContext().getHostContext();
+  if (context) {
+    try {
+      const win = await window.getLastWindow(context);
+      // 异步操作
+    } catch (err) {
+      console.error('操作失败:', err);
+    }
+  }
+}
+```
+
+## 注意事项
+
+1. **类型定义**：`getHostContext()` 返回 `Context | undefined`，必须处理 undefined 情况
+
+2. **null 检查**：建议使用 `if (context)` 检查，而不是直接使用
+
+3. **类型断言**：使用 `as common.UIAbilityContext` 明确类型，但确保类型正确
+
+4. **异常处理**：在异步操作中添加 try-catch 处理可能的异常
+
+5. **封装复用**：可以将 Context 获取逻辑封装为工具函数
+
+## 相关 API 参考
+
+- [UIContext.getHostContext()](https://developer.harmonyos.com/cn/docs/documentation/reference/arkui-ts/ts-methods-uicontext)
+- [Context](https://developer.harmonyos.com/cn/docs/documentation/reference/apis-js-apis-application-context)
+- [window.getLastWindow()](https://developer.harmonyos.com/cn/docs/documentation/reference/apis-arkui-window-0000001774529169)
+
+## 迁移检查清单
+
+- [ ] 识别所有使用 `getHostContext()` 的地方
+- [ ] 添加 null 检查处理 undefined 情况
+- [ ] 使用类型断言明确 Context 类型
+- [ ] 添加异常处理
+- [ ] 测试功能是否正常
+- [ ] 确认类型错误已解决
+
+## 常见问题
+
+### Q: 为什么 `getHostContext()` 可能返回 undefined？
+
+A: 在某些情况下（如组件未完全初始化），Context 可能尚未准备好，因此返回 undefined。
+
+### Q: 可以使用非空断言 `!` 吗？
+
+A: 可以，但不推荐。使用 `!` 会跳过类型检查，可能导致运行时错误。建议使用 null 检查。
+
+### Q: 什么时候应该使用类型断言？
+
+A: 当你确定 Context 的具体类型（如 `UIAbilityContext`）时，可以使用类型断言提高代码可读性。
+
+### Q: 如何在多个地方复用 Context？
+
+A: 可以封装一个工具函数或在组件中定义一个私有方法来安全地获取 Context。
+
+### Q: null 检查会影响性能吗？
+
+A: 不会。null 检查是非常轻量级的操作，对性能影响可以忽略不计。

package/skills/arkts-error-fixes/reference/decorator_state_errors.md

@@ -0,0 +1,109 @@
+# @State 装饰器错误
+
+## 错误描述
+
+在 ArkTS 中，`@State` 装饰器只能用于 `@Component` 修饰的 struct 中，不能用于普通 class。
+
+## 错误示例
+
+```typescript
+// ❌ AI 经常生成的错误代码
+class FoldableStateManager {
+  @State currentBreakpoint: string = 'sm';
+  @State isFolded: boolean = true;
+
+  aboutToAppear() {
+    // ...
+  }
+}
+```
+
+**错误信息：**
+```
+The '@State' decorator can only be used with 'struct'.
+```
+
+## 原因分析
+
+`@State` 是 ArkUI 框架的状态管理装饰器，用于在组件内部管理状态。它只能与 `@Component` 一起使用，不能用于普通类。
+
+## 解决方案
+
+### 方案1：移除 @State 装饰器（推荐用于非组件类）
+
+如果类不需要响应式状态管理，移除 `@State` 装饰器：
+
+```typescript
+// ✅ 正确的代码
+class FoldableStateManager {
+  currentBreakpoint: string = 'sm';
+  isFolded: boolean = true;
+
+  aboutToAppear() {
+    // ...
+  }
+}
+```
+
+### 方案2：使用 @Component struct（推荐用于状态管理）
+
+如果需要状态管理，将类改为 @Component struct：
+
+```typescript
+// ✅ 正确的代码
+@Component
+struct FoldableStateManager {
+  @State currentBreakpoint: string = 'sm';
+  @State isFolded: boolean = true;
+
+  aboutToAppear() {
+    // ...
+  }
+
+  build() {
+    // UI 组件
+  }
+}
+```
+
+## 简单示例
+
+### 用于工具类
+
+```typescript
+// ✅ 用于工具类时移除 @State
+class DisplayManager {
+  currentBreakpoint: string = 'sm';
+
+  updateBreakpoint(width: number): string {
+    if (width < 600) return 'sm';
+    if (width < 840) return 'md';
+    return 'lg';
+  }
+}
+```
+
+### 用于 @Component struct
+
+```typescript
+// ✅ 用于组件时保留 @State
+@Component
+struct AdaptiveLayout {
+  @State currentBreakpoint: string = 'sm';
+
+  build() {
+    Column() {
+      Text(`Current: ${this.currentBreakpoint}`)
+    }
+  }
+}
+```
+
+## 详细代码示例
+
+> [DecoratorStateError.ets](../assets/DecoratorStateError.ets) - 完整的 @State 装饰器错误示例和修复方案
+
+## 相关文档
+
+- [ArkTS 状态管理](./state_migration.md)
+- [HarmonyOS 官方文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-state-management-overview)

package/skills/arkts-error-fixes/reference/display_listener_type_errors.md

@@ -0,0 +1,149 @@
+# Display Listener Type Errors
+
+## Error: Display on/off method type error
+
+### Error Message
+```
+Type 'void' is not assignable to type 'number'
+Argument of type 'number' is not assignable to parameter of type 'Callback<Rect>'
+```
+
+### Cause
+The `display.on()` and `display.off()` methods are module-level methods, not instance methods of the `Display` class. Attempting to call them on a `Display` object instance causes type errors.
+
+### Solution
+Use `display.on()` and `display.off()` at the module level for listening to display changes. Use `Display.on()` and `Display.off()` on Display instances for instance-specific events like `availableAreaChange`.
+
+### Key Points
+- `display.on('add'|'remove'|'change', callback)` - Module level methods
+- `Display.on('availableAreaChange', callback)` - Instance level methods
+- `Display.on('foldStatusChange', callback)` - Instance level methods
+- `Display.on('captureStatusChange', callback)` - Instance level methods
+
+### Module Level Listeners
+```typescript
+import { display } from '@kit.ArkUI';
+
+// ✅ Correct: Module level listener
+let listener: (data: number) => void = (data: number) => {
+  console.info(`Display changed, ID: ${data}`);
+};
+
+display.on('change', listener);
+
+// Unregister
+display.off('change', listener);
+```
+
+### Instance Level Listeners
+```typescript
+import { display } from '@kit.ArkUI';
+
+const displayClass = display.getDefaultDisplaySync();
+
+// ✅ Correct: Instance level listener
+let areaListener: (data: display.Rect) => void = (data: display.Rect) => {
+  console.info(`Available area changed: ${JSON.stringify(data)}`);
+};
+
+displayClass.on('availableAreaChange', areaListener);
+
+// Unregister
+displayClass.off('availableAreaChange', areaListener);
+```
+
+### ❌ Wrong Usage
+```typescript
+const displayClass = display.getDefaultDisplaySync();
+
+// ❌ Wrong: Calling on() on Display instance
+let listener = displayClass.on('change', () => {
+  console.info('Display changed');
+});
+
+// ❌ Wrong: Calling off() on Display instance
+displayClass.off('change', listener);
+```
+
+### ✅ Correct Usage
+```typescript
+// ✅ Correct: Module level for display changes
+let changeListener: (data: number) => void = (data: number) => {
+  console.info(`Display changed, ID: ${data}`);
+};
+display.on('change', changeListener);
+
+// ✅ Correct: Instance level for available area changes
+const displayClass = display.getDefaultDisplaySync();
+let areaListener: (data: display.Rect) => void = (data: display.Rect) => {
+  console.info(`Available area changed: ${JSON.stringify(data)}`);
+};
+displayClass.on('availableAreaChange', areaListener);
+```
+
+### Available Listener Types
+
+#### Module Level (display module)
+- `on('add', callback: Callback<number>)` - Display added
+- `on('remove', callback: Callback<number>)` - Display removed
+- `on('change', callback: Callback<number>)` - Display changed
+
+#### Instance Level (Display object)
+- `on('availableAreaChange', callback: Callback<Rect>)` - Available area changed
+- `on('foldStatusChange', callback: Callback<FoldStatus>)` - Fold status changed
+- `on('captureStatusChange', callback: Callback<boolean>)` - Capture status changed
+
+### Best Practices
+1. **Use module level** for display add/remove/change events
+2. **Use instance level** for display-specific events
+3. **Always unregister** listeners in aboutToDisappear()
+4. **Store listener references** for proper cleanup
+5. **Use explicit types** for listener callbacks
+
+### Component Integration
+```typescript
+@Entry
+@Component
+struct DisplayListenerExample {
+  private changeListener?: (data: number) => void;
+  private areaListener?: (data: display.Rect) => void;
+
+  aboutToAppear() {
+    // Register module level listener
+    this.changeListener = (data: number) => {
+      console.info(`Display changed: ${data}`);
+    };
+    display.on('change', this.changeListener);
+
+    // Register instance level listener
+    const displayClass = display.getDefaultDisplaySync();
+    this.areaListener = (data: display.Rect) => {
+      console.info(`Area changed: ${JSON.stringify(data)}`);
+    };
+    displayClass.on('availableAreaChange', this.areaListener);
+  }
+
+  aboutToDisappear() {
+    // Unregister listeners
+    if (this.changeListener) {
+      display.off('change', this.changeListener);
+      this.changeListener = undefined;
+    }
+    if (this.areaListener) {
+      const displayClass = display.getDefaultDisplaySync();
+      displayClass.off('availableAreaChange', this.areaListener);
+      this.areaListener = undefined;
+    }
+  }
+
+  build() {
+    Column() {
+      Text('Display Listener Example')
+    }
+  }
+}
+```
+
+### Related Files
+- [Code Example](../assets/DisplayListenerTypeError.ets)
+- [Display API Documentation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-display)

package/skills/arkts-error-fixes/reference/duplicate_entry_errors.md

@@ -0,0 +1,193 @@
+# 多个 @Entry 装饰器错误
+
+## 问题描述
+
+在 ArkTS 中，一个 `.ets` 文件只能有一个 `@Entry` 装饰器。如果在同一个文件中使用多个 `@Entry` 装饰器，会导致编译错误。
+
+### 错误信息
+
+```
+Duplicate entry annotation
+```
+
+或
+
+```
+More than one @Entry decorator in the same file
+```
+
+## 错误示例
+
+```typescript
+// ❌ 错误：一个文件中有两个 @Entry
+@Entry
+@Component
+struct FirstPage {
+  build() {
+    Column() {
+      Text('Page 1')
+    }
+  }
+}
+
+@Entry
+@Component
+struct SecondPage {
+  build() {
+    Column() {
+      Text('Page 2')
+    }
+  }
+}
+```
+
+## 解决方案
+
+### 方案一：将子组件改为普通 @Component（推荐）
+
+将多余的 `@Entry` 改为普通 `@Component`，避免重复的入口声明。
+
+```typescript
+// ✅ 正确：只有一个 @Entry，其他用 @Component
+@Entry
+@Component
+struct MainPage {
+  build() {
+    Column() {
+      Text('Main Page')
+      ChildComponent()
+    }
+  }
+}
+
+@Component
+struct ChildComponent {
+  build() {
+    Text('Child Component')
+  }
+}
+```
+
+### 方案二：拆分到不同文件
+
+将每个页面组件拆分到独立的文件中。
+
+```typescript
+// mainPage.ets
+@Entry
+@Component
+struct MainPage {
+  build() {
+    Column() {
+      Text('Main Page')
+    }
+  }
+}
+```
+
+```typescript
+// subPage.ets - 单独的文件
+@Entry
+@Component
+struct SubPage {
+  build() {
+    Column() {
+      Text('Sub Page')
+    }
+  }
+}
+```
+
+### 方案三：使用状态管理实现多页面
+
+如果需要在多个视图之间切换，可以使用 `@State` 和条件渲染：
+
+```typescript
+@Entry
+@Component
+struct MultiViewPage {
+  @State currentView: number = 0;
+
+  build() {
+    Column() {
+      if (this.currentView === 0) {
+        ViewOne()
+      } else {
+        ViewTwo()
+      }
+
+      Row() {
+        Button('View 1')
+          .onClick(() => this.currentView = 0)
+        Button('View 2')
+          .onClick(() => this.currentView = 1)
+      }
+    }
+  }
+}
+
+@Component
+struct ViewOne {
+  build() {
+    Text('View 1').fontSize(24)
+  }
+}
+
+@Component
+struct ViewTwo {
+  build() {
+    Text('View 2').fontSize(24)
+  }
+}
+```
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct PageExample {
+  @State message: string = 'Hello';
+
+  build() {
+    Column() {
+      Text(this.message)
+        .fontSize(24)
+
+      // 使用 @Component 装饰的子组件
+      ContentSection()
+    }
+    .width('100%')
+    .height('100%')
+    .padding(20)
+  }
+}
+
+@Component
+struct ContentSection {
+  @State count: number = 0;
+
+  build() {
+    Column() {
+      Text(`Count: ${this.count}`)
+        .fontSize(18)
+
+      Button('Add')
+        .onClick(() => {
+          this.count++;
+        })
+    }
+  }
+}
+```
+
+## 详细代码示例
+
+- [DuplicateEntryError.ets](../assets/DuplicateEntryError.ets) - 完整的多个 @Entry 错误修复示例
+
+## 最佳实践
+
+1. **每个文件一个 @Entry**：保持每个 `.ets` 文件只有一个入口组件
+2. **使用 @Component 复用 UI**：使用 `@Component` 装饰器创建可复用的 UI 组件
+3. **合理拆分文件**：将不同页面拆分到独立文件，便于管理和维护
+4. **状态提升**：如果多个组件需要共享状态，将状态提升到共同的父组件中