@quicktvui/ai 1.0.4 → 1.0.6

package/rules/.docs/zh-CN/guide/key/dispatch-key-event.md

@@ -11,7 +11,7 @@ lang: zh-CN
 
 :::
 
-## 基础用法
+## 一、普通函数用法
 
 在`setup`中编写`onDispatchKeyEvent`方法，并在`return`中返回此方法。
 
@@ -32,6 +32,39 @@ module/key/es-dispatch
 
 :::
 
+## 二、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
+
+:::
+
+在`setup`中编写`onDispatchKeyEvent`方法，并在`return`中返回此方法。
+
+```ts
+import { onDispatchKeyEvent } from "@extscreen/es3-vue";
+
+onDispatchKeyEvent((keyEvent: ESKeyEvent) => {
+//
+});
+
+```
+
+:::demo
+
+module/key/es-dispatch-hooks
+
+:::
+
 ## API
 
 ### Exposes

package/rules/.docs/zh-CN/guide/key/key-event.md

@@ -5,13 +5,9 @@ lang: zh-CN
 
 # 按键事件
 
-::: warning 注意
-
-仅在[`Page`](/zh-CN/guide/page/type)中使用生效
+## 一、在[页面](/zh-CN/guide/page/type)中使用
 
-:::
-
-## 基础用法
+### 1、普通函数用法
 
 在`setup`中编写 `onKeyDown` 和 `onKeyUp` 方法，并在`return`中返回此方法。
 
@@ -39,6 +35,58 @@ module/key/es-event
 
 :::
 
+### 2、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
+
+:::
+
+```ts
+import { onKeyDown, onKeyUp } from "@extscreen/es3-vue";
+
+onKeyDown((keyEvent: ESKeyEvent) => {
+  //按键被按下
+  //处理业务逻辑
+})
+
+onKeyUp((keyEvent: ESKeyEvent) => {
+  //按键被抬起
+  //处理业务逻辑
+})
+
+```
+
+:::demo
+
+module/key/es-event-hooks
+
+:::
+
+## 二、在组件中使用
+
+在组件标签上监听事件`keydown`、`keyup`。
+
+```vue
+
+<div class='es-key-event-view-css' @keydown='onKeyDown' @keyup='onKeyUp' />
+```
+
+:::demo
+
+module/key/component-event
+
+:::
+
 ## API
 
 ### DataStructure

package/rules/.docs/zh-CN/guide/layout/adapter.md

@@ -14,8 +14,6 @@ lang: zh-CN
 
 ## 长度单位
 
-::: warning 注意： 仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。
-:::
 
 例如：
 

package/rules/.docs/zh-CN/guide/layout/layout.md

@@ -5,14 +5,7 @@ lang: zh-CN
 
 # 布局
 
-* [点击查看支持的布局](/zh-CN/css/overview)
-* [点击查看布局样式相关问题](/zh-CN/guide/faq/layout-style-faq)
-
-::: warning 注意：
-* ***布局中基础组件都需要明确指定组件的宽高尺寸***
-
-* ***仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。***
-:::
+[点击查看 CSS 速查表](/zh-CN/css/cheat-sheet)
 
 ## 盒子模型
 
@@ -28,7 +21,7 @@ lang: zh-CN
 ## 布局（Flex）
 
 默认采用现在移动端最流行的 `Flex` 布局。
-因为仅支持 `Flex` 布局，所以必须手写 `display: flex` 才能生效。
+因为仅支持 `Flex` 布局，所以不需要手写 `display: flex` 即可使用。
 `Flex` 布局与 `Web` 的 `Flex` 类似，它们都旨在提供一个更加有效的方式制定、调整和分布一个容器里的项目布局，即使他们的大小是未知或者是动态的。
 `Flex` 规定了弹性元素如何伸长或缩短，以适应`flex容器`中的可用空间。
 

package/rules/.docs/zh-CN/guide/layout/style.md

@@ -5,27 +5,21 @@ lang: zh-CN
 
 # 样式
 
