新增HarmonyOS开发规则文档，包括动画与转场、组件封装与复用、声明式语法、手势与导航、布局与弹窗、主题与样式等，旨在提升开发效率和用户体验。

.cursor/rules/animation_transition.cursorrules.md

@@ -0,0 +1,131 @@
+# HarmonyOS 动画与转场 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+-   **用户体验至上**: 动画旨在提升交互流畅感，引导用户，而非纯粹的视觉炫技。
+-   **性能优先**: 确保动画运行流畅，不造成卡顿或资源浪费。
+-   **系统能力优先**: 优先使用HarmonyOS提供的原生动画API和高级模板。
+-   **设计意图匹配**: 深入理解UX设计，选择最符合场景的动效类型和实现方式。
+
+## 推荐做法
+
+### 代码结构
+-   **声明式动画与状态驱动**: 优先使用HarmonyOS的声明式UI和 `@State` 驱动动画，通过改变状态变量触发动画。
+-   **组件化封装**: 将复杂的动画逻辑封装到自定义组件中，提高复用性和可维护性。
+
+### 最佳实践
+-   **动效选择与场景匹配**:
+    *   **页面路由转场**: 大部分页面切换推荐使用**左右位移遮罩动效**。
+    *   **共享元素转场**: 图片展开、图标（搜索框、头像）展开，推荐使用**一镜到底动效**或`geometryTransition`接口。将关键元素作为持续存在的共享元素。
+    *   **共享容器转场**: 卡片/视频展开、列表项展开，推荐使用`Navigation`自定义动画或`geometryTransition`结合显示动画。
+    *   **通用动画**: 元素显隐、状态变化等，使用属性动画（`animateTo`）或显式动画。
+-   **动画运行流畅度优化**:
+    *   **优先使用系统动画API**: 系统提供的API经过底层优化，性能更佳。
+    *   **动画属性选择**: 优先改变不影响布局的图形变换属性，如 `transform` (位移、旋转、缩放) 和 `opacity` (不透明度)。这些属性通常在GPU上合成，性能最高。
+    *   **`animateTo` 复用**: 多个动画参数相同时，尽量在同一个 `animateTo` 块中更新状态，减少开销。
+    *   **`renderGroup` 应用**: 对于包含复杂子组件的动画，将其设置为 `renderGroup(true)`，减少渲染批次。
+-   **用户手势反馈**: 对于点击、滑动等手势，提供即时且连贯的动画反馈。
+
+## 禁止做法
+
+-   **频繁修改布局属性**: 严禁在动画过程中频繁改变组件的 `width`、`height`、`padding`、`margin` 等布局属性，这会导致UI树重绘，严重影响性能。
+-   **滥用动画**: 避免不必要的、过于复杂的动画，以免分散用户注意力或增加视觉负担。
+-   **缺乏用户反馈**: 禁止用户操作后界面无任何视觉反馈，特别是在点击、加载等关键交互点。
+
+## 代码示例
+
+### 推荐写法
+```arkts
+// 推荐：通过状态变化驱动动画，并优先改变图形变换属性
+@Entry
+@Component
+struct GoodAnimationExample {
+  @State isScaled: boolean = false;
+
+  build() {
+    Column() {
+      Button('缩放')
+        .width(100).height(100)
+        .backgroundColor(Color.Blue)
+        .scale(this.isScaled ? 1.5 : 1.0) // 改变scale属性
+        .opacity(this.isScaled ? 0.5 : 1.0) // 改变opacity属性
+        .onClick(() => {
+          // 使用animateTo进行动画过渡
+          animateTo({ duration: 300, curve: Curve.EaseOut }, () => {
+            this.isScaled = !this.isScaled;
+          });
+        })
+    }
+    .width('100%').height('100%')
+    .justifyContent(FlexAlign.Center)
+  }
+}
+
+// 推荐：使用共享元素转场
+// PageA.ets
+@Entry
+@Component
+struct PageA {
+  build() {
+    Column() {
+      Image('placeholder.png')
+        .width(100).height(100)
+        .sharedTransition('heroImage') // 定义共享元素ID
+        .onClick(() => {
+          Router.pushUrl({ url: 'pages/PageB' });
+        })
+    }
+  }
+}
+
+// PageB.ets
+@Entry
+@Component
+struct PageB {
+  build() {
+    Column() {
+      Image('placeholder.png')
+        .width(300).height(300)
+        .sharedTransition('heroImage') // 相同ID，自动匹配
+    }
+  }
+}
+```
+
+### 避免写法
+```arkts
+// 避免：在动画中直接修改布局属性
+@Entry
+@Component
+struct BadAnimationExample {
+  @State currentWidth: number = 100;
+  @State currentHeight: number = 100;
+
+  build() {
+    Column() {
+      Button('改变大小')
+        .width(this.currentWidth) // 避免在动画中直接改变width/height
+        .height(this.currentHeight) // 避免在动画中直接改变width/height
+        .backgroundColor(Color.Red)
+        .onClick(() => {
+          // 这种方式会导致UI树的重新布局和重绘，性能较差
+          animateTo({ duration: 300 }, () => {
+            this.currentWidth = 200;
+            this.currentHeight = 200;
+          });
+        })
+    }
+    .width('100%').height('100%')
+    .justifyContent(FlexAlign.Center)
+  }
+}
+```
+
+## 注意事项
+
+-   **转场曲线**: 页面转场曲线优先使用**弹簧曲线 (Curve.Spring)**，以提供更自然的动效。
+-   **内存管理**: 注意及时释放不再需要的动画资源，防止内存泄漏。
+-   **跨应用转场**: 对于跨应用转场，应遵循系统规范，确保体验一致性。
+-   **调试**: 利用DevEco Studio的性能分析工具（如CPU Profiler, UI Latency）对动画进行性能监控和调试。

.cursor/rules/arkts-lint-rules.md

