@quicktvui/ai 1.0.0

package/rules/CLAUDE.md

@@ -0,0 +1,836 @@
+# QuickTVUI - AI 开发指南
+
+> 本文件可放入任何 QuickTVUI 项目根目录，AI 工具会自动加载。
+
+## 🔴 核心准则：权威来源与严禁幻觉 (CRITICAL)
+
+**AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
+
+1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+2.  **官方文档**：https://quicktvui.com (官网 390+ 篇详细文档)
+3.  **核心库示例**：https://github.com/quicktvui/quicktvui.git (Core library + samples)
+4.  **跨平台框架示例**：https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
+5.  **最佳实践应用**：https://github.com/quicktvui/hellotv.git (Complete video app)
+
+**要求：**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
+- **非浏览器与无 HTML 环境**：**本框架绝对不支持标准 HTML 标签（如 `p`, `img`, `a`, `ul`, `li`, `h1` 等），严禁在模板中使用！绝对不支持 `window`、`document` (DOM) 对象或任何 DOM 操作 API。必须使用框架专属标签（如 `qt-text`, `qt-image`）和 Vue `ref`。**
+- **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
+- **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库中搜索同名组件的实际用法。
+
+## 快速创建项目 (Scaffolding)
+
+当用户要求创建全新的 QuickTVUI 快应用项目时，AI **必须**严格遵循以下流程（切勿凭空生成目录和文件）：
+1. **获取模板**：`git clone https://github.com/quicktvui/quicktvui-template.git <项目名>`
+2. **清理 Git**：`cd <项目名> && rm -rf .git`
+3. **更新配置**：读取 `package.json`，修改 `name` 为目标项目名称，重置 `version` 为 `1.0.0`。
+4. **安装依赖**：`yarn install`（推荐）。
+5. **初始化提示**：提醒用户启动服务前，需确认是否已安装全局 CLI `npm install -g @quicktvui/cli@latest` 并执行了 `qui setup` 配置环境（详见 https://quicktvui.com/zh-CN/guide/basic/quick-start.html）。
+
+## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
+
+AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报错，**必须牢记以下框架特性**：
+
+1.  **视频/音频播放架构**：
+    *   **绝对禁止**使用 HTML5 `<video>`、`<audio>` 或 `qt-web-view` 播放媒体。
+    *   **最佳实践**：必须优先使用 **`es-player-manager`**（播放管理器）配合 `es-video-player` 或 `es-audio-player`。`es-player-manager` 负责处理窗口切换（全屏/小窗）、播放列表、焦点逻辑和生命周期，单用底层 player 会导致大量底层逻辑缺失。
+2.  **长列表组件 (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**：
+    *   必须设置 `listenBoundEvent="true"` 并监听 `@item-bind`。
+    *   列表的加载更多模版 `type` **必须**是 `1002`，底线提示 `type` **必须**是 `1003`。
+3.  **零 HTML 与 零 DOM 环境**：
+    *   **这不是浏览器！** 底层是 Hippy 渲染的 Android Native View。
+    *   **禁用标签**：`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>` 等标准 HTML 标签**全部禁用**。只允许使用 `div`, `span` 或 `qt-` 开头的专属标签。
+    *   **禁用 API**：没有 `window`, `document`, `e.preventDefault()`, `alert()`。本地存储必须用 `useESLocalStorage()`，提示必须用 `useESToast()`。
+4.  **CSS 严格子集**：
+    *   不支持任何 CSS 简写（例如 `margin: 10px` 必崩，必须写 `margin-top: 10px; margin-left: 10px;`）。
+    *   不支持 `auto`，不支持 `%`。所有组件**必须显式定义宽高**（`width` / `height` 赋明确的 px 值）。
+
+## 框架概述
+
+QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架。运行在快应用运行环境（Hippy-based）上，Vue 语法开发，渲染为 Android 原生视图。
+
+核心特点：
+
+- Vue 3 Composition API + TypeScript
+- 面向 TV 遥控器交互（焦点系统是核心，没有鼠标/触摸）
+- CSS 子集支持（非标准 Web CSS，有严格限制）
+- 原生组件桥接（Vue 组件 → Android Native View）
+- 设计分辨率 1920x1080，框架自动适配其他 TV 屏幕尺寸
+
+## 示例代码仓库
+
+写代码时参考这三个仓库的实际 Vue 代码风格：
+
+- https://github.com/quicktvui/quicktvui.git — 核心库 + sample 示例
+- https://github.com/quicktvui/es-vue3.git — 跨平台框架 + sample 示例
+- https://github.com/quicktvui/hellotv.git — 完整视频应用项目（最佳实践）
+
+## 在线文档
+
+https://quicktvui.com
+
+---
+
+## ⚠️ 严禁事项（AI 必读，违反任何一条都会导致运行失败）
+
+### 函数命名（框架通过函数名匹配，名字错了就不会被调用）
+
+- 返回键处理必须叫 `onBackPressed`，不能叫 `onBack`、`goBack`、`handleBack` 等任何其他名字
+- 按键事件必须叫 `onKeyDown` / `onKeyUp`，不能叫 `handleKeyDown`、`onKeyPress` 等
+- 生命周期必须叫 `onESCreate` / `onESResume` / `onESDestroy` 等，不能改名
+- 这些函数必须在 `setup()` 中定义，并且必须在 `return { }` 中导出，缺一不可
+
+### 每个页面必须包含的内容（Checklist）
+
+- `onESCreate(params)` — 页面生命周期入口，必须定义并 return
+- `onBackPressed()` — 返回键处理，必须定义并 return（通常调用 `router.back()`）
+- 至少一个元素设置 `:autofocus="true"` — 否则页面打开后没有焦点，遥控器无法操作
+- 页面根元素尺寸 `width: 1920px; height: 1080px`
+
+### 组件名称（必须精确匹配，不能用 HTML 标签替代）
+
+- 图片组件是 `qt-image`，不是 `qt-img`、`<img>`
+- 文字必须用 `<qt-text>` 或 `<span>`，不能用 `<p>`、`<h1>`~`<h6>`、`<label>` 等 HTML 标签
+- 容器用 `<div>`、`<qt-view>`、`<qt-row>`、`<qt-column>`，不能用 `<section>`、`<main>`、`<article>` 等语义标签
+- 按钮用 `<qt-button>` 或可获焦的 `<div>`，不能用 `<button>`
+
+### 强制组件命名规范 (CRITICAL)
+
+**严禁凭空想象或使用标准 Web 标签。必须严格遵守以下映射：**
+
+| 必须使用的标签 | 严禁使用的标签 (Do NOT use)        |
+| -------------- | ---------------------------------- |
+| `<qt-image>`   | `<qt-img>`, `<img>`                |
+| `<qt-text>`    | `<p>`, `<h1>`~`<h6>`, `<label>`    |
+| `<qt-button>`  | `<button>`                         |
+| `<div>`        | `<section>`, `<main>`, `<article>` |
+| `<span>`       | `<p>`, `<label>`                   |
+
+### CSS 规则（这不是标准 Web CSS）
+
+**`<style>` 中用 kebab-case（中划线），`<template>` 标签属性用 camelCase（驼峰）。不要搞反。**
+
+错误写法——不要在 `<style>` 中用驼峰：
+
+```css
+/* 错误！驼峰写法在 <style> 中不生效 */
+.item {
+  backgroundcolor: #333;
+  fontsize: 28px;
+  focusbackgroundcolor: #0066ff;
+  borderradius: 10px;
+}
+```
+
+正确写法——`<style>` 中所有属性用中划线：
+
+```css
+/* 正确——<style> 中一律 kebab-case，包括框架扩展属性 */
+.item {
+  background-color: #333;
+  font-size: 28px;
+  focus-background-color: #0066ff;
+  border-radius: 10px;
+}
+```
+
+正确写法——`<template>` 标签属性用驼峰：
+
+```vue
+<!-- 正确——标签属性用 camelCase -->
+<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
+```
+
+其他 CSS 规则：
+
+- **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
+- **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
+- **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.
+- **CRITICAL: Static styles MUST be in `<style>` (kebab-case), Dynamic styles MUST be in `:style` attributes.**
+- **CRITICAL: NO `-webkit-font-smoothing: antialiased;`**. This is not supported.
+- **CRITICAL: ONLY use `div` and `span` for standard tags.** Do NOT use `p`, `h1-h6`, `section`, etc.
+- **⚠️ 强制要求：默认布局为 `flex-direction: column`**。与 Web 浏览器不同，QuickTVUI 默认就是垂直布局。你几乎不需要写 `display: flex`。
+- 只有本文档"二、样式属性"章节中列出的属性才能使用
+- `display: flex` 和 `flex-direction: column` 是支持的，但它们是默认值，通常不需要写
+- 不要用 `<style scoped>`（在原生渲染中不可靠，直接用 `<style>`）
+- 不支持 `%`、`auto`、`vh`、`vw`、`rem`、`em` 单位，只支持 `px`
+- 不支持 CSS 简写如 `margin: 5px 10px`，必须拆写为 `margin-top: 5px; margin-right: 10px`
+
+### clipChildren / clipPadding（TV 开发必设，不设会导致焦点放大被裁切）
+
+Android 默认裁切超出父容器边界的子元素。TV 端使用 `focusScale` 放大焦点项时，放大部分会被父容器裁切掉，导致显示异常。
+
+**强制规则：**
+- 任何子元素使用了 `focusScale` 的容器，必须设置 `:clipChildren="false"`
+- 列表组件（`qt-list-view`、`qt-waterfall`、`qt-grid-view`）必须同时设置 `:clipChildren="false"` 和 `:clipPadding="false"`
+- 这两个属性写在 `<template>` 中，使用 camelCase
+
+```vue
+<!-- 容器内有焦点放大的子元素 -->
+<div :clipChildren="false">
+  <div :focusable="true" :focusScale="1.1">...</div>
+</div>
+
+<!-- 列表组件必须同时设置两个 -->
+<qt-list-view :clipChildren="false" :clipPadding="false" />
+<qt-waterfall :clipChildren="false" :clipPadding="false" />
+```
+
+### import 来源
+
+- `defineComponent` 从 `vue` 导入（对），不要从 `@vue/runtime-core` 导入
+- 路由用 `useESRouter`，从 `@extscreen/es3-router` 导入
+- 原生模块从 `@extscreen/es3-core` 导入
+
+---
+
+## 一、TV 焦点系统
+
+TV 端没有鼠标/触摸，用户通过遥控器方向键移动焦点、确认键点击。每个页面必须有可获焦元素。
+
+### 基础属性
+
+```vue
+<!-- 可获焦 + 焦点放大 + 焦点边框 -->
+<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
+  <qt-text text="按钮" :duplicateParentState="true" />
+</div>
+
+<!-- 自动获焦（初始化/可见性变化/列表数据重置时触发） -->
+<div :autofocus="true" :focusable="true"></div>
+
+<!-- 请求焦点 -->
+<div :requestFocus="true" :focusable="true"></div>
+
+<!-- 列表自动聚焦到第5项 -->
+<qt-list-view :autofocusPosition="5"></qt-list-view>
+```
+
+### 焦点 CSS 扩展属性
+
+```css
+.item {
+  backgroundcolor: grey;
+  focus-background-color: black; /* 焦点态背景色 */
+  focus-color: white; /* 焦点态文字色 */
+  select-background-color: blue; /* 选中态背景色 */
+  select-color: yellow; /* 选中态文字色 */
+  enable-focus-border: true; /* 启用焦点边框 */
+  focus-border-radius: 5px; /* 焦点边框圆角 */
+  focus-border-width: 3px; /* 焦点边框宽度 */
+  focus-border-color: red; /* 焦点边框颜色 */
+  enable-black-border: true; /* 焦点内部黑色边框 */
+}
+```
+
+### 焦点方向控制
+
+```vue
+<!-- 指定各方向下一个焦点元素 -->
+<div :focusable="true" :nextFocusName="{ down: 'listC', right: 'listB' }" />
+
+<!-- 阻止焦点向某方向移动 -->
+<qt-list-view :blockFocusDirections="['left', 'right']" />
+
+<!-- 禁用子树焦点（如弹窗时禁用主页面） -->
+<div :descendantFocusability="2"></div>
+
+<!-- 根据焦点状态显示/隐藏元素 -->
+<qt-text showOnState="focused" text="焦点时显示" />
+```
+
+### 焦点 API
+
+```javascript
+// 全局默认设置
+Native.callNative("FocusModule", "setDefaultFocusBorderColor", "#ffffff");
+Native.callNative("FocusModule", "setDefaultFocusScale", 1.1);
+Native.callNative("FocusModule", "setDefaultFocusBorderEnable", true);
+Native.callNative("FocusModule", "setDefaultFocusBorderCorner", 5);
+
+// 编程式请求焦点
+ESFocusManager.requestFocus(this.$refs.view);
+```
+
+---
+
+## 二、样式属性（写代码必读）
+
+QuickTVUI 的样式是 Web CSS 的子集，默认 Flexbox 布局，默认 flex-direction: column。
+以下是全部支持的属性，不在此列表中的属性均不支持。
+
+### 基本规则
+
+- 只支持 px 单位（不支持 %、auto、vh/vw/rem/em）
+- 不支持 CSS 简写属性（如 `margin: 5px 10px`，必须拆写）
+- 不支持 CSS 变量 `var(--xxx)`、`!important`
+- 不需要写 `display: flex`（默认就是）
+- 所有元素必须显式指定 width 和 height
+- 文字必须用 `<span>` 或 `<qt-text>` 包裹
+
+### 布局与尺寸
+
+```
+width, height, left, top
+overflow, direction, z-index, visibility
+opacity, transform
+```
+
+### 背景
+
+```
+background-color, background-image
+background-position-x, background-position-y, background-size
+linear-gradient
+```
+
+### 边框
+
+```
+border-color, border-style, border-width, border-radius
+border-top-color, border-top-style, border-top-width
+border-bottom-color, border-bottom-style, border-bottom-width
+border-left-color, border-left-style, border-left-width
+border-right-color, border-right-style, border-right-width
+border-top-left-radius, border-top-right-radius
+border-bottom-left-radius, border-bottom-right-radius
+```
+
+### 阴影
+
+```
+shadow-color, shadow-offset, shadow-offset-x, shadow-offset-y
+shadow-opacity, shadow-radius
+```
+
+### 文字
+
+```
+color, text, text-align, text-align-vertical
+font-size, font-family, font-style, font-weight, fake-bold
+letter-spacing, line-height, line-spacing-extra, line-spacing-multiplier
+number-of-lines, ellipsize-mode, enable-scale, break-strategy
+text-decoration-color, text-decoration-line, text-decoration-style
+text-shadow-color, text-shadow-offset, text-shadow-radius
+vertical-align
+```
+
+### 图片
+
+```
+src, resize-mode, tint-color, tint-color-blend-mode
+cap-insets, default-source
+```
+
+### 焦点态样式
+
+```
+focus-background-color          /* 焦点背景色 */
+focus-color                     /* 焦点文字色 */
+select-color                    /* 选中文字色 */
+select-background-color         /* 选中背景色 */
+enable-focus-border             /* 是否启用焦点边框 */
+focus-border                    /* 焦点边框 */
+focus-border-width              /* 焦点边框宽度 */
+focus-border-color              /* 焦点边框颜色 */
+focus-border-color-string       /* 焦点边框颜色(字符串) */
+focus-border-style              /* 焦点边框样式 */
+focus-border-radius             /* 焦点边框圆角 */
+focus-border-top-left-radius    /* 焦点边框左上圆角 */
+focus-border-top-right-radius   /* 焦点边框右上圆角 */
+focus-border-bottom-right-radius /* 焦点边框右下圆角 */
+focus-border-bottom-left-radius /* 焦点边框左下圆角 */
+focus-border-type               /* 焦点边框类型 */
+enable-black-border             /* 焦点内部黑色边框 */
+```
+
+### 输入与其他
+
+```
+caret-color                   /* 光标颜色 */
+placeholderTextColor          /* 占位文字颜色 */
+blur                          /* 模糊效果 */
+```
+
+### 颜色格式
+
+```
+'#f0f'  '#ff00ff'  '#ff00ff00'(含透明度)
+'rgb(255, 0, 255)'  'rgba(255, 255, 255, 1.0)'
+'hsl(360, 100%, 100%)'  'hsla(360, 100%, 100%, 1.0)'
+'transparent'
+支持 140+ CSS 命名颜色（red, blue, green 等）
+```
+
+---
+
+## 三、页面与路由
+
+### 路由配置
+
+```typescript
+// routes.ts
+const routes = [
+  { path: '/index', name: 'index', component: index },
+  { path: '/detail', name: 'detail', component: detail },
+  { path: '/error', name: 'error', component: error },
+]
+
+// main.ts
+import { createESRouter } from '@extscreen/es3-router'
+const router = createESRouter({ main: 'index', error: 'error', limit: 10, routes })
+const app = createESApp(application, router)
+
+// App.vue
+<template>
+  <div id="root"><es-router-view /></div>
+</template>
+```
+
+### 页面跳转
+
+```typescript
+const router = useESRouter();
+router.push({ name: "detail", params: { id: "123" } }); // 打开页面
+router.back(); // 关闭页面
+```
+
+### 页面生命周期
+
+只有在 routes.ts 中声明的组件才是 Page，子组件不能监听生命周期。生命周期方法不能用 `async`。
+
+```
+onESCreate(params)    → 页面创建，初始化 UI 和资源，params 含启动参数
+onESStart()           → 页面可见但无焦点
+onESResume()          → 页面可见且有焦点（可交互）
+onESPause()           → 页面即将停止
+onESStop()            → 页面完全不可见
+onESDestroy()         → 页面销毁
+onESRestart()         → 页面从停止恢复
+onESNewIntent()       → SingleTask 模式下重复打开同一页面
+```
+
+### 按键事件
+
+```typescript
+// setup() 中定义，必须在 return 中导出
+function onKeyDown(keyEvent: ESKeyEvent) {
+  // keyEvent.keyCode, keyEvent.action, keyEvent.keyRepeat
+}
+function onKeyUp(keyEvent: ESKeyEvent) {}
+function onBackPressed() {
+  router.back();
+}
+return { onKeyDown, onKeyUp, onBackPressed };
+```
+
+常用键值：
+
+- `ES_KEYCODE_DPAD_UP(19)` / `DOWN(20)` / `LEFT(21)` / `RIGHT(22)` — 方向键
+- `ES_KEYCODE_DPAD_CENTER(23)` / `ES_KEYCODE_ENTER(66)` — 确认键
+- `ES_KEYCODE_BACK(4)` — 返回键
+- `ES_KEYCODE_MENU(82)` — 菜单键
+
+---
+
+## 四、常用组件 API
+
+### qt-button
+
+```vue
+<qt-button
+  text="确定"
+  :focusable="true"
+  :focusScale="1.08"
+  size="default"
+  @focus="onFocus"
+  @click="onClick"
+/>
+```
+
+| 属性               | 类型       | 默认值  | 说明                            |
+| ------------------ | ---------- | ------- | ------------------------------- |
+| text               | string     | -       | 按钮文本                        |
+| size               | enum       | default | default/large/medium/small/mini |
+| focusable          | boolean    | true    | 是否可获焦                      |
+| focusScale         | number     | 1.08    | 焦点放大倍数                    |
+| focusBorder        | boolean    | false   | 焦点边框                        |
+| disabled           | boolean    | false   | 禁用                            |
+| round              | boolean    | false   | 圆角                            |
+| icon / focusIcon   | string     | -       | 标准/焦点图标                   |
+| gradientBackground | QTGradient | -       | 渐变背景                        |
+
+Events: `focus(isFocused: boolean)`, `click()`
+
+### qt-text
+
+```vue
+<qt-text
+  text="标题"
+  :fontSize="28"
+  textColor="#ffffff"
+  :focusable="false"
+  :duplicateParentState="true"
+  gravity="center"
+/>
+```
+
+| 属性                                 | 类型    | 说明                           |
+| ------------------------------------ | ------- | ------------------------------ |
+| text                                 | string  | 文字内容                       |
+| fontSize / textSize                  | number  | 字体大小                       |
+| textColor / focusColor / selectColor | string  | 标准/焦点/选中文字颜色         |
+| gravity                              | enum    | 重心(center等)                 |
+| lines / maxLines                     | number  | 行数/最大行数                  |
+| ellipsizeMode                        | number  | 省略模式                       |
+| lineSpacing / lineHeight             | number  | 行间距/行高                    |
+| autoWidth / autoHeight               | boolean | 宽度/高度自适应                |
+| duplicateParentState                 | boolean | 继承父类状态                   |
+| showOnState                          | enum    | normal/focused/selected 时显示 |
+
+Exposes: `setText(text)`, `setTextSize(size)`, `setTextColor(color)`
+
+### qt-image
+
+```vue
+<qt-image
+  src="https://example.com/img.png"
+  :focusable="false"
+  :enableFade="true"
+  :fadeDuration="200"
+/>
+```
+
+| 属性                 | 类型    | 说明         |
+| -------------------- | ------- | ------------ |
+| src                  | string  | 图片地址     |
+| focusable            | boolean | 是否可获焦   |
+| focusScale           | number  | 焦点放大倍数 |
+| enableFocusBorder    | boolean | 焦点边框     |
+| duplicateParentState | boolean | 继承父类状态 |
+| enableFade           | boolean | 淡入效果     |
+| fadeDuration         | number  | 淡入时间(ms) |
+| postDelay            | number  | 延迟加载(ms) |
+| resizeMode           | string  | 缩放模式     |
+
+Events: `load()`, `loadStart()`, `loadEnd(success, image)`, `error()`
+
+### qt-input
+
+```vue
+<qt-input
+  hintText="请输入"
+  :textSize="22"
+  textColor="#ffffff"
+  :strokeWidth="1"
+  strokeColor="#979797"
+  :strokeRadius="16"
+  @onTextChange="onTextChange"
+  @onFocusChanged="onFocusChanged"
+/>
+```
+
+| 属性                           | 类型    | 默认值          | 说明              |
+| ------------------------------ | ------- | --------------- | ----------------- |
+| text                           | string  | -               | 文字内容          |
+| size                           | enum    | small           | 输入框尺寸        |
+| hintText                       | string  | 请输入          | 提示文字          |
+| hintColor                      | string  | #A8A8A8         | 提示文字颜色      |
+| textColor                      | string  | #ffffff         | 输入文字颜色      |
+| textSize                       | number  | 22              | 文字大小          |
+| strokeWidth / focusStrokeWidth | number  | 1/3             | 边框/焦点边框宽度 |
+| strokeColor / focusStrokeColor | string  | #979797/#ffffff | 边框/焦点边框颜色 |
+| strokeRadius                   | number  | 16              | 边框圆角          |
+| disable                        | boolean | false           | 禁用              |
+| mutiline                       | boolean | false           | 多行输入          |
+| maxlength                      | number  | -               | 最大字符数        |
+
+Events: `onFocusChanged`, `onTextChange`
+
+### qt-waterfall（瀑布流列表）
+
+```vue
+<qt-waterfall
+  ref="waterfallRef"
+  :focusable="false"
+  :blockFocusDirections="['left', 'right']"
+  @onItemClick="onItemClick"
+  @onItemFocused="onItemFocused"
+  @onScroll="onScroll"
+/>
+```
+
+核心属性：enablePlaceholder, blockFocusDirections, autofocusPosition, focusMemory, useDiff, listenBoundEvent, makeChildVisibleType, scrollFactor, infiniteMode
+
+Events:
+
+- `onScroll(scrollX, scrollY)` — 滚动
+- `onItemClick(sectionIndex, itemIndex, item)` — 点击
+- `onItemFocused(sectionIndex, itemIndex, isFocused, item)` — 焦点变化
+- `onSectionBind(pageIndex, sectionIndex)` — 板块绑定
+
+### 其他常用组件
+
+| 组件            | 用途         | 关键属性                                             |
+| --------------- | ------------ | ---------------------------------------------------- |
+| qt-card         | 卡片         | load(cardId, useCache), reload(), requestCardFocus() |
+| qt-tabs         | 标签页       | defaultIndex, defaultFocusIndex, itemList            |
+| qt-seek-bar     | 进度条/滑块  | progress, range, seekBarMode, thumbWidth             |
+| qt-dialog       | 弹窗         | 全局弹窗 / 路由弹窗两种模式                          |
+| qt-list-view    | 列表         | autofocusPosition, blockFocusDirections              |
+| qt-grid-view    | 网格         | autofocusPosition                                    |
+| qt-scroll-view  | 滚动容器     | -                                                    |
+| qt-row          | 横向flex容器 | 等同 flex-direction: row                             |
+| qt-column       | 纵向flex容器 | 等同 flex-direction: column                          |
+| qt-view         | 通用容器     | 等同 div                                             |
+| qt-loading      | 加载中       | -                                                    |
+| qt-progress-bar | 进度条       | -                                                    |
+| qt-poster       | 海报图       | -                                                    |
+| qt-collapse     | 折叠面板     | -                                                    |
+| qt-nav-bar      | 导航栏       | -                                                    |
+| qt-web-view     | 网页容器     | -                                                    |
+| qt-animation    | 动画         | alpha/rotation/scale/translation                     |
+
+> 完整组件 API 详见 https://quicktvui.com
+
+---
+
+## 五、原生模块 API
+
+通过全局 `qt` 对象或直接 import 使用。
+
+### 本地存储
+
+```typescript
+import { useESLocalStorage } from "@extscreen/es3-core";
+const storage = useESLocalStorage();
+await storage.putString("key", "value");
+const val = await storage.getString("key", "default");
+// 同理: putInt/getInt, putBoolean/getBoolean, putLong/getLong
+```
+
+### Toast
+
+```typescript
+import { useESToast } from "@extscreen/es3-core";
+const toast = useESToast();
+toast.showToast("提示信息");
+toast.showLongToast("长提示");
+toast.showShortToast("短提示");
+```
+
+### 设备信息
+
+```typescript
+import { useESDevice } from "@extscreen/es3-core";
+const device = useESDevice();
+device.getScreenWidth(); // 屏幕宽度
+device.getScreenHeight(); // 屏幕高度
+device.getIPAddress(); // IP 地址
+device.getDevice(); // 完整设备信息对象
+```
+
+### 网络
+
+```typescript
+import { useESNetwork } from "@extscreen/es3-core";
+const network = useESNetwork();
+network.isNetworkConnected(); // 是否联网
+network.getActiveNetworkInfo(); // 网络信息
+network.addListener(listener); // 监听网络变化
+// 网络类型: NONE(-1), MOBILE(0), WIFI(1), ETHERNET(9)
+```
+
+### 音频控制
+
+```typescript
+import { useESAudio } from "@extscreen/es3-core";
+const audio = useESAudio();
+audio.getStreamMusicVolume(); // 当前音量
+audio.getStreamMusicMaxVolume(); // 最大音量
+audio.setStreamVolume(streamType, volume, flags);
+audio.setStreamMute(streamType, true);
+```
+
+### 事件总线
+
+```typescript
+import { useESEventBus } from "@extscreen/es3-core";
+const eventBus = useESEventBus();
+eventBus.on("eventName", callback); // 监听
+eventBus.once("eventName", callback); // 一次性监听
+eventBus.emit("eventName", ...args); // 发送
+eventBus.off("eventName", callback); // 取消监听
+```
+
+### 亮度控制
+
+```typescript
+import { useESBrightness } from "@extscreen/es3-core";
+const brightness = useESBrightness();
+brightness.getScreenBrightness();
+brightness.changeScreenBrightness(value);
+```
+
+---
+
+## 六、渐变背景（QTGradient）
+
+```typescript
+// 线性渐变示例
+const gradient: QTGradient = {
+  colors: ["#FF0000", "#0000FF"],
+  orientation: 6, // LEFT_RIGHT
+  cornerRadius: 8,
+};
+// orientation: 0=TOP_BOTTOM, 4=BOTTOM_TOP, 6=LEFT_RIGHT, 2=RIGHT_LEFT
+// 使用时 background-color 必须设为 transparent
+```
+
+---
+
+## 七、代码模板
+
+### 最小 TV 页面
+
+```vue
+<template>
+  <div class="page">
+    <div
+      class="item"
+      :focusable="true"
+      :focusScale="1.1"
+      :enableFocusBorder="true"
+      :autofocus="true"
+      @click="onClick"
+    >
+      <qt-text text="Hello TV" :duplicateParentState="true" class="text" />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent } from "vue";
+import { useESRouter } from "@extscreen/es3-router";
+
+export default defineComponent({
+  setup() {
+    const router = useESRouter();
+
+    function onESCreate(params) {
+      // 页面初始化
+    }
+    function onClick() {}
+    function onBackPressed() {
+      router.back();
+    }
+
+    return { onESCreate, onClick, onBackPressed };
+  },
+});
+</script>
+
+<style>
+.page {
+  width: 1920px;
+  height: 1080px;
+  background-color: #000000;
+}
+.item {
+  width: 300px;
+  height: 100px;
+  background-color: #333333;
+  focus-background-color: #0066ff;
+}
+.text {
+  width: 300px;
+  height: 100px;
+  font-size: 28px;
+  color: #ffffff;
+}
+</style>
+```
+
+### 详情页模板（带参数接收 + 返回键处理）
+
+```vue
+<template>
+  <div class="detail-page">
+    <qt-text class="detail-title" :text="title" gravity="center" />
+    <div
+      class="detail-back-btn"
+      :focusable="true"
+      :focusScale="1.1"
+      :enableFocusBorder="true"
+      :autofocus="true"
+      @click="onBackPressed"
+    >
+      <qt-text
+        text="返回"
+        :duplicateParentState="true"
+        class="detail-back-text"
+        gravity="center"
+      />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, ref } from "vue";
+import { useESRouter } from "@extscreen/es3-router";
+
+export default defineComponent({
+  setup() {
+    const router = useESRouter();
+    const title = ref("详情页");
+
+    function onESCreate(params) {
+      // 接收路由参数
+      if (params && params.title) {
+        title.value = params.title;
+      }
+    }
+
+    function onBackPressed() {
+      router.back();
+    }
+
+    return { title, onESCreate, onBackPressed };
+  },
+});
+</script>
+
+<style>
+.detail-page {
+  width: 1920px;
+  height: 1080px;
+  background-color: #1a1a1a;
+  align-items: center;
+  justify-content: center;
+}
+.detail-title {
+  width: 600px;
+  height: 80px;
+  font-size: 48px;
+  color: #ffffff;
+  margin-bottom: 40px;
+}
+.detail-back-btn {
+  width: 240px;
+  height: 70px;
+  background-color: #333333;
+  focus-background-color: #0066ff;
+  border-radius: 35px;
+  align-items: center;
+  justify-content: center;
+}
+.detail-back-text {
+  width: 240px;
+  height: 70px;
+  font-size: 26px;
+  color: #ffffff;
+}
+</style>
+```