@quicktvui/ai 1.0.5 → 1.0.7

package/rules/.source/web/utils/vue/props/runtime.ts

@@ -0,0 +1,129 @@
+import { warn } from "vue";
+import { isObject } from "../../types";
+import { hasOwn } from "../../objects";
+
+import type { PropType } from "vue";
+import type {
+  EpProp,
+  EpPropConvert,
+  EpPropFinalized,
+  EpPropInput,
+  EpPropMergeType,
+  IfEpProp,
+  IfNativePropType,
+  NativePropType,
+} from "./types";
+
+export const epPropKey = "__epPropKey";
+
+export const definePropType = <T>(val: any): PropType<T> => val;
+
+export const isEpProp = (val: unknown): val is EpProp<any, any, any> =>
+  isObject(val) && !!(val as any)[epPropKey];
+
+/**
+ * @description Build prop. It can better optimize prop types
+ * @description 生成 prop，能更好地优化类型
+ * @example
+  // limited options
+  // the type will be PropType<'light' | 'dark'>
+  buildProp({
+    type: String,
+    values: ['light', 'dark'],
+  } as const)
+  * @example
+  // limited options and other types
+  // the type will be PropType<'small' | 'large' | number>
+  buildProp({
+    type: [String, Number],
+    values: ['small', 'large'],
+    validator: (val: unknown): val is number => typeof val === 'number',
+  } as const)
+  @link see more: https://github.com/element-plus/element-plus/pull/3341
+ */
+export const buildProp = <
+  Type = never,
+  Value = never,
+  Validator = never,
+  Default extends EpPropMergeType<Type, Value, Validator> = never,
+  Required extends boolean = false,
+>(
+  prop: EpPropInput<Type, Value, Validator, Default, Required>,
+  key?: string,
+): EpPropFinalized<Type, Value, Validator, Default, Required> => {
+  // filter native prop type and nested prop, e.g `null`, `undefined` (from `buildProps`)
+  if (!isObject(prop) || isEpProp(prop)) return prop as any;
+
+  const { values, required, default: defaultValue, type, validator } = prop;
+
+  const _validator =
+    values || validator
+      ? (val: unknown) => {
+          let valid = false;
+          let allowedValues: unknown[] = [];
+
+          if (values) {
+            allowedValues = Array.from(values);
+            if (hasOwn(prop, "default")) {
+              allowedValues.push(defaultValue);
+            }
+            valid ||= allowedValues.includes(val);
+          }
+          if (validator) valid ||= validator(val);
+
+          if (!valid && allowedValues.length > 0) {
+            const allowValuesText = [...new Set(allowedValues)]
+              .map((value) => JSON.stringify(value))
+              .join(", ");
+            warn(
+              `Invalid prop: validation failed${
+                key ? ` for prop "${key}"` : ""
+              }. Expected one of [${allowValuesText}], got value ${JSON.stringify(val)}.`,
+            );
+          }
+          return valid;
+        }
+      : undefined;
+
+  const epProp: any = {
+    type,
+    required: !!required,
+    validator: _validator,
+    [epPropKey]: true,
+  };
+  if (hasOwn(prop, "default")) epProp.default = defaultValue;
+  return epProp;
+};
+
+export const buildProps = <
+  Props extends Record<
+    string,
+    | { [epPropKey]: true }
+    | NativePropType
+    | EpPropInput<any, any, any, any, any>
+  >,
+>(
+  props: Props,
+): {
+  [K in keyof Props]: IfEpProp<
+    Props[K],
+    Props[K],
+    IfNativePropType<Props[K], Props[K], EpPropConvert<Props[K]>>
+  >;
+} =>
+  fromPairs(
+    Object.entries(props).map(([key, option]) => [
+      key,
+      buildProp(option as any, key),
+    ]),
+  ) as any;
+
+function fromPairs(pairs: [string, any][]): Record<string, any> {
+  return pairs.reduce(
+    (acc, [key, value]) => {
+      acc[key] = value;
+      return acc;
+    },
+    {} as Record<string, any>,
+  );
+}