@@ -0,0 +1,439 @@
+# ArkTS Lint Rules - Cursor Rules
+
+## 概述
+ArkTS（TypeScript的子集）的Lint规则，用于确保代码符合HarmonyOS开发规范。
+
+## 规则统计
+- 总规则数量: 67
+- 严重程度: error
+- 适用范围: ArkTS/TypeScript代码
+
+## 规则列表
+
+### JSON格式
+```json
+[
+  {
+    "name": "arkts-no-aliases-by-index",
+    "severity": "error",
+    "description": "ArkTS不支持索引访问类型。",
+    "suggestion": "请改用类型名称。"
+  },
+  {
+    "name": "arkts-no-ambient-decls",
+    "severity": "error",
+    "description": "ArkTS不支持环境模块声明，因为它有自己的与JavaScript互操作的机制。",
+    "suggestion": "请从原始模块中导入所需的内容。"
+  },
+  {
+    "name": "arkts-no-any-unknown",
+    "severity": "error",
+    "description": "ArkTS不支持any和unknown类型。",
+    "suggestion": "请显式指定类型。"
+  },
+  {
+    "name": "arkts-no-as-const",
+    "severity": "error",
+    "description": "ArkTS不支持as const断言，因为在标准TypeScript中，as const用于使用相应的字面量类型标注字面量，而ArkTS不支持字面量类型。",
+    "suggestion": "请避免使用as const断言。请改用字面量的显式类型标注。"
+  },
+  {
+    "name": "arkts-no-call-signatures",
+    "severity": "error",
+    "description": "ArkTS不支持对象类型中的调用签名。",
+    "suggestion": "请改用class（类）来实现。"
+  },
+  {
+    "name": "arkts-no-class-literals",
+    "severity": "error",
+    "description": "ArkTS不支持类字面量。",
+    "suggestion": "请显式引入新的命名类类型。"
+  },
+  {
+    "name": "arkts-no-classes-as-obj",
+    "severity": "error",
+    "description": "ArkTS不支持将类用作对象（将其赋值给变量等）。这是因为在ArkTS中，类声明引入的是一种新类型，而不是一个值。",
+    "suggestion": "请勿将类用作对象；类声明引入的是一种新类型，而不是一个值。"
+  },
+  {
+    "name": "arkts-no-comma-outside-loops",
+    "severity": "error",
+    "description": "ArkTS仅在for循环中支持逗号运算符。在其他情况下，逗号运算符是无用的，因为它会使执行顺序更难理解。",
+    "suggestion": "在for循环之外，请使用显式执行顺序而不是逗号运算符。"
+  },
+  {
+    "name": "arkts-no-conditional-types",
+    "severity": "error",
+    "description": "ArkTS不支持条件类型别名。",
+    "suggestion": "请显式引入带约束的新类型，或使用Object重写逻辑。不支持infer关键字。"
+  },
+  {
+    "name": "arkts-no-ctor-prop-decls",
+    "severity": "error",
+    "description": "ArkTS不支持在构造函数中声明类字段。",
+    "suggestion": "请在类声明内部声明类字段。"
+  },
+  {
+    "name": "arkts-no-ctor-signatures-funcs",
+    "severity": "error",
+    "description": "ArkTS不支持使用构造函数类型。",
+    "suggestion": "请改用lambdas（匿名函数）。"
+  },
+  {
+    "name": "arkts-no-ctor-signatures-iface",
+    "severity": "error",
+    "description": "ArkTS不支持接口中的构造函数签名。",
+    "suggestion": "请改用方法（methods）。"
+  },
+  {
+    "name": "arkts-no-ctor-signatures-type",
+    "severity": "error",
+    "description": "ArkTS不支持对象类型中的构造函数签名。",
+    "suggestion": "请改用class（类）来实现。"
+  },
+  {
+    "name": "arkts-no-decl-merging",
+    "severity": "error",
+    "description": "ArkTS不支持声明合并。",
+    "suggestion": "请保持代码库中所有类和接口的定义紧凑。"
+  },
+  {
+    "name": "arkts-no-definite-assignment",
+    "severity": "error",
+    "description": "ArkTS不支持确定性赋值断言let v!: T，因为它们被认为是过度的编译器提示。使用确定性赋值断言运算符（!）需要运行时类型检查，导致额外的运行时开销并生成此警告。",
+    "suggestion": "请改用带初始化的声明。如果使用了!，请确保实例属性在使用前已赋值，并注意运行时开销和警告。"
+  },
+  {
+    "name": "arkts-no-delete",
+    "severity": "error",
+    "description": "ArkTS假定对象布局在编译时已知且运行时不可更改。因此，删除属性的操作没有意义。",
+    "suggestion": "为了模拟原始语义，您可以声明一个可空类型并赋值为null以标记值的缺失。"
+  },
+  {
+    "name": "arkts-no-destruct-assignment",
+    "severity": "error",
+    "description": "ArkTS不支持解构赋值。",
+    "suggestion": "请改用其他惯用法（例如，在适用情况下使用临时变量）代替。"
+  },
+  {
+    "name": "arkts-no-destruct-decls",
+    "severity": "error",
+    "description": "ArkTS不支持解构变量声明。这是一个依赖于结构兼容性的动态特性。",
+    "suggestion": "创建中间对象并逐字段操作，不受名称限制。"
+  },
+  {
+    "name": "arkts-no-destruct-params",
+    "severity": "error",
+    "description": "ArkTS要求参数直接传递给函数，并手动分配局部名称。",
+    "suggestion": "请将参数直接传递给函数，并手动分配局部名称，而不是使用解构参数声明。"
+  },
+  {
+    "name": "arkts-no-enum-merging",
+    "severity": "error",
+    "description": "ArkTS不支持枚举的声明合并。",
+    "suggestion": "请保持代码库中每个枚举的声明紧凑。"
+  },
+  {
+    "name": "arkts-no-enum-mixed-types",
+    "severity": "error",
+    "description": "ArkTS不支持使用在程序运行时评估的表达式初始化枚举成员。此外，所有显式设置的初始化器必须是相同类型。",
+    "suggestion": "请仅使用相同类型的编译时表达式初始化枚举成员。"
+  },
+  {
+    "name": "arkts-no-export-assignment",
+    "severity": "error",
+    "description": "ArkTS不支持export = ...语法。",
+    "suggestion": "请改用普通的export和import语法。"
+  },
+  {
+    "name": "arkts-no-extend-same-prop",
+    "severity": "error",
+    "description": "ArkTS不允许接口包含两个具有不可区分签名的方法（例如，参数列表相同但返回类型不同）。",
+    "suggestion": "请避免接口扩展具有相同方法签名的其他接口。重构方法名称或返回类型。"
+  },
+  {
+    "name": "arkts-no-for-in",
+    "severity": "error",
+    "description": "ArkTS不支持通过for .. in循环遍历对象内容。对于对象，运行时遍历属性被认为是冗余的，因为对象布局在编译时已知且运行时不可更改。",
+    "suggestion": "对于数组，请使用常规的for循环进行迭代。"
+  },
+  {
+    "name": "arkts-no-func-apply-call",
+    "severity": "error",
+    "description": "ArkTS不支持Function.apply或Function.call。这些API在标准库中用于显式设置被调用函数的this参数。在ArkTS中，this的语义被限制为传统的OOP风格，并且禁止在独立函数中使用this。",
+    "suggestion": "请避免使用Function.apply和Function.call。请遵循传统的OOP风格来处理this的语义。"
+  },
+  {
+    "name": "arkts-no-func-bind",
+    "severity": "error",
+    "description": "ArkTS不支持Function.bind。这些API在标准库中用于显式设置被调用函数的this参数。在ArkTS中，this的语义被限制为传统的OOP风格，并且禁止在独立函数中使用this。",
+    "suggestion": "请避免使用Function.bind。请遵循传统的OOP风格来处理this的语义。"
+  },
+  {
+    "name": "arkts-no-func-expressions",
+    "severity": "error",
+    "description": "ArkTS不支持函数表达式。",
+    "suggestion": "请改用箭头函数来显式指定。"
+  },
+  {
+    "name": "arkts-no-func-props",
+    "severity": "error",
+    "description": "ArkTS不支持在函数上声明属性，因为不支持具有动态更改布局的对象。函数对象遵循此规则，其布局在运行时不可更改。",
+    "suggestion": "请勿直接在函数上声明属性，因为它们的布局在运行时不可更改。"
+  },
+  {
+    "name": "arkts-no-generators",
+    "severity": "error",
+    "description": "ArkTS当前不支持生成器函数。",
+    "suggestion": "请使用async/await机制进行多任务处理。"
+  },
+  {
+    "name": "arkts-no-globalthis",
+    "severity": "error",
+    "description": "ArkTS不支持全局作用域和globalThis，因为不支持具有动态更改布局的无类型对象。",
+    "suggestion": "请使用显式模块导出和导入来在文件之间共享数据，而不是依赖全局作用域。"
+  },
+  {
+    "name": "arkts-no-implicit-return-types",
+    "severity": "error",
+    "description": "ArkTS支持函数返回类型推断，但此功能目前受到限制。特别是，当return语句中的表达式是对返回类型被省略的函数或方法的调用时，会发生编译时错误。",
+    "suggestion": "当返回类型被省略时，请显式指定函数的返回类型。"
+  },
+  {
+    "name": "arkts-no-import-assertions",
+    "severity": "error",
+    "description": "ArkTS不支持导入断言，因为导入在ArkTS中是编译时特性，而不是运行时特性。因此，对于静态类型语言来说，在运行时断言导入API的正确性没有意义。",
+    "suggestion": "请改用普通的import语法；导入的正确性将在编译时检查。"
+  },
+  {
+    "name": "arkts-no-in",
+    "severity": "error",
+    "description": "ArkTS不支持in运算符。此运算符意义不大，因为对象布局在编译时已知且运行时不可更改。",
+    "suggestion": "如果您想检查是否存在某些类成员，请使用instanceof作为替代方案。"
+  },
+  {
+    "name": "arkts-no-indexed-signatures",
+    "severity": "error",
+    "description": "ArkTS不允许索引签名。",
+    "suggestion": "请改用数组（arrays）。"
+  },
+  {
+    "name": "arkts-no-inferred-generic-params",
+    "severity": "error",
+    "description": "ArkTS允许在函数调用时省略泛型类型参数（如果可以从传递给函数的参数中推断出具体类型），否则会发生编译时错误。特别地，仅基于函数返回类型推断泛型类型参数是被禁止的。",
+    "suggestion": "当推断受限时（特别是仅基于函数返回类型时），请显式指定返回类型。"
+  },
+  {
+    "name": "arkts-no-intersection-types",
+    "severity": "error",
+    "description": "ArkTS当前不支持交叉类型。",
+    "suggestion": "请使用继承（inheritance）作为替代方案。"
+  },
+  {
+    "name": "arkts-no-is",
+    "severity": "error",
+    "description": "ArkTS不支持is运算符，必须将其替换为instanceof运算符。请注意，在使用对象字段之前，必须使用as运算符将其转换为适当的类型。",
+    "suggestion": "请将is运算符替换为instanceof。在使用对象字段之前，请使用as运算符将其转换为适当的类型。"
+  },
+  {
+    "name": "arkts-no-jsx",
+    "severity": "error",
+    "description": "ArkTS不支持JSX表达式。",
+    "suggestion": "请勿使用JSX，因为没有提供替代方案来重写它。"
+  },
+  {
+    "name": "arkts-no-mapped-types",
+    "severity": "error",
+    "description": "ArkTS不支持映射类型。",
+    "suggestion": "请使用其他语言惯用法和常规类来实现相同的行为。"
+  },
+  {
+    "name": "arkts-no-method-reassignment",
+    "severity": "error",
+    "description": "ArkTS不支持重新分配对象方法。在静态类型语言中，对象的布局是固定的，同一对象的所有实例必须共享每个方法的相同代码。",
+    "suggestion": "如果需要为特定对象添加特定行为，可以创建单独的包装函数或使用继承。"
+  },
+  {
+    "name": "arkts-no-misplaced-imports",
+    "severity": "error",
+    "description": "在ArkTS中，所有import语句都应该在程序中的所有其他语句之前。",
+    "suggestion": "请将所有import语句放在程序的开头，在任何其他语句之前。"
+  },
+  {
+    "name": "arkts-no-module-wildcards",
+    "severity": "error",
+    "description": "ArkTS不支持模块名称中的通配符，因为import在ArkTS中是编译时特性，而不是运行时特性。",
+    "suggestion": "请改用普通的export语法。"
+  },
+  {
+    "name": "arkts-no-multiple-static-blocks",
+    "severity": "error",
+    "description": "ArkTS不允许类初始化存在多个静态代码块。",
+    "suggestion": "将所有静态代码块语句合并到一个静态代码块中。"
+  },
+  {
+    "name": "arkts-no-nested-funcs",
+    "severity": "error",
+    "description": "ArkTS不支持嵌套函数。",
+    "suggestion": "请改用lambdas（匿名函数）。"
+  },
+  {
+    "name": "arkts-no-new-target",
+    "severity": "error",
+    "description": "ArkTS不支持new.target，因为语言中没有运行时原型继承的概念。此功能被认为不适用于静态类型。",
+    "suggestion": "此功能不适用于静态类型和运行时原型继承，因此不受支持。没有提供直接的替代方案，因为它是一个根本性的差异。"
+  },
+  {
+    "name": "arkts-no-noninferrable-arr-literals",
+    "severity": "error",
+    "description": "如果数组字面量中至少有一个元素具有不可推断的类型（例如，无类型对象字面量），则会发生编译时错误。",
+    "suggestion": "请确保数组字面量中的所有元素都具有可推断的类型，或将元素显式转换为已定义的类型。"
+  },
+  {
+    "name": "arkts-no-ns-as-obj",
+    "severity": "error",
+    "description": "ArkTS不支持将命名空间用作对象。",
+    "suggestion": "请将类或模块解释为命名空间的类似物。"
+  },
+  {
+    "name": "arkts-no-ns-statements",
+    "severity": "error",
+    "description": "ArkTS不支持命名空间中的语句。",
+    "suggestion": "请使用函数来执行语句。"
+  },
+  {
+    "name": "arkts-no-obj-literals-as-types",
+    "severity": "error",
+    "description": "ArkTS不支持将对象字面量直接用作类型声明。",
+    "suggestion": "请显式声明类和接口。"
+  },
+  {
+    "name": "arkts-no-polymorphic-unops",
+    "severity": "error",
+    "description": "ArkTS只允许一元运算符+、-和~作用于数字类型。如果这些运算符应用于非数字类型，则会发生编译时错误。与TypeScript不同，此上下文中不支持字符串的隐式类型转换，必须显式进行类型转换。",
+    "suggestion": "请确保一元运算符+、-和~仅应用于数字类型。如有必要，请执行显式类型转换。"
+  },
+  {
+    "name": "arkts-no-private-identifiers",
+    "severity": "error",
+    "description": "ArkTS不支持以#符号开头的私有标识符。",
+    "suggestion": "请改用private关键字。"
+  },
+  {
+    "name": "arkts-no-props-by-index",
+    "severity": "error",
+    "description": "ArkTS不支持动态字段声明和访问，也不支持通过索引访问对象字段（obj[\"field\"]）。",
+    "suggestion": "请在类中立即声明所有对象字段，并使用obj.field语法访问字段。标准库中的所有类型化数组（如Int32Array）是例外，它们支持通过container[index]语法访问元素。"
+  },
+  {
+    "name": "arkts-no-prototype-assignment",
+    "severity": "error",
+    "description": "ArkTS不支持原型赋值，因为语言中没有运行时原型继承的概念。此功能被认为不适用于静态类型。",
+    "suggestion": "请改用类和/或接口来静态地将方法与数据“组合”在一起。"
+  },
+  {
+    "name": "arkts-no-require",
+    "severity": "error",
+    "description": "ArkTS不支持通过require导入。它也不支持import赋值。",
+    "suggestion": "请改用常规的import语法。"
+  },
+  {
+    "name": "arkts-no-spread",
+    "severity": "error",
+    "description": "展开运算符唯一支持的场景是将数组或派生自数组的类展开到rest参数或数组字面量中。否则，必要时手动从数组和对象中“解包”数据。",
+    "suggestion": "展开运算符仅用于将数组或派生自数组的类展开到rest参数或数组字面量中。对于其他情况，请手动从数组和对象中解包数据。"
+  },
+  {
+    "name": "arkts-no-standalone-this",
+    "severity": "error",
+    "description": "ArkTS不支持在独立函数和静态方法中使用this。",
+    "suggestion": "this只能在实例方法中使用。"
+  },
+  {
+    "name": "arkts-no-structural-typing",
+    "severity": "error",
+    "description": "ArkTS当前不支持结构化类型。这意味着编译器无法比较两种类型的公共API并判断它们是否相同。",
+    "suggestion": "请改用其他机制（继承、接口或类型别名）。"
+  },
+  {
+    "name": "arkts-no-symbol",
+    "severity": "error",
+    "description": "ArkTS不支持Symbol() API，因为其最常见的用例在静态类型环境中没有意义，对象的布局在编译时定义且运行时不可更改。",
+    "suggestion": "除Symbol.iterator外，避免使用Symbol() API。"
+  },
+  {
+    "name": "arkts-no-ts-deps",
+    "severity": "error",
+    "description": "目前，用标准TypeScript语言实现的 codebase 不得通过导入 ArkTS codebase 来依赖 ArkTS。",
+    "suggestion": "请避免TypeScript代码库依赖ArkTS代码库。反向导入（ArkTS导入TS）是支持的。"
+  },
+  {
+    "name": "arkts-no-type-query",
+    "severity": "error",
+    "description": "ArkTS仅在表达式上下文中支持typeof运算符。不支持使用typeof指定类型标注。",
+    "suggestion": "请改用显式类型声明而不是typeof进行类型标注。"
+  },
+  {
+    "name": "arkts-no-types-in-catch",
+    "severity": "error",
+    "description": "在TypeScript中，catch子句变量类型标注必须是any或unknown（如果指定）。由于ArkTS不支持这些类型，因此请省略类型标注。",
+    "suggestion": "请省略catch子句中的类型标注。"
+  },
+  {
+    "name": "arkts-no-typing-with-this",
+    "severity": "error",
+    "description": "ArkTS不支持使用this关键字进行类型标注。",
+    "suggestion": "请改用显式类型。"
+  },
+  {
+    "name": "arkts-no-umd",
+    "severity": "error",
+    "description": "ArkTS不支持通用模块定义（UMD），因为它没有“脚本”的概念（与“模块”相对）。此外，import在ArkTS中是编译时特性，而不是运行时特性。",
+    "suggestion": "请改用普通的export和import语法。"
+  },
+  {
+    "name": "arkts-no-untyped-obj-literals",
+    "severity": "error",
+    "description": "ArkTS支持对象字面量，前提是编译器可以推断出这些字面量所对应的类或接口。否则，会发生编译时错误。在以下上下文中，不支持使用字面量初始化类和接口：初始化any、Object或object类型；初始化带有方法的类或接口；初始化声明带参数构造函数的类；初始化带有readonly字段的类。",
+    "suggestion": "请确保对象字面量对应于显式声明的类或接口。避免将它们用于any、Object、object类型，或用于初始化带有方法、参数化构造函数或只读字段的类。"
+  },
+  {
+    "name": "arkts-no-utility-types",
+    "severity": "error",
+    "description": "ArkTS目前不支持TypeScript扩展标准库中的实用类型。Partial、Required、Readonly和Record是例外。对于Record<K, V>类型，索引表达式rec[index]的类型为V | undefined。",
+    "suggestion": "请避免使用不支持的TypeScript实用类型。Partial、Required、Readonly和Record可用于其特定目的。"
+  },
+  {
+    "name": "arkts-no-var",
+    "severity": "error",
+    "description": "ArkTS不支持var关键字。",
+    "suggestion": "请改用let关键字。"
+  },
+  {
+    "name": "arkts-no-with",
+    "severity": "error",
+    "description": "ArkTS不支持with语句。",
+    "suggestion": "请使用其他语言惯用法来实现相同的行为。"
+  }
+]
+```
+
+## 使用说明
+
+### 在Cursor中使用
+1. 将此文件保存为 `.cursorrules` 文件
+2. 配置TypeScript/ArkTS项目的ESLint规则
+3. 确保IDE能够识别这些规则
+
+### 规则应用
+这些规则主要用于：
+- TypeScript到ArkTS的迁移
+- HarmonyOS应用开发
+- 确保代码符合ArkTS规范
+
+## 参考资源
+- [HarmonyOS ArkTS开发指南](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V14/typescript-to-arkts-migration-guide-V14)
+- 生成时间: 2025-07-01 20:04:00
+
+---
+*此文件由ArkTS规则提取器自动生成*

