deveco-harness 0.1.0

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

@@ -0,0 +1,156 @@
+# 对象可能为 null 错误
+
+## 错误描述
+
+在 ArkTS 中，编译器会严格检查可能为 null 的对象访问。如果对象可能为 null，但直接访问其属性，会导致"Object is possibly 'null'"错误。
+
+### 错误信息
+
+```
+Object is possibly 'null'
+```
+
+或
+
+```
+Variable 'xxx' is possibly null
+```
+
+## 错误示例
+
+```typescript
+// ❌ 错误：对象可能为 null
+let display = display.getDefaultDisplaySync();
+console.log(display.width); // 错误：Object is possibly 'null'
+
+// ❌ 错误：条件判断不完整
+if (display) {
+  console.log(display.width); // 某些情况下仍可能为 null
+}
+```
+
+## 解决方案
+
+### 方案一：使用 !== null 检查
+
+显式检查对象不等于 null：
+
+```typescript
+// ✅ 正确：使用 !== null 检查
+let display = display.getDefaultDisplaySync();
+if (display !== null) {
+  console.log(display.width);
+}
+```
+
+### 方案二：使用可选链和空值合并
+
+```typescript
+// ✅ 正确：使用可选链和空值合并
+let display = display.getDefaultDisplaySync();
+let width = display?.width ?? 0;
+```
+
+### 方案三：使用 let 声明可空类型
+
+```typescript
+// ✅ 正确：显式声明可空类型
+let display: Display | null = display.getDefaultDisplaySync();
+if (display !== null) {
+  console.log(display.width);
+}
+```
+
+### 方案四：非空断言（谨慎使用）
+
+```typescript
+// ✅ 正确（但需确保不会为 null）：使用非空断言
+let display = display.getDefaultDisplaySync()!;
+console.log(display.width);
+```
+
+## 简单示例
+
+```typescript
+import { display } from '@kit.ArkUI';
+
+@Entry
+@Component
+struct NullCheckExample {
+  private myDisplay: Display | null = null;
+
+  aboutToAppear() {
+    this.myDisplay = display.getDefaultDisplaySync();
+  }
+
+  build() {
+    Column() {
+      if (this.myDisplay !== null) {
+        Text(`Width: ${this.myDisplay.width}`)
+          .fontSize(24)
+      }
+    }
+    .width('100%')
+  }
+}
+```
+
+## 详细代码示例
+
+- [PossiblyNullError.ets](../assets/PossiblyNullError.ets) - 完整的 null 检查错误修复示例
+
+## 最佳实践
+
+1. **优先使用 !== null 检查**：最安全的方式，显式检查对象不为 null
+2. **使用可选链**：`?.` 可以在对象为 null 时返回 undefined
+3. **使用空值合并**：`??` 提供默认值
+4. **避免非空断言**：除非确定对象不会为 null，否则不要使用 `!`
+5. **类型注解**：对可能为 null 的变量显式声明联合类型
+
+## 常见场景
+
+### Display API
+
+```typescript
+// ❌ 错误
+let display = display.getDefaultDisplaySync();
+let width = display.width;
+
+// ✅ 正确
+let display = display.getDefaultDisplaySync();
+if (display !== null) {
+  let width = display.width;
+}
+```
+
+### Window API
+
+```typescript
+// ❌ 错误
+let window = window.getLastWindow(context);
+window.setFullScreen(true);
+
+// ✅ 正确
+let window = await window.getLastWindow(context);
+if (window !== null) {
+  await window.setFullScreen(true);
+}
+```
+
+### 可选属性
+
+```typescript
+// ❌ 错误
+let config = { width: 100 };
+let w = config.height; // height 不存在
+
+// ✅ 正确
+interface Config {
+  width: number;
+  height?: number;
+}
+let config: Config = { width: 100 };
+if (config.height !== undefined) {
+  let h = config.height;
+}
+```

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