package/rules/.source/web/utils/vue/props/types.ts

@@ -0,0 +1,165 @@
+import type { epPropKey } from "./runtime";
+import type { ExtractPropTypes, PropType } from "vue";
+import type { IfNever, UnknownToNever, WritableArray } from "./util";
+
+type Value<T> = T[keyof T];
+
+/**
+ * Extract the type of a single prop
+ *
+ * 提取单个 prop 的参数类型
+ *
+ * @example
+ * ExtractPropType<{ type: StringConstructor }> => string | undefined
+ * ExtractPropType<{ type: StringConstructor, required: true }> => string
+ * ExtractPropType<{ type: BooleanConstructor }> => boolean
+ */
+export type ExtractPropType<T extends object> = Value<
+  ExtractPropTypes<{
+    key: T;
+  }>
+>;
+
+/**
+ * Extracts types via `ExtractPropTypes`, accepting `PropType<T>`, `XXXConstructor`, `never`...
+ *
+ * 通过 `ExtractPropTypes` 提取类型，接受 `PropType<T>`、`XXXConstructor`、`never`...
+ *
+ * @example
+ * ResolvePropType<BooleanConstructor> => boolean
+ * ResolvePropType<PropType<T>> => T
+ **/
+export type ResolvePropType<T> = IfNever<
+  T,
+  never,
+  ExtractPropType<{
+    type: WritableArray<T>;
+    required: true;
+  }>
+>;
+
+/**
+ * Merge Type, Value, Validator types
+ * 合并 Type、Value、Validator 的类型
+ *
+ * @example
+ * EpPropMergeType<StringConstructor, '1', 1> =>  1 | "1" // ignores StringConstructor
+ * EpPropMergeType<StringConstructor, never, number> =>  string | number
+ */
+export type EpPropMergeType<Type, Value, Validator> =
+  | IfNever<UnknownToNever<Value>, ResolvePropType<Type>, never>
+  | UnknownToNever<Value>
+  | UnknownToNever<Validator>;
+
+/**
+ * Handling default values for input (constraints)
+ *
+ * 处理输入参数的默认值（约束）
+ */
+export type EpPropInputDefault<
+  Required extends boolean,
+  Default,
+> = Required extends true
+  ? never
+  : Default extends Record<string, unknown> | Array<any>
+    ? () => Default
+    : (() => Default) | Default;
+
+/**
+ * Native prop types, e.g: `BooleanConstructor`, `StringConstructor`, `null`, `undefined`, etc.
+ *
+ * 原生 prop `类型，BooleanConstructor`、`StringConstructor`、`null`、`undefined` 等
+ */
+export type NativePropType =
+  | ((...args: any) => any)
+  | { new (...args: any): any }
+  | undefined
+  | null;
+export type IfNativePropType<T, Y, N> = [T] extends [NativePropType] ? Y : N;
+
+/**
+ * input prop `buildProp` or `buildProps` (constraints)
+ *
+ * prop 输入参数（约束）
+ *
+ * @example
+ * EpPropInput<StringConstructor, 'a', never, never, true>
+ * ⬇️
+ * {
+    type?: StringConstructor | undefined;
+    required?: true | undefined;
+    values?: readonly "a"[] | undefined;
+    validator?: ((val: any) => boolean) | ((val: any) => val is never) | undefined;
+    default?: undefined;
+  }
+ */
+export type EpPropInput<
+  Type,
+  Value,
+  Validator,
+  Default extends EpPropMergeType<Type, Value, Validator>,
+  Required extends boolean,
+> = {
+  type?: Type;
+  required?: Required;
+  values?: readonly Value[];
+  validator?: ((val: any) => val is Validator) | ((val: any) => boolean);
+  default?: EpPropInputDefault<Required, Default>;
+};
+
+/**
+ * output prop `buildProp` or `buildProps`.
+ *
+ * prop 输出参数。
+ *
+ * @example
+ * EpProp<'a', 'b', true>
+ * ⬇️
+ * {
+    readonly type: PropType<"a">;
+    readonly required: true;
+    readonly validator: ((val: unknown) => boolean) | undefined;
+    readonly default: "b";
+    __epPropKey: true;
+  }
+ */
+export type EpProp<Type, Default, Required> = {
+  readonly type: PropType<Type>;
+  readonly required: [Required] extends [true] ? true : false;
+  readonly validator: ((val: unknown) => boolean) | undefined;
+  [epPropKey]: true;
+} & IfNever<Default, unknown, { readonly default: Default }>;
+
+/**
+ * Determine if it is `EpProp`
+ */
+export type IfEpProp<T, Y, N> = T extends { [epPropKey]: true } ? Y : N;
+
+/**
+ * Converting input to output.
+ *
+ * 将输入转换为输出
+ */
+export type EpPropConvert<Input> =
+  Input extends EpPropInput<
+    infer Type,
+    infer Value,
+    infer Validator,
+    any,
+    infer Required
+  >
+    ? EpPropFinalized<Type, Value, Validator, Input["default"], Required>
+    : never;
+
+/**
+ * Finalized conversion output
+ *
+ * 最终转换 EpProp
+ */
+export type EpPropFinalized<Type, Value, Validator, Default, Required> = EpProp<
+  EpPropMergeType<Type, Value, Validator>,
+  UnknownToNever<Default>,
+  Required
+>;
+
+export {};

