deveco-harness 0.1.0

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

@@ -0,0 +1,295 @@
+# 未使用变量警告解决方案
+
+## 问题描述
+
+在 HarmonyOS ArkUI 开发中，当函数参数或变量被声明但未使用时，会触发编译警告：
+
+```
+'scrollState' is declared but its value is never read.
+```
+
+这个警告提示代码中存在未使用的变量，可能是遗漏了某些逻辑或者参数确实不需要。
+
+## 问题示例
+
+```typescript
+// ❌ 警告：scrollState 参数未使用
+.onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+## 推荐解决方案
+
+### 方案 1: 使用下划线前缀标记未使用参数
+
+```typescript
+// ✅ 推荐：使用下划线前缀
+.onDidScroll((scrollOffset: number, _scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+### 方案 2: 使用该参数
+
+```typescript
+// ✅ 可选：如果需要使用该参数
+.onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+  this.scrollState = scrollState;
+})
+```
+
+### 方案 3: 删除未使用的参数
+
+```typescript
+// ✅ 可选：如果确实不需要该参数
+.onDidScroll((scrollOffset: number) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+## 下划线前缀约定
+
+在 TypeScript/ArkTS 中，使用下划线 `_` 作为变量名前缀是一种常见的约定，表示该变量是故意未使用的：
+
+```typescript
+// 明确表示 scrollState 参数是故意未使用的
+function example(scrollOffset: number, _scrollState: ScrollState) {
+  console.log(scrollOffset);
+  // scrollState 不会被使用，但保留参数以保持 API 一致性
+}
+```
+
+## 迁移步骤
+
+### 1. 识别未使用变量警告
+
+```typescript
+// 查找编译警告中提到的变量
+.onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+### 2. 添加下划线前缀
+
+```typescript
+// 为未使用的参数添加下划线前缀
+.onDidScroll((scrollOffset: number, _scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+### 3. 或者使用该参数
+
+```typescript
+// 如果确实需要使用该参数
+.onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+  this.scrollState = scrollState;
+})
+```
+
+## 完整示例
+
+```typescript
+@Entry
+@Component
+struct ScrollExample {
+  @State scrollOffset: number = 0;
+  @State scrollState: ScrollState = ScrollState.Idle;
+  private scroller: Scroller = new Scroller();
+
+  build() {
+    Column() {
+      Text(`滚动偏移: ${this.scrollOffset}`)
+        .fontSize(16)
+        .margin({ bottom: 8 })
+      
+      Text(`滚动状态: ${this.getScrollStateName(this.scrollState)}`)
+        .fontSize(16)
+        .margin({ bottom: 16 })
+      
+      Scroll(this.scroller) {
+        Column() {
+          ForEach(Array.from({ length: 50 }), (_: Object, index: number) => {
+            Text(`Item ${index + 1}`)
+              .fontSize(16)
+              .padding(12)
+              .margin({ bottom: 8 })
+              .backgroundColor('#F5F5F5')
+              .borderRadius(4)
+          }, (_: Object, index: number) => `${index}`)
+        }
+        .width('100%')
+      }
+      .scrollable(ScrollDirection.Vertical)
+      .scrollBar(BarState.Auto)
+      .onDidScroll((scrollOffset: number, _scrollState: ScrollState) => {
+        // 使用下划线前缀标记未使用的 scrollState 参数
+        this.scrollOffset = scrollOffset;
+      })
+      .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+        // 在需要时使用 scrollState 参数
+        this.scrollOffset = scrollOffset;
+        this.scrollState = scrollState;
+      })
+    }
+    .width('100%')
+    .height('100%')
+    .padding(16)
+  }
+
+  private getScrollStateName(state: ScrollState): string {
+    switch (state) {
+      case ScrollState.Idle:
+        return 'Idle';
+      case ScrollState.Scroll:
+        return 'Scroll';
+      case ScrollState.Fling:
+        return 'Fling';
+      default:
+        return 'Unknown';
+    }
+  }
+}
+```
+
+> [查看完整示例](../assets/UnusedVariableWarning.ets)
+
+## 使用场景
+
+### 1. 事件回调中的未使用参数
+
+```typescript
+// ✅ 使用下划线前缀
+.onClick((_event: ClickEvent) => {
+  this.handleClick();
+})
+
+.onDidScroll((scrollOffset: number, _scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+### 2. ForEach 中的未使用参数
+
+```typescript
+// ✅ 使用下划线前缀
+ForEach(this.items, (_item: Item, index: number) => {
+  Text(`Item ${index}`)
+}, (item: Item, index: number) => `${index}`)
+```
+
+### 3. 函数参数中的未使用参数
+
+```typescript
+// ✅ 使用下划线前缀
+private processData(data: string, _options: ProcessOptions) {
+  return data.toUpperCase();
+}
+```
+
+### 4. 解构赋值中的未使用属性
+
+```typescript
+// ✅ 使用下划线前缀
+const { name, _id, _timestamp } = this.userData;
+console.log(name);
+```
+
+## 最佳实践
+
+### 1. 使用下划线前缀明确意图
+
+```typescript
+// 明确表示该参数是故意未使用的
+function example(required: string, _optional: string) {
+  console.log(required);
+}
+```
+
+### 2. 保持 API 一致性
+
+```typescript
+// 即使某些参数未使用，也保留它们以保持 API 一致性
+.onDidScroll((scrollOffset: number, _scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+})
+```
+
+### 3. 考虑是否真的不需要
+
+```typescript
+// 在添加下划线前缀前，考虑是否真的不需要该参数
+.onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
+  this.scrollOffset = scrollOffset;
+  // 也许未来会需要 scrollState？
+  this.scrollState = scrollState;
+})
+```
+
+### 4. 删除真正未使用的变量
+
+```typescript
+// 如果变量确实不需要，直接删除
+// ❌ 不好：保留未使用的变量
+const unused = calculateSomething();
+doSomething();
+
+// ✅ 好：删除未使用的变量
+doSomething();
+```
+
+## 注意事项
+
+1. **下划线前缀约定**：使用 `_` 作为前缀是 TypeScript 社区的常见约定
+
+2. **明确意图**：下划线前缀明确表示该变量是故意未使用的
+
+3. **保持一致性**：在项目中统一使用下划线前缀标记未使用变量
+
+4. **定期清理**：定期检查并删除真正未使用的变量和参数
+
+5. **代码审查**：在代码审查时关注未使用变量警告
+
+## 相关 API 参考
+
+- [TypeScript 未使用变量警告](https://www.typescriptlang.org/docs/handbook/compiler-options.html#noUnusedLocals)
+- [ArkTS 编译选项](https://developer.harmonyos.com/cn/docs/documentation/guides/arkts-getting-started)
+
+## 迁移检查清单
+
+- [ ] 识别所有未使用变量警告
+- [ ] 为确实不需要使用的参数添加下划线前缀
+- [ ] 考虑是否应该使用某些被标记为未使用的参数
+- [ ] 删除真正未使用的变量
+- [ ] 测试功能是否正常
+- [ ] 确认警告已消失
+
+## 常见问题
+
+### Q: 为什么要使用下划线前缀而不是删除参数？
+
+A: 有时需要保留参数以保持 API 一致性（如事件回调），下划线前缀明确表示这是故意的。
+
+### Q: 下划线前缀会影响运行时行为吗？
+
+A: 不会。下划线前缀只是一个命名约定，不会影响代码的执行。
+
+### Q: 可以在所有未使用变量上使用下划线前缀吗？
+
+A: 可以，但对于真正未使用的变量，建议删除而不是添加下划线前缀。
+
+### Q: 如何区分故意未使用和遗漏使用？
+
+A: 如果参数是 API 的一部分（如事件回调），使用下划线前缀；如果是临时变量，考虑删除。
+
+### Q: 编译器会自动处理未使用变量吗？
+
+A: 某些编译器选项会自动删除未使用的变量，但建议手动处理以保持代码清晰。
+
+### Q: ForEach 中的未使用参数如何处理？
+
+A: 使用下划线前缀标记未使用的参数，如 `(_item: Item, index: number)`。

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

@@ -0,0 +1,290 @@
+# Utility Type Errors
+
+## Error: Utility types not supported
+
+### Error Message
+```
+Some of utility types are not supported (arkts-no-utility-types)
+```
+
+### Cause
+ArkTS does not support TypeScript's utility types like `Parameters<T>`, `ReturnType<T>`, `Partial<T>`, etc. These utility types are part of TypeScript's advanced type system but are not compatible with ArkTS's stricter type system.
+
+### Solution
+Use explicit type definitions, interfaces, or type aliases instead of utility types. For function parameters, use `Object[]` or define explicit parameter types.
+
+### Key Points
+- ArkTS does not support TypeScript utility types
+- Use explicit type definitions instead
+- Use interfaces or type aliases for complex types
+- Use `Object[]` for rest parameters
+- Define function types explicitly
+
+### ❌ Wrong Usage
+```typescript
+// ❌ Wrong: Using Parameters<T>
+function debounce<T extends (...args: any[]) => void>(func: T, delay: number): T {
+  return ((...args: Parameters<T>) => {
+    setTimeout(() => func(...args), delay);
+  }) as T;
+}
+
+// ❌ Wrong: Using ReturnType<T>
+type Handler = () => string;
+type Result = ReturnType<Handler>;
+
+// ❌ Wrong: Using Partial<T>
+interface Config {
+  width: number;
+  height: number;
+  color?: string;
+}
+const partial: Partial<Config> = { width: 100 };
+```
+
+### ✅ Correct Usage
+```typescript
+// ✅ Correct: Using Object[] for rest parameters
+function debounce(func: Function, delay: number): Function {
+  return (...args: Object[]): void => {
+    setTimeout(() => func(...args), delay);
+  };
+}
+
+// ✅ Correct: Using explicit type
+type Handler = () => string;
+type Result = string;
+
+// ✅ Correct: Using optional properties
+interface Config {
+  width: number;
+  height: number;
+  color?: string;
+}
+const partial: Config = { width: 100, height: 0, color: undefined };
+```
+
+### Function Type Definitions
+
+#### Using Explicit Types
+```typescript
+// ✅ Correct: Explicit function type
+private handleClick = (event: ClickEvent): void => {
+  this.count++;
+};
+
+// ✅ Correct: Explicit return type
+private getValue(): string {
+  return 'Hello';
+}
+```
+
+#### Using Interfaces
+```typescript
+// ✅ Correct: Interface for function type
+interface EventHandler {
+  (event: ClickEvent): void;
+}
+
+private handleClick: EventHandler = (event: ClickEvent): void => {
+  console.info('Clicked');
+};
+```
+
+#### Using Type Aliases
+```typescript
+// ✅ Correct: Type alias for function type
+type ClickHandler = (event: ClickEvent) => void;
+
+private handleClick: ClickHandler = (event: ClickEvent): void => {
+  console.info('Clicked');
+};
+```
+
+### Rest Parameters
+
+#### ❌ Wrong
+```typescript
+// ❌ Wrong: Using Parameters<T>
+function wrapper<T extends (...args: any[]) => void>(func: T): void {
+  return (...args: Parameters<T>) => {
+    func(...args);
+  };
+}
+```
+
+#### ✅ Correct
+```typescript
+// ✅ Correct: Using Object[]
+function wrapper(func: Function): Function {
+  return (...args: Object[]): void => {
+    func(...args);
+  };
+}
+
+// ✅ Correct: Using explicit types
+function wrapper(func: (x: number, y: number) => void): (x: number, y: number) => void {
+  return (x: number, y: number): void => {
+    func(x, y);
+  };
+}
+```
+
+### Debounce Implementation
+
+#### ❌ Wrong
+```typescript
+class DebounceUtil {
+  private timeoutId: number = -1;
+
+  debounce<T extends (...args: any[]) => void>(func: T, delay: number): T {
+    return ((...args: Parameters<T>) => {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = setTimeout(() => {
+        func(...args);
+      }, delay);
+    }) as T;
+  }
+}
+```
+
+#### ✅ Correct
+```typescript
+class DebounceUtil {
+  private timeoutId: number = -1;
+
+  debounce(func: Function, delay: number): Function {
+    return (...args: Object[]): void => {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = setTimeout(() => {
+        func(...args);
+      }, delay);
+    };
+  }
+}
+
+// ✅ Correct: With explicit types
+class DebounceUtil {
+  private timeoutId: number = -1;
+
+  debounce(func: (event: ClickEvent) => void, delay: number): (event: ClickEvent) => void {
+    return (event: ClickEvent): void => {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = setTimeout(() => {
+        func(event);
+      }, delay);
+    };
+  }
+}
+```
+
+### Generic Functions
+
+#### ❌ Wrong
+```typescript
+// ❌ Wrong: Using utility types
+function wrap<T extends (...args: any[]) => R, R>(func: T): T {
+  return func;
+}
+```
+
+#### ✅ Correct
+```typescript
+// ✅ Correct: Using explicit types
+function wrap(func: (x: number, y: number) => number): (x: number, y: number) => number {
+  return func;
+}
+
+// ✅ Correct: Using interfaces
+interface BinaryFunction {
+  (x: number, y: number): number;
+}
+
+function wrap(func: BinaryFunction): BinaryFunction {
+  return func;
+}
+```
+
+### Common Patterns
+
+#### Event Handlers
+```typescript
+// ✅ Correct: Event handler type
+type ClickHandler = (event: ClickEvent) => void;
+type TouchHandler = (event: TouchEvent) => void;
+type ScrollHandler = (event: ScrollEvent) => void;
+
+@Component
+struct EventHandlers {
+  private onClick: ClickHandler = (event: ClickEvent): void => {
+    console.info('Clicked');
+  };
+
+  private onTouch: TouchHandler = (event: TouchEvent): void => {
+    console.info('Touched');
+  };
+
+  build() {
+    Column() {
+      Button('Click')
+        .onClick(this.onClick)
+    }
+    .onTouch(this.onTouch)
+  }
+}
+```
+
+#### Callback Functions
+```typescript
+// ✅ Correct: Callback type
+interface SuccessCallback {
+  (data: string): void;
+}
+
+interface ErrorCallback {
+  (error: Error): void;
+}
+
+class DataFetcher {
+  fetchData(success: SuccessCallback, error: ErrorCallback): void {
+    try {
+      success('Data loaded');
+    } catch (e) {
+      error(e as Error);
+    }
+  }
+}
+```
+
+#### Utility Functions
+```typescript
+// ✅ Correct: Utility function types
+type Mapper<T, R> = (item: T, index: number) => R;
+type Filter<T> = (item: T, index: number) => boolean;
+type Reducer<T, R> = (acc: R, item: T, index: number) => R;
+
+class ArrayUtils {
+  static map<T, R>(array: T[], mapper: Mapper<T, R>): R[] {
+    return array.map(mapper);
+  }
+
+  static filter<T>(array: T[], filter: Filter<T>): T[] {
+    return array.filter(filter);
+  }
+
+  static reduce<T, R>(array: T[], reducer: Reducer<T, R>, initial: R): R {
+    return array.reduce(reducer, initial);
+  }
+}
+```
+
+### Best Practices
+1. **Use explicit types**: Always define function types explicitly
+2. **Use interfaces**: Define interfaces for complex function types
+3. **Use type aliases**: Create type aliases for reusable function types
+4. **Avoid utility types**: Don't use TypeScript utility types
+5. **Use Object[]**: Use `Object[]` for rest parameters
+
+### Related Files
+- [Code Example](../assets/UtilityTypeError.ets)
+- [ArkTS Type System](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-type-system)

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

@@ -0,0 +1,70 @@
+# window.Rect 和 window.Size 类型错误
+
+## 常见错误
+
+### 1. window.Point 不存在
+
+```
+Property 'Point' does not exist on type 'Namespace window'
+```
+
+### 2. window.Size 不存在
+
+```
+Property 'size' does not exist on type 'WindowProperties'
+```
+
+### 3. window.Rect 属性访问错误
+
+```
+Property 'x' does not exist on type 'Rect'
+Property 'y' does not exist on type 'Rect'
+```
+
+## 错误原因
+
+- `window.Rect` 使用 `left/top` 而非 `x/y`
+- `WindowProperties` 没有 `size` 属性，需要从 `windowRect` 获取
+- `window.Point` 类型不存在
+
+## 解决方案
+
+### window.Rect 正确使用
+
+```typescript
+// window.Rect 有 left, top, width, height 属性
+const rect: window.Rect = { left: 0, top: 0, width: 100, height: 100 };
+```
+
+### 从 WindowProperties 获取尺寸
+
+```typescript
+const properties = win.getWindowProperties();
+const rect = properties.windowRect;
+const width = rect.width;
+const height = rect.height;
+```
+
+### windowSizeChange 事件回调
+
+```typescript
+win.on('windowSizeChange', (size: window.Size) => {
+  // size 有 width 和 height 属性
+  this.windowRect = {
+    left: this.windowRect.left,
+    top: this.windowRect.top,
+    width: size.width,
+    height: size.height
+  };
+});
+```
+
+## 详细代码示例
+
+请参考 [WindowRectSizeError.ets](../assets/WindowRectSizeError.ets)
+
+## 相关 API
+
+- [WindowProperties](https://developer.harmonyos.com/cn/docs/documentation/reference/apis-arkui-window-0000001774129417)
+- [window.Rect](https://developer.harmonyos.com/cn/docs/documentation/reference/apis-arkui-window-0000001774129417)
+- [window.Size](https://developer.harmonyos.com/cn/docs/documentation/reference/apis-arkui-window-0000001774129417)