@@ -0,0 +1,154 @@
+# Resource 类型转换错误
+
+## 错误描述
+
+在 ArkTS 中，不能将 `Resource` 类型直接转换为 `string` 或 `number` 类型。Resource 是一个特殊的资源引用类型，需要通过特定的方式使用。
+
+## 错误示例
+
+```typescript
+const message: string = $r('app.string.hello');
+const fontSize: number = $r('app.float.title_font_size');
+```
+
+**错误信息：**
+```
+Conversion of type 'Resource' to type 'string'/'number' may be a mistake because neither type sufficiently overlaps with the other.
+```
+
+## 解决方案
+
+### 方案1：直接在 UI 组件中使用（推荐）
+
+Resource 类型可以直接作为属性值传递给 UI 组件，系统会自动处理资源解析。
+
+```typescript
+@Entry
+@Component
+struct MyComponent {
+  build() {
+    Column() {
+      Text($r('app.string.hello'))
+        .fontSize($r('app.float.title_font_size'))
+        .width($r('app.float.layout_width'))
+        .height($r('app.float.layout_height'))
+        .backgroundColor($r('app.color.background_color'))
+    }
+  }
+}
+```
+
+### 方案2：使用资源管理器获取字符串值
+
+如果需要获取字符串的实际值，可以使用 `ResourceManager`。
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit';
+
+async function getStringResource(context: Context, resourceId: number): Promise<string> {
+  const manager = context.resourceManager;
+  return await manager.getString(resourceId);
+}
+```
+
+### 方案3：使用 getNumber 获取数值资源
+
+对于数值资源，使用 `getNumber` 方法。
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit';
+
+async function getNumberResource(context: Context, resourceId: number): Promise<number> {
+  const manager = context.resourceManager;
+  return await manager.getNumber(resourceId);
+}
+```
+
+### 方案4：使用 getStringByName 根据名称获取
+
+根据资源名称获取字符串值。
+
+```typescript
+import { resourceManager } from '@kit.LocalizationKit';
+
+async function getStringByName(context: Context, name: string): Promise<string> {
+  const manager = context.resourceManager;
+  return await manager.getStringByName(name);
+}
+```
+
+## 详细说明
+
+Resource 类型的特点：
+
+1. **延迟加载**：资源在需要时才被解析
+2. **多语言支持**：根据系统语言自动选择对应的资源
+3. **主题适配**：支持深色/浅色主题切换
+4. **类型安全**：编译时检查资源引用的正确性
+
+## 资源类型对照表
+
+| 资源类型 | $r 语法 | 资源文件位置 | 示例 |
+|---------|---------|-------------|------|
+| 字符串 | `$r('app.string.name')` | `resources/base/element/string.json` | `$r('app.string.hello')` |
+| 颜色 | `$r('app.color.name')` | `resources/base/element/color.json` | `$r('app.color.primary')` |
+| 浮点数 | `$r('app.float.name')` | `resources/base/element/float.json` | `$r('app.float.title_font_size')` |
+| 整数 | `$r('app.integer.name')` | `resources/base/element/integer.json` | `$r('app.integer.max_count')` |
+| 布尔 | `$r('app.boolean.name')` | `resources/base/element/boolean.json` | `$r('app.boolean.is_enabled')` |
+| 媒体 | `$r('app.media.name')` | `resources/base/media/` | `$r('app.media.icon')` |
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct ResourceUsageExample {
+  @State displayText: string = '';
+
+  async loadStringResource() {
+    try {
+      const context = this.getUIContext().getHostContext();
+      const manager = context.resourceManager;
+      this.displayText = await manager.getString($r('app.string.hello').id);
+    } catch (err) {
+      console.error(`Failed to load string resource: ${JSON.stringify(err)}`);
+    }
+  }
+
+  build() {
+    Column() {
+      Text('Resource 类型使用示例')
+        .fontSize($r('app.float.title_font_size'))
+        .fontWeight(FontWeight.Bold)
+        .margin(20)
+
+      Text($r('app.string.hello'))
+        .fontSize($r('app.float.content_font_size'))
+        .width($r('app.float.layout_width'))
+        .padding($r('app.float.padding'))
+        .backgroundColor($r('app.color.background_color'))
+        .borderRadius($r('app.float.border_radius'))
+        .margin(20)
+
+      Button('加载字符串资源')
+        .onClick(() => {
+          this.loadStringResource();
+        })
+        .margin(20)
+
+      if (this.displayText) {
+        Text(`加载的字符串: ${this.displayText}`)
+          .fontSize(14)
+          .margin(20)
+      }
+    }
+    .width('100%')
+    .height('100%')
+    .padding(20)
+  }
+}
+```
+
+## 详细代码示例
+
+> [ResourceConversionError.ets](../assets/ResourceConversionError.ets) - 完整的 Resource 类型转换错误示例和修复方案

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

@@ -0,0 +1,68 @@
+# Standalone Function `this` Usage Error
+
+## 错误描述
+
+在独立函数（非类方法）中不能直接使用 `this`，因为 `this` 在独立函数中没有上下文绑定。
+
+## 错误示例
+
+```typescript
+async function getAvoidArea() {
+  const win = await window.getLastWindow(this.getUIContext().getHostContext());
+  return win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
+}
+```
+
+**错误信息：**
+```
+Cannot find name 'this'
+```
+
+## 解决方案
+
+将上下文作为参数传递给独立函数。
+
+```typescript
+async function getAvoidArea(context: common.UIAbilityContext): Promise<window.AvoidArea> {
+  return new Promise((resolve, reject) => {
+    window.getLastWindow(context, (err, win) => {
+      if (err.code !== 0) {
+        reject(err);
+        return;
+      }
+      const avoidArea = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
+      resolve(avoidArea);
+    });
+  });
+}
+```
+
+## 简单示例
+
+```typescript
+@Entry
+@Component
+struct Example {
+  @State avoidAreaHeight: number = 0;
+
+  async aboutToAppear() {
+    const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
+    try {
+      const avoidArea = await getAvoidArea(context);
+      this.avoidAreaHeight = avoidArea.topRect.height;
+    } catch (err) {
+      console.error('获取避让区域失败:', err);
+    }
+  }
+
+  build() {
+    Column() {
+      Text(`避让区域高度: ${this.avoidAreaHeight}`)
+    }
+  }
+}
+```
+
+## 详细代码示例
+
+- [StandaloneFunctionError.ets](../assets/StandaloneFunctionError.ets) - 完整的独立函数上下文传递示例，包含多个独立函数的使用

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

@@ -0,0 +1,124 @@
+# @StorageLink Default Value Errors
+
+## Error: `The '@StorageLink' property must be specified a default value`
+
+### Error Message
+```
+The '@StorageLink' property must be specified a default value
+```
+
+### Cause
+ArkTS requires all `@StorageLink` decorated properties to have a default value. This is a strict type safety requirement to ensure the property always has a valid initial state.
+
+### Solution
+Add a default value to the `@StorageLink` property, typically `= undefined` for optional types or a specific default value for required types.
+
+### Key Points
+- Always provide a default value for `@StorageLink` properties
+- Use `= undefined` for optional types
+- Use specific default values for required types (e.g., `= 0`, `= ''`, `= false`)
+- Initialize the actual value in `aboutToAppear()` using `AppStorage.setOrCreate()`
+
+### Basic Pattern
+```typescript
+@Entry
+@Component
+struct MyComponent {
+  @StorageLink('myKey') myValue: number = 0;
+
+  aboutToAppear() {
+    AppStorage.setOrCreate('myKey', 0);
+  }
+
+  build() {
+    Text(`Value: ${this.myValue}`)
+  }
+}
+```
+
+### Optional Type Pattern
+```typescript
+interface WindowUtil {
+  width: number;
+  height: number;
+  density: number;
+  updateWindowInfo: () => void;
+  destroy: () => void;
+}
+
+@Entry
+@Component
+struct MyComponent {
+  @StorageLink('windowUtil') windowUtil?: WindowUtil = undefined;
+
+  aboutToAppear() {
+    AppStorage.setOrCreate('windowUtil', {
+      width: 0,
+      height: 0,
+      density: 1.0,
+      updateWindowInfo: () => {},
+      destroy: () => {}
+    });
+  }
+
+  build() {
+    Text(`Width: ${this.windowUtil?.width || 0}`)
+  }
+}
+```
+
+### Common Default Values
+```typescript
+// Number types
+@StorageLink('counter') count: number = 0;
+@StorageLink('width') width: number = 100;
+@StorageLink('opacity') opacity: number = 1.0;
+
+// String types
+@StorageLink('userName') userName: string = '';
+@StorageLink('title') title: string = 'Default Title';
+
+// Boolean types
+@StorageLink('isDarkMode') isDarkMode: boolean = false;
+@StorageLink('isLoading') isLoading: boolean = true;
+
+// Array types
+@StorageLink('items') items: Array<string> = [];
+@StorageLink('numbers') numbers: number[] = [1, 2, 3];
+
+// Optional types
+@StorageLink('user') user?: User = undefined;
+@StorageLink('settings') settings?: Settings = undefined;
+```
+
+### Detailed Examples
+For more detailed code examples, see:
+- [Optional Type Pattern](../assets/StorageLinkDefaultError.ets#L8-L31)
+- [Initialization Pattern](../assets/StorageLinkDefaultError.ets#L11-L23)
+- [Usage Pattern](../assets/StorageLinkDefaultError.ets#L25-L39)
+
+### Best Practices
+1. **Always provide default value**: Never leave `@StorageLink` without a default
+2. **Use appropriate defaults**: Choose defaults that make sense for your use case
+3. **Initialize in aboutToAppear**: Set the actual value when component appears
+4. **Use optional types carefully**: Only use `?` when the value can legitimately be undefined
+5. **Document default values**: Add comments explaining why a specific default was chosen
+
+### Common Mistakes
+```typescript
+// ❌ Wrong: No default value
+@StorageLink('myValue') myValue: number;
+
+// ❌ Wrong: Using null instead of undefined
+@StorageLink('myValue') myValue: number = null;
+
+// ✅ Correct: With default value
+@StorageLink('myValue') myValue: number = 0;
+
+// ✅ Correct: Optional type with undefined
+@StorageLink('myValue') myValue?: number = undefined;
+```
+
+### Related Files
+- [Code Example](../assets/StorageLinkDefaultError.ets)
+- [AppStorage Type Errors](./appstorage_errors.md)

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

@@ -0,0 +1,167 @@
+# TitleButtonRect Type Error
+
+## 错误描述
+
+`window.getTitleButtonRect()` 方法返回的是 `window.TitleButtonRect` 类型，而不是 `window.Rect` 类型。如果函数返回类型声明为 `window.Rect`，会导致类型不匹配错误。
+
+## 错误信息
+
+### 错误 1: 类型不匹配
+```
+Argument of type 'TitleButtonRect' is not assignable to parameter of type 'Rect | PromiseLike<Rect>'.
+  Property 'left' is missing in type 'TitleButtonRect' but required in type 'Rect'.
+```
+
+### 错误 2: 访问不存在的属性
+```
+Property 'left' does not exist on type 'TitleButtonRect'.
+Property 'top' does not exist on type 'TitleButtonRect'.
+```
+
+**原因**：`TitleButtonRect` 类型只包含 `width` 和 `height` 属性，不包含 `left` 和 `top` 属性。
+
+## 错误示例
+
+```typescript
+async function getTitleButtonRect(context: common.UIAbilityContext): Promise<window.Rect> {
+  return new Promise((resolve, reject) => {
+    window.getLastWindow(context, (err, win) => {
+      if (err.code !== 0) {
+        reject(new Error(err.message));
+        return;
+      }
+      const titleButtonRect = win.getTitleButtonRect();
+      resolve(titleButtonRect);
+    });
+  });
+}
+```
+
+## 解决方案
+
+将函数返回类型从 `window.Rect` 改为 `window.TitleButtonRect`。
+
+```typescript
+async function getTitleButtonRect(context: common.UIAbilityContext): Promise<window.TitleButtonRect> {
+  return new Promise((resolve, reject) => {
+    window.getLastWindow(context, (err, win) => {
+      if (err.code !== 0) {
+        reject(new Error(err.message));
+        return;
+      }
+      const titleButtonRect = win.getTitleButtonRect();
+      resolve(titleButtonRect);
+    });
+  });
+}
+```
+
+## 类型说明
+
+`window.TitleButtonRect` 和 `window.Rect` 是两个不同的类型：
+
+- `window.Rect`: 包含 `left`, `top`, `width`, `height` 属性
+- `window.TitleButtonRect`: **只包含** `width`, `height` 属性（不包含 `left` 和 `top` 属性）
+
+**重要提示**：`TitleButtonRect` 类型只提供宽度和高度信息，不包含位置信息（left 和 top）。如果需要位置信息，需要使用其他 API 获取。
+
+## 简单示例
+
+```typescript
+import { window } from '@kit.ArkUI';
+import { common } from '@kit.AbilityKit';
+
+async function getTitleButtonRect(context: common.UIAbilityContext): Promise<window.TitleButtonRect> {
+  return new Promise((resolve, reject) => {
+    window.getLastWindow(context, (err, win) => {
+      if (err.code !== 0) {
+        reject(new Error(err.message));
+        return;
+      }
+      const titleButtonRect = win.getTitleButtonRect();
+      resolve(titleButtonRect);
+    });
+  });
+}
+
+@Entry
+@Component
+struct TitleButtonRectExample {
+  @State titleBarHeight: number = 0;
+  @State titleBarWidth: number = 0;
+
+  async aboutToAppear() {
+    const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
+    try {
+      const titleButtonRect = await getTitleButtonRect(context);
+      // TitleButtonRect 只包含 width 和 height 属性
+      this.titleBarHeight = titleButtonRect.height;
+      this.titleBarWidth = titleButtonRect.width;
+      // ❌ 错误：不能访问 left 和 top 属性
+      // this.titleBarLeft = titleButtonRect.left;  // Property 'left' does not exist
+      // this.titleBarTop = titleButtonRect.top;     // Property 'top' does not exist
+    } catch (err) {
+      console.error('获取标题栏按钮区域失败:', err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  build() {
+    Column() {
+      Text(`标题栏高度: ${this.titleBarHeight}`)
+      Text(`标题栏宽度: ${this.titleBarWidth}`)
+    }
+  }
+}
+```
+
+## 详细代码示例
+
+- [TitleButtonRectTypeError.ets](../assets/TitleButtonRectTypeError.ets) - TitleButtonRect 类型错误的完整示例，包含错误和正确的解决方案
+- [StandaloneFunctionContext.ets](../assets/StandaloneFunctionContext.ets#L34-L47) - 完整的 TitleButtonRect 类型使用示例，包含错误处理
+- [StandaloneFunctionError.ets](../assets/StandaloneFunctionError.ets#L34-L47) - 独立函数中的 TitleButtonRect 类型使用示例
+
+## 相关类型
+
+| 类型 | 说明 | 用途 |
+|------|------|------|
+| `window.Rect` | 通用矩形区域 | 窗口区域、避让区域等 |
+| `window.TitleButtonRect` | 标题栏按钮区域 | 标题栏按钮的位置和大小 |
+| `window.AvoidArea` | 避让区域 | 系统栏、导航栏等避让区域 |
+
+## 最佳实践
+
+1. **使用正确的返回类型**: 根据实际调用的 API 返回类型来声明函数返回类型
+2. **查看 API 文档**: 使用窗口 API 时，仔细查看返回值类型和可用属性
+3. **了解类型差异**: `TitleButtonRect` 只包含 `width` 和 `height`，不包含位置信息
+4. **类型转换**: 如果需要在不同类型之间转换，创建新的对象而不是直接赋值
+5. **避免访问不存在的属性**: 不要尝试访问 `TitleButtonRect` 的 `left` 和 `top` 属性
+6. **使用 TypeScript 类型推断**: 在某些情况下，可以省略返回类型注解让编译器推断
+
+## 常见错误
+
+```typescript
+// ❌ 错误：返回类型声明为 Rect
+async function getTitleButtonRect(): Promise<window.Rect> {
+  const win = await window.getLastWindow(context);
+  return win.getTitleButtonRect();
+}
+
+// ✅ 正确：返回类型声明为 TitleButtonRect
+async function getTitleButtonRect(): Promise<window.TitleButtonRect> {
+  const win = await window.getLastWindow(context);
+  return win.getTitleButtonRect();
+}
+
+// ✅ 正确：如果需要 Rect 类型，进行类型转换
+// 注意：TitleButtonRect 不包含 left 和 top 属性，只能提供 width 和 height
+async function getTitleButtonRectAsRect(): Promise<window.Rect> {
+  const win = await window.getLastWindow(context);
+  const titleButtonRect = win.getTitleButtonRect();
+  return {
+    left: 0,  // TitleButtonRect 不提供位置信息，需要从其他 API 获取
+    top: 0,   // TitleButtonRect 不提供位置信息，需要从其他 API 获取
+    width: titleButtonRect.width,
+    height: titleButtonRect.height
+  };
+}
+```