package/rules/.source/web/utils/vue/props/util.ts

@@ -0,0 +1,10 @@
+export type Writable<T> = { -readonly [P in keyof T]: T[P] };
+export type WritableArray<T> = T extends readonly any[] ? Writable<T> : T;
+
+export type IfNever<T, Y = true, N = false> = [T] extends [never] ? Y : N;
+
+export type IfUnknown<T, Y, N> = [unknown] extends [T] ? Y : N;
+
+export type UnknownToNever<T> = IfUnknown<T, never, T>;
+
+export {};

package/rules/.source/web/utils/vue/typescript.ts

@@ -0,0 +1,9 @@
+import type { AppContext, EmitsOptions, Plugin, SetupContext } from "vue";
+
+export type SFCWithInstall<T> = T & Plugin;
+
+export type SFCInstallWithContext<T> = SFCWithInstall<T> & {
+  _context: AppContext | null;
+};
+
+export type EmitFn<E extends EmitsOptions> = SetupContext<E>["emit"];

package/rules/.source/web/video/index.ts

@@ -0,0 +1,9 @@
+import { withInstall, SFCWithInstall } from "../utils";
+import WebVideo from "./src/video.vue";
+
+export const Video: SFCWithInstall<typeof WebVideo> = withInstall(WebVideo);
+export default Video;
+
+export * from "./src/video";
+
+export type { VideoInstance } from "./src/instance";

package/rules/.source/web/video/src/instance.ts

@@ -0,0 +1,3 @@
+import type Video from "./video.vue";
+
+export type VideoInstance = InstanceType<typeof Video> & unknown;

package/rules/.source/web/video/src/video.ts

@@ -0,0 +1,34 @@
+import { buildProps } from "../../utils";
+import type { ExtractPropTypes } from "vue";
+
+export const videoPreload = ["auto", "metadata", "none"] as const;
+
+export const videoProps = buildProps({
+  width: {
+    type: Number,
+  },
+  height: {
+    type: Number,
+  },
+  muted: Boolean,
+  loop: Boolean,
+  autoplay: Boolean,
+  controls: Boolean,
+  src: {
+    type: String,
+    default: "",
+  },
+  poster: {
+    type: String,
+    default: "",
+  },
+  preload: {
+    type: String,
+    values: videoPreload,
+    default: "auto",
+  },
+} as const);
+export type VideoProps = ExtractPropTypes<typeof videoProps>;
+
+export const videoEmits = {};
+export type VideoEmits = typeof videoEmits;

