deveco-harness 0.1.0

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

@@ -0,0 +1,110 @@
+# ESObject 类型限制错误
+
+## 错误描述
+
+在 ArkTS 中，`ESObject` 类型的使用受到限制，不能直接用作变量类型声明。这是为了确保类型安全和避免运行时错误。
+
+## 错误示例
+
+```typescript
+let nfcModule: ESObject = null;
+```
+
+**错误信息：**
+```
+Usage of "ESObject" type is restricted (arkts-limited-esobj)
+```
+
+## 解决方案
+
+### 方案1：使用动态导入（推荐）
+
+对于需要动态导入的模块，使用 `import()` 函数并使用 `Promise` 或 `ESModule` 类型。
+
+```typescript
+let nfcModule: ESModule | null = null;
+try {
+  nfcModule = import('@kit.ConnectivityKit');
+} catch (err) {
+  console.error(`Failed to import NFC module: ${JSON.stringify(err)}`);
+}
+```
+
+### 方案2：使用具体类型
+
+如果知道模块的具体类型，使用具体的接口或类。
+
+```typescript
+import { nfcController } from '@kit.ConnectivityKit';
+
+let nfcControllerInstance: nfcController.NfcController | null = null;
+```
+
+### 方案3：使用 unknown 类型
+
+如果不确定模块类型，可以使用 `unknown` 类型，但需要在使用时进行类型检查。
+
+```typescript
+let module: unknown = null;
+try {
+  module = import('@kit.ConnectivityKit');
+  if (module !== null && module !== undefined) {
+    // 使用前进行类型检查
+    console.info('Module imported successfully');
+  }
+} catch (err) {
+  console.error(`Failed to import module: ${JSON.stringify(err)}`);
+}
+```
+
+## 详细说明
+
+ArkTS 限制 `ESObject` 类型的使用是为了：
+
+1. **类型安全**：避免运行时类型错误
+2. **编译时检查**：确保类型使用的正确性
+3. **模块系统规范**：遵循 ES 模块标准
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct DynamicImportExample {
+  @State moduleLoaded: boolean = false;
+  @State moduleName: string = '';
+
+  async loadNFCModule() {
+    try {
+      const nfcModule = await import('@kit.ConnectivityKit');
+      this.moduleLoaded = true;
+      this.moduleName = 'NFC';
+      console.info('NFC module imported successfully');
+    } catch (err) {
+      console.error(`Failed to import NFC module: ${JSON.stringify(err)}`);
+      this.moduleLoaded = false;
+      this.moduleName = 'NFC';
+    }
+  }
+
+  build() {
+    Column() {
+      Button('Load NFC Module')
+        .onClick(() => {
+          this.loadNFCModule();
+        })
+        .margin(20)
+
+      if (this.moduleLoaded) {
+        Text(`${this.moduleName} module loaded successfully`)
+          .fontSize(16)
+          .margin(20)
+      }
+    }
+  }
+}
+```
+
+## 详细代码示例
+
+> [ESObjectTypeError.ets](../assets/ESObjectTypeError.ets) - 完整的ESObject类型错误示例和修复方案

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

@@ -0,0 +1,104 @@
+# fontColor 属性错误
+
+## 错误描述
+
+`fontColor` 属性只能用于文本组件（如 `Text`、`Span`、`Button` 等），不能用于容器组件（如 `Column`、`Row`、`Stack` 等）。在容器组件上使用 `fontColor` 会导致编译错误。
+
+## 错误示例
+
+```typescript
+@Entry
+@Component
+struct FontColorError {
+  build() {
+    Column() {
+      Text('Hello World')
+    }
+    .fontColor('#FF0000')
+  }
+}
+```
+
+**错误信息：**
+```
+Property 'fontColor' does not exist on type 'ColumnAttribute'
+```
+
+## 解决方案
+
+### 方案一：将 fontColor 应用到 Text 组件
+
+将 `fontColor` 属性从容器组件移除，直接应用到文本组件上。
+
+```typescript
+@Entry
+@Component
+struct FontColorCorrect {
+  build() {
+    Column() {
+      Text('Hello World')
+        .fontColor('#FF0000')
+    }
+  }
+}
+```
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct FontColorExample {
+  build() {
+    Column() {
+      Text('标题')
+        .fontSize(20)
+        .fontWeight(FontWeight.Bold)
+        .fontColor('#333333')
+      
+      Text('内容')
+        .fontSize(16)
+        .fontColor('#666666')
+    }
+    .width('100%')
+    .padding(16)
+  }
+}
+```
+
+## 详细代码示例
+
+- [FontColorPropertyError.ets](../assets/FontColorPropertyError.ets) - 完整的 fontColor 属性错误修复示例，包含正确和错误的用法对比
+
+## 最佳实践
+
+1. **仅在文本组件上使用 fontColor**：`fontColor` 属性应该只用于 `Text`、`Span`、`Button` 等文本组件
+2. **使用十六进制颜色值**：推荐使用十六进制颜色值（如 `#FF0000`）而不是 `Color` 枚举
+3. **定义颜色常量**：对于重复使用的颜色，建议定义常量
+4. **使用资源引用**：对于主题相关的颜色，使用资源引用以便于主题切换
+
+## 常见错误
+
+```typescript
+// ❌ 错误：在 Column 上使用 fontColor
+Column() {
+  Text('Hello')
+}
+.fontColor('#FF0000')
+
+// ❌ 错误：在 Row 上使用 fontColor
+Row() {
+  Text('Hello')
+}
+.fontColor('#FF0000')
+
+// ✅ 正确：在 Text 上使用 fontColor
+Column() {
+  Text('Hello')
+    .fontColor('#FF0000')
+}
+
+// ✅ 正确：在 Button 上使用 fontColor
+Button('Click Me')
+  .fontColor('#FFFFFF')
+```

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