-* [点击查看支持的样式](/zh-CN/css/overview)
-* [点击查看布局样式相关问题](/zh-CN/guide/faq/layout-style-faq)
+::: tip 提示
 
-::: warning 注意：
-* ***布局中基础组件都需要明确指定组件的宽高尺寸***
+[点击查看 CSS 速查表](/zh-CN/css/cheat-sheet)
 
-* ***仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。***
-  :::
+:::
 
-## 样式主要依靠 css、sass、less 样式来实现。
 
-::: warning 注意：目前仅支持基本的 ID、Class、Tag 选择器，而且可以支持基本的嵌套关系，其余选择器和 scoped 还未支持。
-:::
+## 样式主要依靠 css、sass、less 样式来实现。
 
 ```vue
 
-<div class="div" />
+<div class='div' />
 ```
 
 ```css
-
 .div {
   width: 100px;
   height: 100px;
@@ -38,27 +32,6 @@ lang: zh-CN
 ::: warning 注意：
 
 ***1、不支持的 CSS 样式如下：***
-* `background`
-* `% 百分比尺寸`
-* `auto`
-* `!important`
 
-***2、不支持 CSS 自定义属性（变量）：***
+* `font-family`
 
-```css
-element {
-  background-color: var(--main-bg-color);
-}
-```
-
-***3、不支持 CSS 复合属性写法：***
-
-```css
-element {
-  margin: 5px 10px 20px 15px;
-  padding: 5px 10px;
-  font: oblique bold 16px Helvetica, Arial, Sans-Serif;
-  border: 2px 5px 10px 3px;
-}
-```
-:::

package/rules/.docs/zh-CN/guide/layout/theming.md

@@ -5,150 +5,35 @@ lang: zh-CN
 
 # 自定义主题
 
-QuickTVUI 默认提供一套主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。 但是如果需要大规模替换样式，例如： 将主题颜色从蓝色改为橙色或绿色，也许一个个将其覆盖起来不是一个好主意。
-
-我们提供通过 SCSS 变量的方法来改变样式变量。
-
-`theme-chalk` 使用SCSS编写而成。
-你可以在 [`packages/theme-chalk/src/common/var.scss`](https://github.com/quicktvui/quicktvui/blob/dev/packages/theme-chalk/src/common/var.scss)
-文件中查找SCSS变量。
-
-:::warning
-
-我们使用 sass 模块 ([sass:map](https://sass-lang.com/documentation/values/maps)...) 和 `@use` 来重构所有的 SCSS 变量。 通过对所有 SCSS
-变量使用 `@use` ，解决了由 `@import` 造成的重复输出问题。
-
-> [介绍 Sass 模块 | CSS-TRICKS](https://css-tricks.com/introducing-sass-modules/)
-
-例如，我们使用 `$colors` 作为 map 来保存不同类型的颜色。
-
-今后，我们将为每个组件自定义的变量编写文档。
-你也可以直接查看源代码 [var.scss](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss)
-
-:::
-
-```scss
-$colors: () !default;
-$colors: map.deep-merge(
-    (
-      'white': #ffffff,
-      'black': #000000,
-      'primary': (
-        'base': #409eff,
-      ),
-      'success': (
-        'base': #67c23a,
-      ),
-      'warning': (
-        'base': #e6a23c,
-      ),
-      'danger': (
-        'base': #f56c6c,
-      ),
-      'error': (
-        'base': #f56c6c,
-      ),
-      'info': (
-        'base': #909399,
-      ),
-    ),
-    $colors
-);
-```
-
-### 如何覆盖它？
-
-如果您的项目也使用了 SCSS，可以直接修改 QuickTVUI 的样式变量。 新建一个样式文件，例如
-`./src/styles/quicktvui/index.scss`:
-
-:::warning
-
-您应该使用 `@use 'xxx.scss' as *;` 代替 `@import 'xxx.scss';`.
-
-因为 sass 团队说他们最终会删除 `@import` 语法。
-
-> [Sass: @use](https://sass-lang.com/documentation/at-rules/use) vs [Sass: @import](https://sass-lang.com/documentation/at-rules/import)
-
-:::
-
-```scss
-// styles/quicktvui/index.scss
-/* 只需要重写你需要的即可 */
-@forward 'quicktvui/theme-chalk/src/common/var.scss' with (
-    $bg-color: (
-      'normal': gold,
-      'focus': red,
-      'select': #ffffff,
-    ),
-);
-
-// 如果只是按需导入，则可以忽略以下内容。
-// 如果你想导入所有样式:
-// @use "quicktvui/theme-chalk/src/index.scss" as *;
-```
-
-然后在你的项目入口文件中，导入这个样式文件以替换 QuickTVUI 内置的 CSS：
-
-:::tip
-
-在 `quicktvui scss` 文件之前导入 quicktvui/index.scss 以避免 sass 混合变量的问题，因为我们需要通过你的自定义变量生成 light-x。
-
-:::
-
-创建一个 `quicktvui/index.scss`文件来合并你的变量和 quicktvui 的变量。 （如果你在 TypeScript 中导入了它们，他们将不会被合并）
-
-:::tip
-
-除此以外，你应该将你的 scss 文件与 quicktvui 变量的 scss 文件区分开来。 如果将它们混合在一起，`QuickTVUI` 每次热更新都需要编译大量的 scss 文件，这将会导致编译速度变慢。
-
-:::
+## 第一步：main.ts 中注册主题样式
 
 ```ts