package/rules/.source/web/video/src/video.vue

@@ -0,0 +1,171 @@
+<template>
+  <div :style="{ width: width, height: height }">
+    <es-video-player
+      ref="videoPlayer"
+      :player-width="width"
+      :player-height="height"
+      @onPlayerPreparing="onPlayerPreparing"
+      @onPlayerPrepared="onPlayerPrepared"
+      @onPlayerPlaying="onPlayerPlaying"
+      @onPlayerInitialized="onPlayerInitialized"
+      @onPlayerStopped="onPlayerStopped"
+      @onPlayerCompleted="onPlayerCompleted"
+    />
+    <img
+      :src="poster"
+      v-if="poster"
+      :visible="visible"
+      :style="{ width: width, height: height, position: 'absolute' }"
+    />
+  </div>
+</template>
+
+<script lang="ts">
+import {
+  computed,
+  defineComponent,
+  onBeforeUnmount,
+  onMounted,
+  onUnmounted,
+  ref,
+  useSlots,
+} from "vue";
+import { videoProps } from "./video";
+import Source from "../../source/src/source.vue";
+import {
+  ESIPlayer,
+  ESMediaSource,
+  ESMediaSourceList,
+  ESPlayerPlayMode,
+} from "@extscreen/es3-player";
+import { ESVideoPlayer } from "@extscreen/es3-video-player";
+
+const TAG = "WebVideo";
+
+export default defineComponent({
+  name: "Video",
+  props: videoProps,
+  emits: [],
+  components: {
+    "es-video-player": ESVideoPlayer,
+  },
+  setup(props, context) {
+    const videoPlayer = ref<ESIPlayer>();
+    const slots = useSlots();
+    const visible = ref<boolean>(true);
+
+    const sources = computed(() => {
+      const nodes = slots.default?.() ?? [];
+      return nodes
+        .filter((node) => node?.type === Source)
+        .map((node) => ({
+          src: node.props?.src ?? "",
+          type: node.props?.type ?? "",
+        }));
+    });
+
+    onMounted(() => {
+      if (props.autoplay) {
+        videoPlayer.value?.initialize();
+      }
+    });
+
+    onBeforeUnmount(() => {
+      videoPlayer.value?.stop();
+      videoPlayer.value?.release();
+    });
+
+    const onPlayerInitialized = (playerType) => {
+      let sourceList: Array<ESMediaSource> = [];
+      if (props.src) {
+        let mediaSource: ESMediaSource = {
+          uri: props.src,
+        };
+        sourceList = [mediaSource];
+      } else {
+        sourceList = sources.value.map((source) => ({
+          uri: source.src,
+          type: source.type,
+        }));
+      }
+      let mediaSourceList: ESMediaSourceList = {
+        index: 0,
+        list: sourceList,
+      };
+      //loop
+      if (props.loop) {
+        videoPlayer.value?.setPlayMode(
+          ESPlayerPlayMode.ES_PLAYER_PLAY_MODE_REPEAT,
+        );
+      } else {
+        videoPlayer.value?.setPlayMode(
+          ESPlayerPlayMode.ES_PLAYER_PLAY_MODE_ONCE,
+        );
+      }
+      //muted
+      if (props.muted) {
+        videoPlayer.value?.setVolume(0);
+      } else {
+        videoPlayer.value?.setVolume(1);
+      }
+      //start
+      videoPlayer.value?.playMediaSourceList(mediaSourceList);
+      videoPlayer.value?.start(0);
+    };
+
+    function onPlayerStopped(): void {
+      visible.value = true;
+    }
+
+    function onPlayerCompleted(): void {
+      visible.value = true;
+    }
+
+    function onPlayerPreparing(): void {}
+
+    function onPlayerPrepared(): void {}
+
+    function onPlayerPlaying(): void {
+      visible.value = false;
+    }
+
+    //加载初始化
+    const play = () => {
+      videoPlayer.value?.initialize();
+    };
+    //开始播放
+    const start = () => {
+      console.log("=========开始播放====start======>>>>");
+      videoPlayer.value?.start(0);
+    };
+    //暂停播放
+    const pause = () => {
+      videoPlayer.value?.pause();
+    };
+    const stop = () => {
+      videoPlayer.value?.stop();
+      videoPlayer.value?.release();
+    };
+    //重新加载媒体
+    const load = () => {
+      videoPlayer.value?.initialize();
+    };
+    return {
+      visible,
+      videoPlayer,
+      sources,
+      play,
+      start,
+      pause,
+      load,
+      stop,
+      onPlayerInitialized,
+      onPlayerPreparing,
+      onPlayerPrepared,
+      onPlayerPlaying,
+      onPlayerStopped,
+      onPlayerCompleted,
+    };
+  },
+});
+</script>

