@quicktvui/ai 1.0.3 → 1.0.5

package/README.md

@@ -1,25 +1,25 @@
 # @quicktvui/ai
 
-QuickTVUI 官方提供的 AI 辅助开发规范包。
-安装后，会自动将 QuickTVUI 的严格开发规范、架构避坑指南（不支持 HTML、组件用法等）、以及本地文档库注入到你的项目中。
+> **让 AI 助你丝滑开发 QuickTVUI，彻底告别“Web 习惯”导致的运行报错。**
 
-## 它可以做什么？
+`@quicktvui/ai` 是 QuickTVUI 官方提供的 AI 辅助开发规范包。它通过向你的项目中注入经过深度调优的 AI 指令（Rules）和本地知识库，让 Cursor、Windsurf、Copilot、Cline 等 AI 助手瞬间化身为“QuickTVUI 资深专家”。
 
-安装本包后，它会自动在你的项目根目录下生成并配置：
-- `.cursorrules` (供 Cursor 使用)
-- `.windsurfrules` (供 Windsurf 使用)
-- `.clinerules` (供 Cline/Roo-Code 使用)
-- `.github/copilot-instructions.md` (供 GitHub Copilot 使用)
-- `GEMINI.md` / `CLAUDE.md` / `AGENTS.md` (供其他模型使用)
-- `.docs/` (本地轻量级 QuickTVUI 知识库)
+---
 
-这些规则会强制 AI：
-1. **停止捏造标签**（如禁止使用 `qt-web-view`，强制使用 `qt-web`）。
-2. **遵守非浏览器环境**（禁止使用 `window`, `document` 和任何标准 HTML 标签，如 `p`, `div` 以外的标签）。
-3. **正确的播放器架构**（强制使用 `es-player-manager`）。
-4. **严格的 CSS 子集**（禁止简写，禁止 auto 等）。
+## 🚀 为什么需要它？
 
-## 安装方式
+QuickTVUI 运行在 TV 端原生环境（Hippy-based），虽然使用 Vue 语法，但它**不是浏览器**。开发者在使用 AI 辅助编程时，AI 极其容易带入传统的 Web 开发习惯，导致生成无法运行的代码：
+
+- ❌ **误用 HTML 标签**：生成了 `<p>`, `<img>`, `<a>` 等标签（QuickTVUI 必须使用 `qt-text`, `qt-image`）。
+- ❌ **误用 DOM API**：使用了 `window`, `document`, `alert()`（原生环境不存在这些对象）。
+- ❌ **无效的 CSS**：使用了简写（`margin: 10px`）或 `auto` 尺寸（QuickTVUI 严格要求拆写且必须是 `px`）。
+- ❌ **错误的播放器架构**：直接使用 `<video>` 标签（必须使用 `es-player-manager`）。
+
+**安装 `@quicktvui/ai` 后，这些问题将不复存在。AI 将严格遵守框架规范，生成 100% 可运行的 TV 端代码。**
+
+---
+
+## 📦 安装方式
 
 在你的 QuickTVUI 项目根目录下运行：
 