-import { createApp } from 'vue'
-import './src/styles/quicktvui/index.scss'
-import QuickTVUI from 'quicktvui'
-import App from './App.vue'
+const app: ESAppContext = createESApp(application, router, {
+  debug: false
+});
+//主题管理器
+const themeManager = app.theme;
+//注册主题
+themeManager.registerTheme("light", {
+  "--primary-color": "#9890ff",
+  "--text-color": "#000000",
+  "--bg-color": "#ffffff",
+  "--divider-color": "#40b883",
+});
+
+themeManager.registerTheme("dark", {
+  "--primary-color": "#ff4d4f",
+  "--text-color": "red",
+  "--bg-color": "#1f1f1f",
+  "--divider-color": "#91b200",
+});
 
-const app: ESApp = createESApp(App, router)
-app.use(QuickTVUI)
 ```
 
-如果您正在使用 webpack，并且需要在按需导入时自定义主题。
+## 第二步：main.ts 中使用指定的主题样式
 
 ```ts
-// webpack.config.ts
-// use unplugin-quicktvui
-
-import QuickTVUI from 'unplugin-quicktvui/webpack'
-
-export default defineConfig({
-  css: {
-    loaderOptions: {
-      scss: {
-        additionalData: `@use "~/styles/quicktvui/index.scss" as *;`,
-      },
-    },
-  },
-  plugins: [
-    QuickTVUI({
-      useSource: true,
-    }),
-  ],
-  module: {
-    rules: [
-      {
-        test: /\.(sc|c)ss$/,
-        use: [
-          cssLoader,
-          {
-            loader: 'sass-loader',
-            options: {
-              additionalData: `@use "./src/styles/quicktvui/index.scss" as *;`,
-            }
-          }
-        ]
-      },
-    ]
-  },
-})
+themeManager.setTheme("light");
 ```
+
+## 第三步：页面和组件中使用注册的主题的样式的 CSS 变量即可

package/rules/.docs/zh-CN/guide/page/application-lifecycle.md

@@ -13,25 +13,49 @@ import application from './App.vue';
 const app: ESApp = createESApp(application, routerOptions);
 ```
 
+在`App.vue`中监听Application生命周期。
+
+## 基础用法
+
+### 1、普通函数用法
+
 ::: warning 注意：
 
 生命周期方法前面不能添加`async`关键字。
 
 下面的方法使用错误
+
 ```js
-async function onESCreate(){
+async function onESCreate() {
   //
 }
 ```
 
 :::
+:::demo
 
-在`App.vue`中监听Application生命周期。
+module/page/es-app-lifecycle
 
-:::demo ## 基础用法
+:::
 