.cursor/rules/component_encapsulation_reuse.cursorrules.md

@@ -0,0 +1,95 @@
+# HarmonyOS 组件封装与复用 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+-   **高效复用，减少开销：** 通过组件缓存和生命周期管理，避免频繁创建和销毁UI对象，提升渲染效率。
+-   **统一封装，提升维护：** 采用标准化的封装模式，如`attributeModifier`，统一组件API风格，简化调用和维护。
+-   **数据优化，避免冗余：** 选择高效的数据传递方式，减少不必要的深拷贝和重复更新。
+-   **按需加载，动态渲染：** 利用动态UI能力实现组件的预创建和按需加载，优化页面响应速度。
+
+## 推荐做法
+
+### 推荐做法
+
+-   **组件复用声明与生命周期：**
+    -   使用`@Reusable`装饰器修饰自定义组件，使其具备复用能力。
+    -   在`aboutToReuse()`生命周期回调中，根据新数据刷新组件UI，而非在构造函数中执行所有初始化逻辑。
+    -   通过`reuseId`属性对不同结构或用途的可复用组件进行精细化分组，提高缓存匹配效率。
+-   **数据传递与状态更新：**
+    -   对于复杂对象或数组，优先使用`@Link`或`@ObjectLink`装饰器传递引用，避免深拷贝带来的性能开销。
+    -   避免在`aboutToReuse()`中对会自动更新的状态变量（如`@Link`、`@ObjectLink`、`@Prop`）进行重复赋值。
+-   **公用组件封装：**
+    -   利用ArkTS提供的`attributeModifier`属性方法，对系统组件进行封装，实现链式调用风格，统一API。
+    -   提供方可暴露`AttributeModifier`接口实现类，供调用方通过`.attributeModifier()`方法传入。
+-   **弹窗组件封装：**
+    -   使用`UIContext`中获取的`PromptAction`对象来管理自定义弹窗的显示与隐藏，确保生命周期正确。
+-   **动态UI与性能优化：**
+    -   对于需要频繁动态增删改查组件、或组件树深度和复杂度较高的场景，优先使用`FrameNode`配合`NodeController`进行组件的创建、管理和局部渲染，以获得更好的性能。
+    -   利用`onIdle()`生命周期回调或其他空闲时间进行组件预创建和缓存，减少用户感知到的加载延迟。
+
+## 禁止做法
+
+-   **函数作为入参：** 避免将函数方法直接作为复用组件的入参，这可能导致组件无法有效复用或引起不必要的渲染更新。
+-   **`@Prop`深拷贝复杂数据：** 避免使用`@Prop`传递大型或复杂的对象/数组，这会导致不必要的深拷贝，影响性能。
+-   **传统冗余封装：** 避免采用导致自定义组件入参列表过长、使用方式与系统组件不一致的传统封装方式。
+-   **过度依赖声明式`diff`：** 在需要频繁动态增删改查组件、或组件树深度和复杂度较高时，仅依赖声明式范式可能导致`diff`算法开销过大，影响性能。
+-   **整体重绘操作局部：** 避免为了操作或移动局部子组件树而重新渲染整个父组件，导致不必要的性能浪费。
+
+## 代码示例
+
+### 推荐写法
+
+```arkts
+// 推荐：@Reusable 组件及 aboutToReuse 生命周期
+@Reusable
+@Component
+struct ReusableListItem {
+  private itemData: string = ''; // 初始化，但数据更新在aboutToReuse
+  aboutToReuse(params: { data: string }) {
+    this.itemData = params.data; // 从缓存取出时，更新数据
+  }
+  build() {
+    Text(this.itemData)
+      .fontSize(16)
+      .fontColor(Color.Black);
+  }
+}
+
+// 推荐：使用 attributeModifier 封装公用组件样式
+class CommonButtonModifier implements AttributeModifier<ButtonAttribute> {
+  applyNormalAttribute(instance: ButtonAttribute): void {
+    instance.fontSize(18).fontColor(Color.White).backgroundColor(Color.Blue);
+  }
+}
+// 使用方式
+Button('提交').attributeModifier(new CommonButtonModifier());
+```
+
+### 避免写法
+
+```arkts
+// 避免：传统组件封装导致入参过多且非链式调用
+@Component
+struct MyLegacyButton {
+  @Prop text: string = '';
+  @Prop fontSize: number = 14;
+  @Prop textColor: Color = Color.Black;
+  @Prop bgColor: Color = Color.Gray;
+  // ... 如果要支持所有Button属性，此处将非常冗长
+  build() {
+    Button(this.text)
+      .fontSize(this.fontSize)
+      .fontColor(this.textColor)
+      .backgroundColor(this.bgColor);
+  }
+}
+// 调用方式: <MyLegacyButton text="确认" fontSize={16} textColor={Color.Red} bgColor={Color.Green}/>
+```
+
+## 注意事项
+
+-   **性能监控：** 在开发和测试阶段，务必关注应用的帧率、内存占用和CPU使用情况，尤其是在列表滑动、页面切换和复杂动画场景。
+-   **`FrameNode`适用性：** `FrameNode`虽性能优越，但其使用场景相对特定，主要用于对性能有极高要求且需要直接操作UI树的动态布局，并非所有动态UI都需要采用。
+-   **调试：** 利用HarmonyOS提供的DevEco Studio调试工具，特别是UI调试器，分析组件树结构和渲染性能。