@@ -29,8 +29,88 @@ npm install @quicktvui/ai --save-dev
 yarn add @quicktvui/ai --dev
 ```
 
-> 安装完成后，脚本会自动将相关规范和文档拷贝到你的项目根目录。如果你的项目使用 Git，它还会自动执行 `git add`。
+安装完成后，脚本会自动执行以下操作：
+1. **注入配置文件**：在根目录生成 `.cursorrules`, `.clinerules`, `GEMINI.md`, `CLAUDE.md` 等。
+2. **配置 Copilot**：在 `.github/` 下注入 Copilot 专用指令。
+3. **关联知识库**：让 AI 能够检索 `node_modules` 中内置的组件详细文档。
+4. **自动忽略**：自动更新 `.gitignore`，确保这些辅助配置文件不会污染你的 Git 提交。
+
+---
+
+## 🤖 支持的 AI 工具与配置
+
+本包一次性适配了市面上主流的 AI 编程助手，安装后会自动在项目根目录生成对应的配置文件：
+
+| AI 工具 | 核心配置文件 | 配置方式 |
+| :--- | :--- | :--- |
+| **Cursor** | `.cursorrules` | 自动加载，无需额外设置 |
+| **Windsurf** | `.windsurfrules` | 自动加载，级联项目上下文 |
+| **Cline (Roo-Code)** | `.clinerules` | 自动加载，作为 Agent 的全局指令 |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | 自动生效 (需较新版本的 Copilot 插件) |
+| **Gemini CLI** | `GEMINI.md` | 自动被 Gemini 及其相关工具链引用 |
+| **Claude Code** | `CLAUDE.md` / `.claude/` | 深度适配，提供 `/create-page` 等快捷指令 |
+
+---
+
+## 🌟 强力推荐：最佳模型选择
+
+为了获得最精准的 QuickTVUI 代码生成效果，我们**强烈建议**开发者配合以下最新一代 AI 模型使用：
+
+1.  **Claude 3.5 Sonnet (推荐)**：目前对 QuickTVUI 复杂焦点逻辑和样式约束理解最深刻的模型，逻辑严密，极少幻觉。
+2.  **GitHub Copilot (基于 Codex/GPT-4o)**：响应速度快，适合日常组件编写和代码补全。
+3.  **Gemini 1.5 Pro / Flash**：拥有超长上下文窗口，能够一次性理解项目中的多个页面关系，适合进行大型功能重构。
+
+> **提示**：在使用这些 AI 时，请确保已启用“读取项目文件”或“代码库索引”功能，以便 AI 能够自动发现并遵循本项目注入的 `.docs` 文档。
+
+---
+
+## ✨ 它强制 AI 遵守的核心规范
+
+安装后，AI 将掌握以下“生存法则”：
+
+### 1. 零 HTML 与 零 DOM
+- 绝对禁止使用 `p`, `img`, `ul`, `li`, `h1`, `button` 等标签。
+- 绝对禁止使用 `window`, `document`, `e.preventDefault()`。
+- 必须使用 `qt-text`, `qt-image`, `qt-view` 等原生对应组件。
+
+### 2. 严格的 CSS 子集
+- 必须使用 `px` 单位，严禁使用 `%`, `auto`, `rem`, `vh` 等。
+- 严禁 CSS 属性简写（如 `margin` 必须拆分为 `margin-top` 等）。
+- 必须显式声明 `display: flex` 且默认方向为 `column`。
+
+### 3. TV 特有的焦点系统
+- 自动为交互元素添加 `:focusable="true"`。
+- 自动处理 `focusScale` 带来的 `clipChildren="false"` 适配问题。
+
+### 4. 正确的命名协议
+- 返回键处理函数必须叫 `onBackPressed`。
+- 生命周期必须叫 `onESCreate`, `onESResume` 等。
+
+### 5. AI 哨兵：自动化问题上报
+当 AI 发现代码符合规范但仍运行报错，或者同一问题修复 3 次未果时，它会启动**问题上报机制**：
+- **脱敏诊断**：自动整理报错日志、环境信息并编写最小可复现 Demo。
+- **一键上报**：在获得你授权后，AI 会自动尝试打开浏览器或生成 GitHub Issue 链接，助你快速反馈给官方。
+
+---
+
+## 🔍 验证注入是否成功
+
+安装完成后，检查项目根目录，如果出现以下文件，说明注入成功：
+- `.cursorrules`
+- `.clinerules`
+- `.windsurfrules`
+- `GEMINI.md`
+- `CLAUDE.md`
+- `.quicktvui-ai-backup/` (如有旧配置，会自动备份在此)
+
+---
+
+## 🛠️ 进阶使用：本地知识库
+
+本包在 `node_modules/@quicktvui/ai/rules/.docs/` 下内置了约 400 篇 QuickTVUI 核心组件及 API 文档。你的 AI 助手现在具备了“离线查阅文档”的能力，生成代码前它会先检索本地文档，确保参数和用法 100% 准确。
+
+---
 
-## 验证
+## 📄 开源协议
 
-安装完毕后，请检查你的项目根目录是否多出了 `.cursorrules` 等文件以及 `.docs` 目录。如果有，说明注入成功，尽情享受不踩坑的 AI 编程体验吧！
+MIT License.

package/USAGE.md

@@ -0,0 +1,74 @@
+# @quicktvui/ai 开发者使用指南
+
+本指南将帮助你利用 AI 助手高效地开发 QuickTVUI 应用。
+
+## 1. 快速上手
+
+### 第一步：安装规范包
+
+在你的 QuickTVUI 项目（建议使用 `quicktvui-template` 创建）中安装：
+
+```bash
+npm install @quicktvui/ai --save-dev
+```
+
+### 第二步：配置并开启推荐模型
+
+为了达到最佳辅助效果，请在你的 AI 工具中优先选择以下模型：
+
+- **Claude **
+- **Codex**
+- **Gemini**
+
+AI 助手将自动读取项目根目录下的 `.cursorrules`, `GEMINI.md`, `CLAUDE.md` 等文件中的指令。
+
+## 2. 常见场景 AI 辅助示例
+
+### 场景 A：创建新页面
+
+**输入：** `/create-page 首页`
+**AI 将生成：** 包含 `onESCreate`, `onBackPressed`, `:autofocus="true"` 以及正确 CSS（kebab-case + px 单位）的代码。
+
+### 场景 B：API 查询
+
+**输入：** “qt-image 支持哪些属性？”
+**AI 将检索：** 它会查阅 `node_modules/@quicktvui/ai/rules/.docs/component/image.md` 并返回：`src`, `enableFade`,
+`resizeMode` 等原生支持的属性。
+
+### 场景 C：样式纠错
+
+**输入：** “这段样式哪里不对？ `.box { margin: 10px; width: 100%; }`”
+**AI 将纠错：** “在 QuickTVUI 中不能使用 `margin` 简写，必须拆写为 `margin-top` 等；且不能使用 `100%`，必须使用具体的 `px`
+值。”
+
+## 3. 开发检查清单 (Checklist)
+
+当 AI 为你生成代码后，请务必核对以下关键点：
+
+- [ ] **标签检查**：是否误用了 `p`, `img`, `h1`？（必须是 `qt-text`, `qt-image`）
+- [ ] **生命周期**：入口函数是否叫 `onESCreate(params)`？
+- [ ] **返回键**：处理函数是否叫 `onBackPressed()` 且已 `return`？
+- [ ] **焦点系统**：页面是否至少有一个元素设置了 `:autofocus="true"`？
+- [ ] **样式单位**：是否所有数值都带 `px`？是否误用了 `auto` 或 `%`？
+- [ ] **属性命名**：`<template>` 标签属性用 `camelCase`，`<style>` 样式名用 `kebab-case`。
+
+## 4. 如何使用 AI 反馈框架问题 (Bug Reporting)
+
+如果你在开发中发现框架可能存在 Bug（例如 AI 生成的代码符合规范但仍运行报错），你可以直接通过 AI 进行上报：
+
+1. **触发上报**：你可以直接对 AI 说：“我想上报一个 Bug”、“这段代码运行报错，帮我反馈给官方”。
+2. **AI 自动诊断**：
+   - AI 会自动检测你的运行环境和报错日志。
+   - 它会尝试编写一个**脱敏后的最小可复现 Demo**。
+3. **寻求授权**：AI 会询问你：“检测到该问题可能属于框架缺陷，是否允许我协助将其上报到 GitHub 官方仓库？”
+4. **快速提交**：获得授权后，AI 会自动尝试在你的电脑上**打开浏览器并预填充 GitHub Issue 内容**，你只需核对后点击提交即可。
+
+---
+
+## 5. 故障排除
+
+如果 AI 生成了错误的代码（例如使用了 Web 标签）：
+
+1. **重新引用规则**：告诉它：“请参考项目根目录下的 `.cursorrules` (或 `GEMINI.md`) 重新检查规范。”
+2. **强制读取文档**：告诉它：“请读取 `node_modules/@quicktvui/ai/rules/.docs/` 下的相关组件文档后再回答。”
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "QuickTVUI AI 开发规范与脚手架注入工具",
   "main": "index.js",
   "scripts": {

package/postinstall.js

@@ -41,7 +41,7 @@ function copyDirectorySync(src, dest) {
 }
 
 try {
-  const rootItems = fs.readdirSync(rulesDir);
+  const rootItems = fs.readdirSync(rulesDir).filter((item) => item !== ".docs");
   let backupNeeded = false;
 
   // 1. 检查并备份现有配置
@@ -69,7 +69,15 @@ try {
   }
 
   // 2. 注入新规则
-  copyDirectorySync(rulesDir, projectRoot);
+  rootItems.forEach((item) => {
+    const srcPath = path.join(rulesDir, item);
+    const destPath = path.join(projectRoot, item);
+    if (fs.lstatSync(srcPath).isDirectory()) {
+      copyDirectorySync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  });
   console.log("🎉 [@quicktvui/ai] AI 规范注入成功！");
 
   // 3. 更新 .gitignore

package/rules/.clinerules

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -38,6 +38,10 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
 2.  **List Components (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**:
     *   You MUST set `listenBoundEvent="true"` and listen to `@item-bind`.
     *   The "Loading More" template `type` **MUST** be `1002`. The "End of List" template `type` **MUST** be `1003`.
+    *   **Waterfall Critical Rules (qt-waterfall)**:
+        *   Custom item root nodes **MUST** include `layout="${layout}"` and `flexStyle="${style}"` to avoid stacking/overlapping.
+        *   Local image paths in waterfall data **MUST** use the `file://` protocol (e.g., `file://${icon}`).
+        *   Refer to `node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md` for full layout logic.
 3.  **Zero HTML & Zero DOM**:
     *   **This is NOT a browser.** It compiles to Hippy Native Android Views.
     *   **Banned Tags**: Standard HTML tags (`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>`) will **CRASH** the app. Use only `div`, `span`, or `qt-*` tags.