package/rules/.windsurfrules

@@ -6,7 +6,11 @@
 
 **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 & Source (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` and `node_modules/@quicktvui/ai/rules/.source/` directories.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: `.docs/examples/` are verified best practices.
+    *   **Framework Source Code**: `.source/` directory contains the actual framework implementation. **AI SHOULD refer to the source code to resolve ambiguities in documentation.**
+
 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
@@ -50,6 +54,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).
@@ -389,3 +398,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.

package/rules/AGENTS.md

@@ -6,7 +6,11 @@
 
 **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 & Source (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` and `node_modules/@quicktvui/ai/rules/.source/` directories.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: `.docs/examples/` are verified best practices.
+    *   **Framework Source Code**: `.source/` directory contains the actual framework implementation. **AI SHOULD refer to the source code to resolve ambiguities in documentation.**
+
 2.  **Official Docs**: https://quicktvui.com (390+ docs)
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
@@ -50,6 +54,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).
@@ -478,3 +487,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/CLAUDE.md

@@ -6,7 +6,11 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.docs/` 目录中的相关内容。**
+1.  **本地文档、示例与源码 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 和 `node_modules/@quicktvui/ai/rules/.source/` 目录。
+    *   **组件文档**：提供组件、API 及 CSS 的详细定义。
+    *   **示例代码**：`.docs/examples/` 下的 Vue 文件是经过验证的最佳实践。
+    *   **框架源码**：`.source/` 目录下是框架的真实实现逻辑。**当文档模糊时，AI 必须查阅源码以确保 100% 准确性。**
+
 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)
@@ -50,6 +54,11 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
     *   不支持任何 CSS 简写（例如 `margin: 10px` 必崩，必须写 `margin-top: 10px; margin-left: 10px;`）。
     *   不支持 `auto`，不支持 `%`。所有组件**必须显式定义宽高**（`width` / `height` 赋明确的 px 值）。
 
+### 4. 分页加载硬约束 (Pagination Rules)
+*   **`qt-tabs` (Tabs Waterfall)**：必须使用 **`@onTabPageLoadData="onTabPageLoadData"`** 回调。加载数据后，第一页使用 `setPageData`，后续页使用 `addPageData` 追加（或直接 push 到绑定数组）。
+*   **`qt-waterfall` (单瀑布流)**：原生没有 `loadMore` 事件。通常在最后一个板块的 **`@onItemBind`** 中触发下一页请求，或监听 **`@onScrollToBottom`** (若外层容器支持)。
+*   **`qt-list-view` / `qt-grid-view`**：原生支持 `@loadMore="loadMoreFn"`，方法签名：`(pageNo: number) => void`。
+
 ## 框架概述
 
 QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架。运行在快应用运行环境（Hippy-based）上，Vue 语法开发，渲染为 Android 原生视图。