.cursor/rules/declarative_syntax.cursorrules.md

@@ -0,0 +1,91 @@
+# HarmonyOS 声明式语法 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+-   **UI是状态的函数**: 确保UI显示与应用状态始终一致，状态变更可预测。
+-   **性能优先**: 优化UI刷新机制，避免不必要的组件渲染，提升应用性能。
+-   **状态与UI解耦**: 将状态管理逻辑从UI组件中分离，提高组件复用性和代码可维护性。
+-   **单向数据流**: 遵循明确的数据流向，简化状态管理复杂度。
+
+## 推荐做法
+
+### 代码结构
+-   **集中共享状态**: 对于多组件共享的状态，推荐使用`StateStore`进行全局管理，将数据集中存储，实现状态与UI的解耦。
+-   **观测数据定义**: 所有需要被`StateStore`管理且能触发UI更新的业务数据，必须使用`@Observed`或`@ObservedV2`装饰器修饰。
+-   **纯函数Reducer**: 将所有的状态更新逻辑封装在独立的纯函数（Reducer）中，确保状态变更的单一职责和可预测性。
+
+### 最佳实践
+-   **理解刷新机制**: 深入理解`@State`, `@Prop`, `@Link`等装饰器的工作原理，明确它们如何触发UI刷新。
+-   **审慎使用`@Link`**: `Link`实现双向绑定。若仅需单向传递数据，优先考虑`@Prop`或普通参数，以减少不必要的子组件刷新范围。
+-   **按需使用状态变量**: 仅当变量的改变需要触发UI更新时，才使用相应的状态装饰器对其进行标记。
+-   **事件驱动状态更新**: 状态的改变应发生在用户交互（如`onClick`）、生命周期回调（如`onAppear`）、数据请求回调等明确的事件中。
+
+## 禁止做法
+
+-   **`build`方法副作用**: 绝对避免在组件的`build`方法或其直接调用的计算属性/函数中修改非状态变量或执行其他副作用操作。
+-   **冗余状态变量**: 禁止将未关联任何UI组件、或仅被读取但从未被修改的变量定义为状态变量（例如，未在`build`方法中使用的`@State`变量）。
+-   **不必要的`@Link`**: 避免在仅需单向数据流的场景下使用`@Link`，这会增加不必要的双向依赖和刷新风险。
+
+## 代码示例
+
+### 推荐写法
+```arkts
+@Component
+struct MyCounter {
+  @State count: number = 0; // 状态变量，UI依赖
+
+  build() {
+    Column() {
+      Text(`当前计数: ${this.count}`)
+        .fontSize(24)
+      Button('增加')
+        .onClick(() => {
+          this.count++; // 状态在事件回调中修改，触发UI刷新
+        })
+    }
+  }
+}
+```
+
+### 避免写法
+```arkts
+// 避免写法1: 在build方法直接调用的函数中引入副作用
+@Component
+struct BadImageEffect {
+  private currentOpacity: number = 0; // 非状态变量
+
+  // 该函数在每次build时都会被调用，意外修改非状态变量
+  private calculateOpacity(): number {
+    this.currentOpacity = (this.currentOpacity + 0.1) % 1;
+    return this.currentOpacity;
+  }
+
+  build() {
+    Image('icon.png')
+      .opacity(this.calculateOpacity()) // 每次UI刷新都累加opacity
+  }
+}
+
+// 避免写法2: 冗余状态变量
+@Entry
+@Component
+struct BadComponent {
+  // 变量未关联任何UI组件，或仅被读取但未修改，不应定义为状态变量
+  @State unusedData: string = 'some data';
+  @State readonlyMessage: string = 'Hello';
+
+  build() {
+    Column() {
+      // 仅读取readonlyMessage，未修改
+      Text(this.readonlyMessage)
+    }
+  }
+}
+```
+
+## 注意事项
+
+-   **利用开发工具**: 使用HarmonyOS提供的诊断工具（如`hidumper`）来分析应用运行时状态变量的变化和UI组件的刷新情况，定位冗余刷新问题。
+-   **代码静态检查**: 定期使用`Code Linter`工具进行代码检查，重点关注性能优化规则（如`@performance/hp-arkui-remove-redundant-state-var`），并根据扫描结果进行优化。