@@ -147,7 +151,7 @@ Other CSS rules:
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范 but 无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：

package/rules/.cursorrules

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -35,9 +35,14 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
 1.  **Media Playback Architecture**:
     *   **NEVER** use HTML5 `<video>`, `<audio>`, or `qt-web-view` for media.
     *   **Best Practice**: You MUST prioritize using **`es-player-manager`** wrapping `es-video-player` or `es-audio-player`. The manager handles playlists, window sizing (full/small), and focus. Using the base player alone leads to missing logic.
-2.  **List Components (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**:
+2. **List Components (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**:
     *   You MUST set `listenBoundEvent="true"` and listen to `@item-bind`.
     *   The "Loading More" template `type` **MUST** be `1002`. The "End of List" template `type` **MUST** be `1003`.
+    *   **Waterfall Critical Rules (qt-waterfall)**:
+        *   Custom item root nodes **MUST** include `layout="${layout}"` and `flexStyle="${style}"` to avoid stacking/overlapping.
+        *   Local image paths in waterfall data **MUST** use the `file://` protocol (e.g., `file://${icon}`).
+        *   Refer to `node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md` for full layout logic.
+
 3.  **Zero HTML & Zero DOM**:
     *   **This is NOT a browser.** It compiles to Hippy Native Android Views.
     *   **Banned Tags**: Standard HTML tags (`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>`) will **CRASH** the app. Use only `div`, `span`, or `qt-*` tags.
@@ -147,7 +152,7 @@ Other CSS rules:
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：

package/rules/.docs/examples/css/pseudo-classes/v-pseudo.vue

@@ -0,0 +1,57 @@
+<template>
+  <div class="es-sdk-root-css" :clipChildren="false">
+    <div class="es-sdk-content-column-css" :clipChildren="false">
+      <qt-button text="改变值" @click="onButtonClicked" />
+      <div
+        v-pseudo:test="value"
+        class="div-v-pseudo-css"
+        :focusable="true"
+        :enableFocusBorder="true"
+        :focusScale="1"
+        @focus="onFocus"
+      />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { ref } from "vue";
+import { defineComponent } from "@vue/runtime-core";
+
+export default defineComponent({
+  emits: [],
+  setup() {
+    const value = ref<boolean>(false);
+
+    function onButtonClicked() {
+      value.value = !value.value;
+    }
+
+    const onFocus = (e) => {
+      const focused = e.isFocused;
+    };
+
+    return {
+      onFocus,
+      onButtonClicked,
+      value,
+    };
+  },
+});
+</script>
+
+<style scoped>
+.div-v-pseudo-css {
+  width: 192px;
+  height: 108px;
+  margin: 20px;
+  background: green;
+}
+
+.div-v-pseudo-css:test {
+  width: 384px;
+  height: 216px;
+  margin: 20px;
+  background: palevioletred;
+}
+</style>

package/rules/.docs/examples/guide/slot/lifecycle-hooks.vue

@@ -0,0 +1,108 @@
+<script>
+import { defineComponent } from '@vue/runtime-core'
+import { ESLogLevel, ESSlotEventName, useESLog } from '@extscreen/es3-core'
+import {
+  onESAttached,
+  onESBind,
+  onESCreate,
+  onESDestroy,
+  onESDetached,
+  onESNewIntent,
+  onESPause,
+  onESRecycle,
+  onESRestart,
+  onESRestoreInstanceState,
+  onESResume,
+  onESSaveInstanceState,
+  onESSlotEvent,
+  onESStart,
+  onESStop,
+} from '@extscreen/es3-vue'
+import type { ESData, ESSlotEvent } from '@extscreen/es3-core'
+
+const TAG = 'Lifecycle'
+
+export default defineComponent({
+  name: 'JsView生命周期',
+  setup() {
+    const log = useESLog()
+
+    onESCreate((params) => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESCreate----->>>', params)
+      }
+    })
+
+    onESBind((data: ESData) => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESBind----->>>', data)
+      }
+    })
+
+    onESAttached((data: ESData) => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESAttached----->>>', data)
+      }
+    })
+
+    onESStart(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESStart----->>>')
+      }
+    })
+
+    onESRestart(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESRestart----->>>')
+      }
+    })
+
+    onESResume(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESResume----->>>')
+      }
+    })
+
+    onESPause(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESPause----->>>')
+      }
+    })
+
+    onESStop(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESStop----->>>')
+      }
+    })
+
+    onESDetached((data: ESData) => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESDetached----->>>', data)
+      }
+    })
+
+    onESRecycle(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESRecycle----->>>')
+      }
+    })
+
+    onESDestroy(() => {
+      if (log.isLoggable(ESLogLevel.DEBUG)) {
+        log.d(TAG, '---onESDestroy----->>>')
+      }
+    })
+
+    onESSlotEvent((event: ESSlotEvent) => {
+      //JsView焦点事件
+      if (event.eventName == ESSlotEventName.ES_SLOT_EVENT_NAME_FOCUS) {
+        if (event.eventData.isFocused) {
+          //
+        } else {
+          //
+        }
+      }
+    })
+  },
+})
+</script>