-module/page/es-app-lifecycle
+### 2、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
 
 :::
 
+:::demo
 
+module/page/es-app-lifecycle-hooks
+
+:::

package/rules/.docs/zh-CN/guide/page/page-lifecycle.md

@@ -7,29 +7,57 @@ lang: zh-CN
 
 ::: warning 注意：
 
-1、声明在路由表 routes.ts 里面的组件才能作为快应用的 Page 。
+声明在路由表 routes.ts 里面的组件才能作为快应用的 Page 。
 
-2、生命周期方法前面不能添加`async`关键字。
+:::
+
+::: tip 提示：Page 生命周期只能触发在 “ 声明在 routes.ts 路由表里面的 Page 组件 ”
+
+* `home.vue`声明在了`routes.ts`，所以`home.vue`是快应用的页面，可以监听生命周期。
+* `home-child-component.vue`没有声明在`routes.ts`，不是快应用的页面，不可以监听生命周期。
+
+<img src="/guide/page/page_lifecycle_warning.png" />
+
+:::
+
+## 一、普通函数用法
+
+::: warning 注意 生命周期方法前面不能添加 async 关键字。
 
 下面的方法使用错误
+
 ```js
-async function onESCreate(){
+async function onESCreate() {
   //
 }
 ```
+
 :::
 
-::: tip 提示：Page 生命周期只能触发在 “ 声明在 routes.ts 路由表里面的 Page 组件 ”
+:::demo
 
-* `home.vue`声明在了`routes.ts`，所以`home.vue`是快应用的页面，可以监听生命周期。
-* `home-child-component.vue`没有声明在`routes.ts`，不是快应用的页面，不可以监听生命周期。
+module/page/es-page-lifecycle
 
-<img src="/guide/page/page_lifecycle_warning.png" />
+:::
+
+## 二、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
 
 :::
 
-:::demo ## 基础用法
+:::demo
 
-module/page/es-page-lifecycle
+module/page/es-page-lifecycle-hooks
 
 :::

package/rules/.docs/zh-CN/guide/page/page-state.md

@@ -23,9 +23,32 @@ lang: zh-CN
 调用顺序为`onESStart()` ==> `onESRestoreInstanceState(savedInstanceState)`
 ==> `onESResume()`
 
-:::demo ## 代码示例
+### 1、普通函数用法
+
+:::demo
 
 module/page/es-page-state
 
 :::
 
+### 2、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
+
+:::
+
+:::demo
+
+module/page/es-page-state-hooks
+
+:::

package/rules/.docs/zh-CN/guide/slot/lifecycle.md

@@ -11,8 +11,34 @@
 ::: warning 注意：onESBind、onESRecycle、onESAttached、onESDetached 生命周期只会在瀑布流里面使用轻卡被调用。
 :::
 
-:::demo ## 生命周期示例
+## 生命周期示例
+
+### 1、普通函数用法
+
+:::demo
 
 guide/slot/lifecycle
 
 :::
+
+### 2、Hooks 函数用法
+
+::: warning 注意
+
+***@extscreen/es3-core" ≥ 1.2.6***
+
+***@extscreen/es3-router ≥ 1.2.3***
+
+***@extscreen/es3-vue ≥ 2.0.11***
+
+***@extscreen/es3-vue-style-parser ≥ 2.0.0***
+
+***@extscreen/es3-vue-css-loader ≥ 2.0.0***
+
+:::
+
+:::demo
+
+guide/slot/lifecycle-hooks
+
+:::

package/rules/.github/copilot-instructions.md

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 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
@@ -38,6 +41,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.
@@ -46,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -454,3 +466,9 @@ export default defineComponent({
 }
 </style>
 ```
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/.windsurfrules

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 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
@@ -38,6 +41,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.
@@ -46,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -385,3 +397,9 @@ export default defineComponent({
 .detail-back-btn { width: 240px; height: 70px; background-color: #333; focus-background-color: #0066FF; border-radius: 35px; }
 .detail-back-text { width: 240px; height: 70px; font-size: 26px; color: #ffffff; }
 </style>
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.