.cursor/rules/gesture_navigation.cursorrules.md

@@ -0,0 +1,89 @@
+# HarmonyOS 手势与导航 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+*   理解HarmonyOS触摸事件的分发机制和事件响应链的构建过程，是解决手势冲突的基础。
+*   优先使用HarmonyOS提供的标准UI组件（如`Tabs`）构建导航，确保一致、高效的用户体验。
+*   利用HMRouter简化页面路由管理，提升开发效率和代码可维护性，避免手动管理页面栈。
+
+## 推荐做法
+
+### 代码结构
+*   使用`@Builder`装饰器封装可复用的UI模块，例如自定义底部页签的图标和文字组合 (`TabItemBuilder`)。
+*   通过`@HMRouter`注解为目标页面注册唯一的`pageUrl`，实现声明式路由配置。
+
+### 最佳实践
+*   **手势事件冲突解决**：
+    *   通过`hitTestBehavior`属性精确控制组件的触摸测试行为：
+        *   `HitTestMode.Transparent`: 组件自身响应，但允许事件继续向下或向上透传。
+        *   `HitTestMode.Block`: 组件命中后独占事件，阻塞事件向兄弟节点和父组件传递。
+    *   在触摸或手势回调函数中，适时调用`event.stopPropagation()`，立即停止事件向上冒泡。
+*   **底部页签导航**：
+    *   使用`Tabs`组件作为底部导航容器，并设置`barPosition: BarPosition.End`。
+    *   为每个`TabContent`组件通过`tabBar`属性定义其对应的页签外观（包括选中和未选中状态的图标及文字）。
+    *   对于固定数量的页签，设置`Tabs`的`barMode: Fixed`以平均分配页签宽度。
+*   **页面跳转与返回**：
+    *   使用`HMRouterMgr.push()`或`HMRouterMgr.replace()`方法进行页面跳转，并可通过`param`参数传递数据。
+    *   在目标页面（被跳转页）的`aboutToAppear`生命周期中，通过`HMRouterMgr.getCurrentParam()`获取跳转参数。
+    *   在`push/replace`方法的`onResult`回调中接收从其他页面返回的数据，并通过`popInfo.srcPageInfo.name`判断返回源页面。
+
+## 禁止做法
+
+*   **过度阻塞手势事件**：未经深思熟虑地滥用`HitTestMode.Block`或`event.stopPropagation()`，可能导致用户交互失效或应用行为异常。
+*   **手动管理页面栈**：避免直接操作底层的`Navigation`能力进行页面跳转和栈管理，应优先使用HMRouter提供的统一接口。
+
+## 代码示例
+
+### 推荐写法
+```arkts
+// 手势冲突处理: 独占区域手势，不向上冒泡
+Column() {
+  Text('点击我，事件在此终止')
+}
+.width('100%').height(100)
+.backgroundColor(Color.Blue)
+.hitTestBehavior(HitTestMode.Block) // 独占所有触摸事件
+.onClick(() => {
+  console.log('Column clicked, event stopped here.');
+})
+
+// 底部页签导航 (简化示例)
+Tabs({ barPosition: BarPosition.End }) {
+  TabContent() { Text('消息页面').fontSize(24) }
+    .tabBar(this.TabItemBuilder('消息', $r('app.media.message_icon'))) // 自定义页签样式
+  TabContent() { Text('我的页面').fontSize(24) }
+    .tabBar(this.TabItemBuilder('我的', $r('app.media.profile_icon')))
+}
+
+@Builder TabItemBuilder(text: string, icon: Resource) {
+  Column() {
+    Image(icon).width(24).height(24)
+    Text(text).fontSize(12)
+  }
+}
+
+// 页面跳转与参数传递，并接收返回结果
+HMRouterMgr.push({
+  pageUrl: 'pages/DetailPage', // 目标页面路由
+  param: { id: 123, name: 'Product A' }, // 传递参数
+  onResult: (popInfo) => { // 接收返回结果
+    if (popInfo.srcPageInfo.name === 'pages/DetailPage') {
+      console.log('Returned from DetailPage with result:', popInfo.result);
+    }
+  }
+});
+```
+
+### 避免写法
+```arkts
+// 避免不加区分地在父子组件上都使用onTouch，且不控制事件冒泡，这会增加手势冲突的风险。
+// 避免在存在多个HMNavigation组件时，不指定HMRouterMgr跳转的navigationId，可能导致页面跳转到错误的栈。
+```
+
+## 注意事项
+
+*   在使用`hitTestBehavior`和`event.stopPropagation()`时，务必充分测试，确保用户交互的连贯性和预期性。
+*   在应用中存在多个`HMNavigation`组件（如多窗口、多页面栈）时，务必为`HMRouterMgr.push/replace`方法明确指定正确的`navigationId`，以确保页面跳转到正确的导航栈。
+*   为底部导航的页签提供清晰的图标（区分选中和未选中态）和简洁的文字标签，以提升用户识别度和整体用户体验。