package/rules/.docs/examples/module/key/component-event.vue

@@ -0,0 +1,36 @@
+<template>
+  <div class="es-key-event-view-css" @keydown="onKeyDown" @keyup="onKeyUp" />
+</template>
+
+<script lang="ts">
+import { defineComponent } from "@vue/runtime-core";
+import type { ESKeyEvent } from "@extscreen/es3-core";
+
+const TAG = "ESKeyEventView";
+
+export default defineComponent({
+  name: "EsKeyEventView",
+  emits: [],
+  setup() {
+    function onKeyDown(keyEvent: ESKeyEvent) {
+      //
+    }
+
+    function onKeyUp(keyEvent: ESKeyEvent) {
+      //
+    }
+
+    return {
+      onKeyDown,
+      onKeyUp,
+    };
+  },
+});
+</script>
+
+<style scoped>
+.es-key-event-view-css {
+  width: 1920px;
+  height: 1080px;
+}
+</style>

package/rules/.docs/examples/module/key/es-back-hooks.vue

@@ -0,0 +1,30 @@
+<template>
+  <div class="es-sdk-root-css">
+    <s-title-view class="es-sdk-content-title-css" :text="$options.name" />
+    <div class="es-sdk-content-divider-css" />
+    <div class="es-sdk-content-row-css">
+      <s-text-view text="按返回键查看效果" />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent } from "@vue/runtime-core";
+import { useESToast } from "@extscreen/es3-core";
+import { useESRouter } from "@extscreen/es3-router";
+import { onBackPressed } from "@extscreen/es3-vue";
+
+export default defineComponent({
+  name: "返回键",
+  emits: [],
+  setup() {
+    const toast = useESToast();
+    const router = useESRouter();
+
+    onBackPressed(() => {
+      toast.showToast("按了返回键");
+      router.back();
+    });
+  },
+});
+</script>