@@ -0,0 +1,194 @@
+# Function Return Type Errors
+
+## Error: `Object literals cannot be used as type declarations`
+
+### Error Message
+```
+Object literals cannot be used as type declarations (arkts-no-obj-literals-as-types)
+```
+
+### Cause
+ArkTS does not allow object literal types (like `{ width: number; height: number }`) to be used directly as return type annotations. You must define an interface or type alias first.
+
+### Solution
+Define an interface for the object shape, then use that interface as the return type.
+
+### Basic Pattern
+```typescript
+// ❌ Wrong: Object literal type in return annotation
+private getWindowInfo(): { width: number; height: number } {
+  return {
+    width: 1080,
+    height: 2340
+  };
+}
+
+// ✅ Correct: Define interface first
+interface WindowInfo {
+  width: number;
+  height: number;
+}
+
+private getWindowInfo(): WindowInfo {
+  return {
+    width: 1080,
+    height: 2340
+  };
+}
+```
+
+### Simple Example
+```typescript
+interface WindowInfo {
+  width: number;
+  height: number;
+}
+
+@Entry
+@Component
+struct WindowInfoExample {
+  @State windowWidth: number = 0;
+  @State windowHeight: number = 0;
+
+  private getWindowInfo(): WindowInfo {
+    return {
+      width: 1080,
+      height: 2340
+    };
+  }
+
+  build() {
+    Column() {
+      Text(`Window: ${this.windowWidth} x ${this.windowHeight}`)
+    }
+  }
+}
+```
+
+### Detailed Code Examples
+- [FunctionReturnTypeError.ets](../assets/FunctionReturnTypeError.ets) - 完整的函数返回类型示例，包含接口定义和使用
+
+---
+
+## Error: `Function return type inference is limited`
+
+### Error Message
+```
+Function return type inference is limited
+```
+
+### Cause
+ArkTS has limited type inference for function return types, especially for complex types or when the return type cannot be easily inferred from the function body. This is a strict type safety requirement to ensure code clarity and prevent type errors.
+
+### Solution
+Add explicit return type annotations to functions that return complex types or when the compiler cannot infer the return type.
+
+### Key Points
+- Add explicit return type annotations for complex return types
+- Use interface or type aliases for object return types
+- Annotate functions that return arrays, objects, or unions
+- Keep return type annotations simple and clear
+
+### Basic Pattern
+```typescript
+// ❌ Wrong: No explicit return type
+private getWindowInfo() {
+  return {
+    width: 1080,
+    height: 2340
+  };
+}
+
+// ✅ Correct: With explicit return type
+private getWindowInfo(): { width: number; height: number } {
+  return {
+    width: 1080,
+    height: 2340
+  };
+}
+```
+
+### Common Patterns
+```typescript
+// Object return types
+private getConfig(): Config {
+  return { width: 100, height: 100, color: 'red' };
+}
+
+// Array return types
+interface Item {
+  id: number;
+  name: string;
+}
+
+private getItems(): Item[] {
+  return [
+    { id: 1, name: 'Item 1' },
+    { id: 2, name: 'Item 2' }
+  ];
+}
+
+// Union return types
+private getValue(): string | number {
+  if (Math.random() > 0.5) {
+    return 'string';
+  }
+  return 42;
+}
+
+// Optional return types
+private findUser(id: number): User | undefined {
+  return this.users.find(user => user.id === id);
+}
+
+// Promise return types
+private async fetchData(): Promise<Data> {
+  const response = await fetch('https://api.example.com/data');
+  return await response.json();
+}
+```
+
+### Detailed Examples
+For more detailed code examples, see:
+- [Object Return Type](../assets/FunctionReturnTypeError.ets#L14-L19)
+- [Void Return Type](../assets/FunctionReturnTypeError.ets#L21-L26)
+- [Usage Pattern](../assets/FunctionReturnTypeError.ets#L28-L35)
+
+### Best Practices
+1. **Add explicit types**: Always add return type annotations for complex functions
+2. **Use interfaces**: Define interfaces for object return types
+3. **Keep types simple**: Avoid overly complex return type expressions
+4. **Be consistent**: Use the same style throughout your codebase
+5. **Document types**: Add comments explaining complex return types
+
+### Common Mistakes
+```typescript
+// ❌ Wrong: No explicit return type
+private getConfig() {
+  return { width: 100, height: 100 };
+}
+
+// ❌ Wrong: Using 'any' type
+private getConfig(): any {
+  return { width: 100, height: 100 };
+}
+
+// ✅ Correct: With explicit return type
+private getConfig(): { width: number; height: number } {
+  return { width: 100, height: 100 };
+}
+
+// ✅ Correct: Using interface
+interface Config {
+  width: number;
+  height: number;
+}
+
+private getConfig(): Config {
+  return { width: 100, height: 100 };
+}
+```
+
+### Related Files
+- [Code Example](../assets/FunctionReturnTypeError.ets)
+- [ArkTS Language Guide](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-get-started)

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

@@ -0,0 +1,77 @@
+# IDataSource 类型错误
+
+## 错误信息
+
+```
+Argument of type 'string[]' is not assignable to parameter of type 'IDataSource'.
+Type 'string[]' is missing the following properties from type 'IDataSource': 
+  totalCount, getData, registerDataChangeListener, unregisterDataChangeListener
+```
+
+## 错误原因
+
+在 ArkTS 中，`LazyForEach` 要求数据源必须实现 `IDataSource` 接口，直接使用 `string[]` 会导致类型错误。
+
+## 错误示例
+
+```typescript
+// 错误 - 直接使用 string[]
+private data: string[] = ['Item 1', 'Item 2', 'Item 3'];
+
+build() {
+  List() {
+    LazyForEach(this.data, (item: string) => {
+      ListItem() {
+        Text(item)
+      }
+    }, (item: string) => item)
+  }
+}
+```
+
+## 解决方案
+
+实现 `IDataSource` 接口：
+
+```typescript
+class MyDataSource {
+  data: string[] = [];
+  private listeners: DataChangeListener[] = [];
+
+  totalCount(): number {
+    return this.data.length;
+  }
+
+  getData(index: number): string {
+    return this.data[index];
+  }
+
+  registerDataChangeListener(listener: DataChangeListener): void {
+    this.listeners.push(listener);
+  }
+
+  unregisterDataChangeListener(listener: DataChangeListener): void {
+    const index = this.listeners.indexOf(listener);
+    if (index > -1) {
+      this.listeners.splice(index, 1);
+    }
+  }
+
+  pushData(data: string): void {
+    this.data.push(data);
+    this.listeners.forEach((listener: DataChangeListener) => {
+      listener.onDataAdd(this.data.length - 1);
+    });
+  }
+}
+```
+
+## 详细代码示例
+
+请参考 [IDataSourceError.ets](../assets/IDataSourceError.ets)
+
+## 相关 API
+
+- [LazyForEach](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/arkts-rendering-control-000000177275贼299)
+- [IDataSource](https://developer.harmonyos.com/cn/docs/documentation/doc-references/arkts-common-0000001774129201)
+- [DataChangeListener](https://developer.harmonyos.com/cn/docs/documentation/doc-references/arkts-common-0000001774129201)

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

@@ -0,0 +1,191 @@
+# 实现不允许错误
+
+## 错误描述
+
+在 ArkTS 中，UI 组件必须使用 `@Component` 装饰器装饰，并且必须在 `build()` 方法中返回 UI 结构。直接在文件中编写 UI 组件而不使用 `@Component` 装饰器会导致"实现不允许"错误。
+
+## 错误示例
+
+```typescript
+// 错误：直接在文件中编写 UI 组件
+Row() {
+  Text('Hello')
+}
+```
+
+**错误信息：**
+```
+Implementation not allowed
+```
+
+## 解决方案
+
+### 方案一：使用 @Component 装饰器
+
+将 UI 组件包装在 `@Component` 装饰器中，并添加 `build()` 方法。
+
+```typescript
+@Component
+struct MyComponent {
+  build() {
+    Row() {
+      Text('Hello')
+    }
+  }
+}
+```
+
+### 方案二：使用 @Entry 装饰器（如果是页面入口）
+
+如果是页面入口组件，使用 `@Entry` 装饰器。
+
+```typescript
+@Entry
+@Component
+struct MyPage {
+  build() {
+    Row() {
+      Text('Hello')
+    }
+  }
+}
+```
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct MyPage {
+  @State count: number = 0;
+
+  build() {
+    Column() {
+      Text(`计数: ${this.count}`)
+        .fontSize(20)
+        .margin({ bottom: 16 })
+      
+      Button('增加')
+        .onClick(() => {
+          this.count++;
+        })
+    }
+    .padding(16)
+  }
+}
+```
+
+## 详细代码示例
+
+- [ImplementationNotAllowedError.ets](../assets/ImplementationNotAllowedError.ets) - 完整的实现不允许错误修复示例，包含正确的组件结构
+
+## 最佳实践
+
+1. **使用 @Component 装饰器**：所有自定义组件都必须使用 `@Component` 装饰器
+2. **使用 @Entry 装饰器**：页面入口组件必须使用 `@Entry` 装饰器
+3. **实现 build() 方法**：所有组件都必须实现 `build()` 方法并返回 UI 结构
+4. **遵循组件结构**：UI 组件必须遵循 ArkTS 的组件结构规范
+
+## 常见错误
+
+```typescript
+// ❌ 错误：直接在文件中编写 UI 组件
+Row() {
+  Text('Hello')
+}
+
+// ❌ 错误：缺少 @Component 装饰器
+struct MyComponent {
+  build() {
+    Row() {
+      Text('Hello')
+    }
+  }
+}
+
+// ❌ 错误：缺少 build() 方法
+@Component
+struct MyComponent {
+  // 缺少 build() 方法
+}
+
+// ✅ 正确：使用 @Component 装饰器和 build() 方法
+@Component
+struct MyComponent {
+  build() {
+    Row() {
+      Text('Hello')
+    }
+  }
+}
+
+// ✅ 正确：页面入口使用 @Entry 装饰器
+@Entry
+@Component
+struct MyPage {
+  build() {
+    Row() {
+      Text('Hello')
+    }
+  }
+}
+```
+
+## 组件结构规范
+
+### 基本组件结构
+
+```typescript
+@Component
+struct MyComponent {
+  // 状态变量
+  @State count: number = 0;
+  
+  // 私有属性
+  private scroller: Scroller = new Scroller();
+  
+  // 生命周期方法
+  aboutToAppear() {
+    // 组件即将出现时调用
+  }
+  
+  aboutToDisappear() {
+    // 组件即将消失时调用
+  }
+  
+  // 自定义方法
+  private handleClick() {
+    this.count++;
+  }
+  
+  // UI 构建方法
+  build() {
+    Column() {
+      Text('Hello')
+    }
+  }
+}
+```
+
+### 页面入口组件结构
+
+```typescript
+@Entry
+@Component
+struct MyPage {
+  // 状态变量
+  @State title: string = 'My Page';
+  
+  // 生命周期方法
+  aboutToAppear() {
+    // 页面即将出现时调用
+  }
+  
+  // UI 构建方法
+  build() {
+    Column() {
+      Text(this.title)
+    }
+  }
+}
+```