.cursor/rules/layout_dialog.cursorrules.md

@@ -0,0 +1,94 @@
+```markdown
+# HarmonyOS 布局与弹窗 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+-   **性能优先，流畅体验**：精简UI节点，优化布局计算，确保动画和滚动平滑。
+-   **用户为中心**：提供直观、自然、可预期的交互手势和反馈。
+-   **组件化与复用**：封装可复用组件，利用数据驱动UI，提升开发效率和可维护性。
+-   **适配多样性**：考虑不同设备形态（如折叠屏、软键盘）的布局与交互适配。
+
+## 推荐做法
+
+### 代码结构
+-   将复杂或可复用的UI模块（如瀑布流、评论弹窗、图片预览器）封装为独立的自定义组件。
+-   通过数据驱动UI渲染，根据数据类型动态选择和渲染列表项（`ListItem`、`GridItem`）或弹窗内容。
+
+### 最佳实践
+-   **布局与性能优化**：
+    -   **精简UI节点**：避免不必要的布局嵌套，优先使用扁平化布局。
+    -   **设置布局边界**：为父级容器明确设置固定宽高（如`width('100%').height(xxx)`），减少局部UI更新时的全局重计算。
+    -   **长列表优化**：对于大量数据，务必使用`LazyForEach`替代`ForEach`实现懒加载和组件复用。当`List`嵌套在`Scroll`内时，为`List`明确设置固定宽高。
+    -   **条件渲染**：根据组件是否需要存在于组件树中，合理选择`if/else`（减少节点）或`visibility`（保留占位）。
+-   **交互与动画**：
+    -   **图片跟手效果**：利用`matrix4`实现缩放跟手，`translate`实现平移跟手，确保精确数学计算。
+    -   **列表交互**：结合`Refresh`组件实现下拉刷新，利用`List.onReachEnd()`实现上滑加载更多，并提供清晰的状态反馈。
+    -   **拖拽交换**：`Grid`组件开启`editMode(true)`和`supportAnimation(true)`，并为`GridItem`绑定`LongPressGesture`和`PanGesture`。
+    -   **自定义指示器**：`Swiper`组件禁用自带`indicator(false)`，并自定义进度条指示器，与`Swiper`页面切换联动。
+    -   **文本展开折叠**：使用`measureTextSize()`精确测量文本高度，计算截断点，实现“...展开/收起”功能。
+-   **弹窗管理**：
+    -   **弹窗选型**：对于评论回复等复杂交互场景，优先选择`Navigation Dialog`或统一的`DialogHub`方案，而非`CustomDialog`。
+    -   **交互控制**：精细控制弹窗的关闭行为（如是否允许侧滑、点击外部关闭），并自定义进出场动画。
+    -   **键盘适配**：确保弹窗能自动避让软键盘，避免内容遮挡；在软键盘和表情面板切换时平滑过渡。
+    -   **多弹窗管理**：利用`DialogHub`管理多弹窗层级，确保显示优先级。
+
+## 禁止做法
+
+-   **长列表一次性渲染**：避免对大量数据直接使用`ForEach`，导致性能瓶颈和内存占用过高。
+-   **不当的弹窗选型**：避免将`CustomDialog`用于需要复杂软键盘避让和动画控制的场景（如评论回复弹窗），因为它存在不可配置的局限性。
+-   **依赖默认指示器**：当需要自定义进度条或复杂动画时，不应直接依赖`Swiper`组件自带的`indicator`。
+-   **过度嵌套布局**：避免不必要的组件嵌套，增加UI节点数量和布局计算开销。
+-   **重要弹窗随意关闭**：对于关键提示或需用户确认的弹窗，禁止允许侧滑或点击外部区域关闭。
+
+## 代码示例
+
+### 推荐写法
+```arkts
+// 推荐：长列表懒加载与Swiper自定义指示器
+Swiper() {
+  LazyForEach(this.imageData, (item: ImageItem) => {
+    Image(item.src)
+  }, (item: ImageItem) => item.id)
+}
+.autoPlay(true)
+.indicator(false) // 关闭默认指示器
+// ... 自定义进度条指示器逻辑 (通常是一个独立的组件或布局)
+
+// 推荐：List与下拉刷新、上滑加载
+List() {
+  // ... ListItem内容
+}
+.onScrollIndex((first, last) => {
+  // 仅渲染可见区域，此处可监听加载更多
+  if (last >= this.data.length - 5 && !this.isLoading) {
+    this.loadMoreData();
+  }
+})
+.width('100%')
+.height(this.listHeight) // List在Scroll内时需固定宽高
+```
+
+### 避免写法
+```arkts
+// 避免：长列表一次性渲染或过多嵌套
+Column() { // 避免不必要的Column/Row包裹
+  Row() { // 避免多层嵌套
+    Text('Title')
+  }
+  ForEach(this.largeData, (item: DataItem) => { // 避免直接ForEach大量数据
+    Column() {
+      // ... 复杂UI
+    }
+  })
+}
+```
+
+## 注意事项
+
+-   **充分测试**：在不同设备形态、屏幕尺寸和输入法环境下测试UI的布局、交互和性能。
+-   **异常处理**：在数据加载、刷新等异步操作中，务必处理网络异常、数据为空等情况，并提供清晰的用户反馈。
+-   **计算精确性**：涉及复杂动画（如图片跟手）或文本处理（如展开折叠）时，确保数学计算的精确性，避免视觉抖动或错误。
+-   **状态管理**：封装可复用组件时，明确其内部状态管理机制，确保在不同场景下状态的独立性或可控性。
+```