package/rules/.docs/examples/module/key/es-dispatch-hooks.vue

@@ -0,0 +1,36 @@
+<template>
+  <div class="es-sdk-root-css">
+    <s-title-view class="es-sdk-content-title-css" :text="$options.name" />
+    <div class="es-sdk-content-divider-css" />
+    <div class="es-sdk-content-row-css">
+      <s-text-view :text="textRef" />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { ref } from "vue";
+import { defineComponent } from "@vue/runtime-core";
+import { useESToast } from "@extscreen/es3-core";
+import { onDispatchKeyEvent } from "@extscreen/es3-vue";
+import type { ESKeyEvent } from "@extscreen/es3-core";
+
+export default defineComponent({
+  name: "监听分发按键事件",
+  emits: [],
+  setup() {
+    const toast = useESToast();
+    const textRef = ref<string>("按键查看效果");
+
+    onDispatchKeyEvent((keyEvent: ESKeyEvent) => {
+      toast.showToast(`onKeyDown${JSON.stringify(keyEvent)}`);
+      textRef.value = JSON.stringify(keyEvent);
+    });
+
+    return {
+      textRef,
+      onDispatchKeyEvent,
+    };
+  },
+});
+</script>

package/rules/.docs/examples/module/key/es-event-hooks.vue

@@ -0,0 +1,31 @@
+<template>
+  <div class="es-sdk-root-css">
+    <s-title-view class="es-sdk-content-title-css" :text="$options.name" />
+    <div class="es-sdk-content-divider-css" />
+    <div class="es-sdk-content-row-css">
+      <s-text-view text="按键查看效果" />
+    </div>
+  </div>
+</template>
+<script lang="ts">
+import { defineComponent } from "@vue/runtime-core";
+import { useESToast } from "@extscreen/es3-core";
+import { onKeyDown, onKeyUp } from "@extscreen/es3-vue";
+import type { ESKeyEvent } from "@extscreen/es3-core";
+
+export default defineComponent({
+  name: "按键",
+  emits: [],
+  setup() {
+    const toast = useESToast();
+
+    onKeyDown((keyEvent: ESKeyEvent) => {
+      toast.showToast(`onKeyDown${JSON.stringify(keyEvent)}`);
+    });
+
+    onKeyUp((keyEvent: ESKeyEvent) => {
+      toast.showToast(`onKeyUp${JSON.stringify(keyEvent)}`);
+    });
+  },
+});
+</script>