.cursor/rules/theme_style.cursorrules.md

@@ -0,0 +1,86 @@
+# HarmonyOS 主题与样式 - Cursor Rules
+
+你正在为HarmonyOS应用开发相关功能。以下是你需要遵循的开发规则。
+
+## 核心原则
+
+- **响应用户/系统偏好**: UI应自动适配深浅色模式及用户自定义亮度。
+- **保持视觉一致性**: 在不同模式和页面间，保持UI元素的统一性和协调性。
+- **优化资源与性能**: 合理管理资源，避免不必要的电量消耗和性能开销。
+- **提供流畅用户体验**: 确保用户在不同场景下（如视频播放、付款码）获得无缝且舒适的体验。
+
+## 推荐做法
+
+### 代码结构
+- **资源目录管理**: 利用HarmonyOS的资源目录机制 (`src/main/resources/base` 用于浅色模式，`src/main/resources/dark` 用于深色模式) 管理深浅色资源。
+- **同名资源定义**: 在 `base` 和 `dark` 目录下，为同一种UI元素（如颜色、图片）定义**同名**的资源文件和资源项，实现自动切换。
+
+### 最佳实践
+- **深浅色模式适配**:
+    - **颜色资源**: 自定义颜色应定义在 `base/element/color.json` 和 `dark/element/color.json` 中，并通过 `$('app.color.your_color_name')` 引用。优先使用系统级颜色资源。
+    - **媒体资源**:
+        - SVG图标: 利用 `fillColor()` 属性，使其颜色跟随当前主题变化。
+        - 非SVG图片: 在 `base/media` 和 `dark/media` 目录下放置同名图片资源。
+    - **状态栏**: 确保状态栏背景和内容字体颜色与应用深浅模式保持一致。
+    - **Web页面**: 配合前端开发，使应用内嵌Web内容支持深色模式（利用CSS媒体查询 `prefers-color-scheme`）。
+    - **模式切换**: 提供应用跟随系统模式切换 (`applicationContext.setColorMode(ColorMode.COLOR_MODE_NOT_SET)`) 或用户手动切换的选项。
+- **页面亮度与常亮控制**:
+    - **页面级亮度**: 使用 `window.setWindowBrightness()` 实现页面专属亮度。利用 `uiObserver.on('navDestinationUpdate')` 监听页面跳转，并在页面进入时应用亮度，离开时恢复系统默认或前一页面的亮度。
+    - **屏幕常亮**: 在沉浸式场景（如视频播放）中，通过 `window.setWindowKeepScreenOn(true)` 保持屏幕常亮。务必将其与组件生命周期绑定（如 `onStart` 开启，`onPause`/`onDestroy` 关闭）。
+    - **用户UI**: 为需要用户调节亮度的场景（如视频播放器）提供 `Slider` 等UI组件，方便用户调节。
+
+## 禁止做法
+
+- **硬编码颜色值**: 避免直接在代码中写入十六进制或RGB颜色值，应统一通过资源引用。
+- **不及时关闭屏幕常亮**: 在不需要常亮时（如视频暂停、页面退出）不调用 `setWindowKeepScreenOn(false)`，导致不必要的电量消耗和设备发热。
+- **深浅色资源命名不一致**: 在 `base` 和 `dark` 目录下为同一元素定义不同的资源名称，导致深浅色模式切换失败。
+
+## 代码示例
+
+### 推荐写法
+```arkts
+// 1. 深浅色模式下引用颜色资源
+Text('Hello HarmonyOS')
+  .fontColor($r('app.color.text_primary')) // text_primary 在base和dark下定义不同颜色
+
+// 2. 页面亮度动态设置与屏幕常亮
+// 假设在视频播放页面的某个组件内
+@State currentBrightness: number = 0.5; // 当前页面亮度
+
+aboutToAppear() {
+  // 进入页面时设置亮度，并保持屏幕常亮
+  window.setWindowBrightness(this.currentBrightness);
+  window.setWindowKeepScreenOn(true);
+}
+
+aboutToDisappear() {
+  // 离开页面时恢复系统亮度，并关闭屏幕常亮
+  window.setWindowBrightness(-1); // -1 表示恢复系统默认亮度
+  window.setWindowKeepScreenOn(false);
+}
+
+// 用户通过Slider调节亮度
+Slider({ value: this.currentBrightness, min: 0.01, max: 1.0, step: 0.01 })
+  .onChange((value: number) => {
+    this.currentBrightness = value;
+    window.setWindowBrightness(value);
+  })
+```
+
+### 避免写法
+```arkts
+// 1. 硬编码颜色值
+Text('Avoid this')
+  .fontColor('#FF0000') // 硬编码红色，在深色模式下可能不协调
+
+// 2. 随意开启屏幕常亮，不及时关闭
+// 假设某个地方开启了常亮，但没有对应的关闭逻辑
+window.setWindowKeepScreenOn(true); // 容易造成电量浪费
+```
+
+## 注意事项
+
+- **资源自动切换**: HarmonyOS会自动根据系统颜色模式加载对应资源目录下的同名资源，无需额外代码判断。
+- **页面亮度作用域**: `window.setWindowBrightness()` 仅在当前应用内生效，退出应用后系统亮度会自动恢复。
+- **Web组件适配**: Web内容的深色模式适配通常需要前端开发人员配合完成，确保Web内容自身支持 `prefers-color-scheme`。
+- **权限**: 某些亮度或窗口操作可能需要特定权限，请查阅官方文档。