@quicktvui/qtx 0.9.0-alpha.1 → 0.9.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AI_CONTRACT.md CHANGED
@@ -35,13 +35,13 @@ qtx 是 **QuickTVUI 平台之上的扩展库**,不是一套独立的 TV 应用
35
35
  | 宿主工程 | 由 `quicktvui-template` 克隆,不使用通用 Vue 脚手架 | `AGENTS.md`「Project Scaffolding」 |
36
36
  | JS 运行时 | `@extscreen/es3-core >=3.0.0`、`@extscreen/es3-vue >=3.0.0`、`vue >=3.2.0`(`peerDependencies`) | `js/qtx/package.json` |
37
37
  | 常见宿主依赖 | `@extscreen/es3-component`、`@extscreen/es3-router`、`@quicktvui/quicktvui3`、`@quicktvui/ai`(开发期)均为 `^3.0.0` 系列 | `js/demo/package.json` |
38
- | 本包版本 | `0.9.0-alpha.1`,安装时**固定版本号**,不写 `latest` | `js/qtx/package.json` / `CHANGELOG.md` |
39
- | npm 包 | `@quicktvui/qtx`,公开 registry `https://registry.npmjs.org/`(发布时 dist-tag 为 `alpha`,不设 `latest`) | `CHANGELOG.md` 版本路线 |
38
+ | 安装渠道 | `@quicktvui/qtx@alpha`(跟随渠道最新发布);需要可复现时锁定具体版本号 | 发布 SOP / `scripts/verify/online-qtx.mjs` |
39
+ | npm 包 | `@quicktvui/qtx`,公开 registry `https://registry.npmjs.org/`;预发布用 dist-tag `alpha`,`latest` 不随其更新 | `CHANGELOG.md` 版本路线 |
40
40
  | 宿主运行时 | 由 QuickTVUI 平台提供;`qtx-*` 组件的原生能力随运行时就绪,**接入方无需安装或配置额外组件** | 平台模板项目 / `AGENTS.md` |
41
41
  | 播放器 | 本包**不含播放器实现**,播放能力由平台提供,见平台文档的播放器章节 | `CHANGELOG.md` 已知限制 |
42
42
  | 设备 | 一台已 `adb connect` 的 TV / 盒子类设备;多设备时须明确指定 serial。若使用线上快应用引擎验收,可跳过本地运行时安装步骤 | `AGENTS.md`「Run To TV Workflow」 |
43
43
 
44
- `0.9.0-alpha.1` 属于语义化版本的 `0.y.z` 阶段,**允许破坏性变更,不承诺向下兼容**。升级前重新核对组件生成页。
44
+ 0.9 阶段属于语义化版本的 `0.y.z` 阶段,**允许破坏性变更,不承诺向下兼容**。升级前重新核对组件生成页。
45
45
 
46
46
  > **开发者只需关心 Vue 侧**:安装本包、`app.use(qtx)`、按平台模板写页面。原生能力的探测、装载与版本兼容属于平台运行时的内部实现,不在接入范围内,也不需要写进业务代码或工程配置。若页面长时间停在骨架屏或出现诊断信息,属于运行时环境问题,请把日志交给平台侧排查。
47
47
 
@@ -55,8 +55,8 @@ git clone https://github.com/quicktvui/quicktvui-template.git my-tv-app
55
55
  cd my-tv-app && rm -rf .git
56
56
  # 2 修改 package.json 的 name 为 my-tv-app、version 重置为 1.0.0
57
57
  yarn install
58
- # 3 安装 qtx(固定版本)
59
- npm i @quicktvui/qtx@0.9.0-alpha.1
58
+ # 3 安装 qtx(跟随 alpha 渠道最新)
59
+ npm i @quicktvui/qtx@alpha
60
60
  # 4 环境未就绪时先执行
61
61
  quicktvui-ai setup-all-env --project <project-path>
62
62
 
@@ -77,6 +77,44 @@ quicktvui-ai run-dev --project <project-path>
77
77
  5. `run-dev` 到达 runtime launcher 页后,**必须发送一次确认动作**(`adb shell input keyevent 23` 或 `66`)让 runtime 拉取 dev bundle;随后通过 `quicktvui-ai runtime-status`(可用时)或日志确认加载结果,不能停在 launcher 页就宣称完成。
78
78
  6. 排错取 `logcat`、`uiautomator dump` 与构建输出原文,并注明宿主平台版本与 qtx 版本。
79
79
 
80
+ ### 2.1 接入 qtx 构建插件(建好工程后加一次)
81
+
82
+ 这一步决定「页面默认不裁、写 `overflow: hidden` 能裁」。装完 `@quicktvui/qtx` 后加一个文件、改两条脚本;之后页面里不需要写任何 Android 裁切属性。
83
+
84
+ 新建 `scripts/qtx-webpack.config.js`:
85
+
86
+ ```js
87
+ module.exports = {
88
+ module: {
89
+ rules: [
90
+ {
91
+ // 正则必须带 i 后缀:build-tools 按 test 字符串合并同规则,
92
+ // 不带 i 会与内置 vue-loader 规则合并,本 loader 将拿到拆分后的 JS 而失效。
93
+ test: /\.vue$/i,
94
+ enforce: 'pre',
95
+ use: [require.resolve('@quicktvui/qtx/plugin/webpack.cjs')],
96
+ },
97
+ ],
98
+ },
99
+ };
100
+ ```
101
+
102
+ 把 `package.json` 的两条脚本加上 `-c`:
103
+
104
+ ```json
105
+ "dev": "qt-dev android -c scripts/qtx-webpack.config.js",
106
+ "build:android": "qt-build android -c scripts/qtx-webpack.config.js"
107
+ ```
108
+
109
+ 自建 Vite 工程不需要上面两个文件,在 `vite.config.ts` 里加一行即可:
110
+
111
+ ```ts
112
+ import { qtx } from '@quicktvui/qtx/plugin/vite.mjs'
113
+ export default defineConfig({ plugins: [vue(), qtx()] })
114
+ ```
115
+
116
+ 页面写法只有两条:不写裁切属性 = 不裁;写 `overflow="hidden"` 并用 `:width` / `:height` 显式声明尺寸 = 裁。自检:构建产物中页面层 `div` 应带 `:clipChildren="false"`,写 `overflow: hidden` 的容器应带 `:clipBounds`;没有就说明插件没挂上。
117
+
80
118
  ## 3. 完整工程(可逐字复制)
81
119
 
82
120
  目录结构:
@@ -440,7 +478,7 @@ export default defineComponent({
440
478
  | 写法 | 判定 | 依据 |
441
479
  | --- | --- | --- |
442
480
  | 用 `createApp(App)` + `vue-router` 搭工程 | 错误 | 宿主使用 `createESApp` + `createESRouter`,见 `src/main.ts` |
443
- | `npm i @quicktvui/qtx` 不带版本 | 不推荐 | `0.9.0-alpha.1` 不设 `latest`,alpha 阶段允许破坏性变更 |
481
+ | `npm i @quicktvui/qtx` 不带版本 | 不推荐 | 等于 `@latest`,不随 `--tag alpha` 发布更新;改用 `@alpha` |
444
482
  | 示例里 `:items="rows"` 但 `rows` 未定义 | 错误 | `rows` 必须是 `setup()` 中定义并返回的响应式数组 |
445
483
  | 依据 `qt-list-view` 文档给 `qtx-list` 传属性 | 错误 | 平台资料不含 `qtx-*` 定义,参数查组件生成页 |
446
484
  | 认为 `div` 完全禁用 | 错误 | 平台允许 `div` / `span` 容器,禁用的是标准 HTML 语义标签 |
@@ -450,7 +488,7 @@ export default defineComponent({
450
488
 
451
489
  ## 6. 验收清单
452
490
 
453
- - [ ] `yarn install` 与 `npm i @quicktvui/qtx@0.9.0-alpha.1` 均成功,宿主依赖版本满足 `peerDependencies`。
491
+ - [ ] `yarn install` 与 `npm i @quicktvui/qtx@alpha` 均成功,宿主依赖版本满足 `peerDependencies`。
454
492
  - [ ] `quicktvui-ai doctor` / `setup-vue-env` / `setup-android-env` 通过,`adb devices` 能看到目标。
455
493
  - [ ] `run-dev` 到达 launcher 后已发送确认键,runtime 状态或日志显示 bundle 已加载。
456
494
  - [ ] 首页渲染 6 行数据,遥控器上下左右能移动焦点,首屏存在一个自动获焦节点。
@@ -460,7 +498,7 @@ export default defineComponent({
460
498
 
461
499
  ## 7. 版本与资料边界
462
500
 
463
- - 当前版本 `0.9.0-alpha.1`。完整变更清单由维护方随发布说明提供;包内 `README.md` 内联了 alpha 摘要。**源码仓库为私有维护仓库,不对外公开,接入方无需访问**。
501
+ - 当前发布渠道 `alpha`;具体版本见包内 `package.json` 与发布说明。包内 `README.md` 内联了 alpha 摘要。**源码仓库为私有维护仓库,不对外公开,接入方无需访问**。
464
502
  - 本包 `files` 只含 `dist`、`README.md` 与 `AI_CONTRACT.md`;`docs-site/`、`AGENTS.md`、`.docs/` 均不随包分发,文档站暂无在线部署地址。
465
503
  - `docs/qtx-list-guide.md`、`docs/qtx-tabs-guide.md`、`docs/ai-guide/README.md` 与 `docs/components/*.md` 均为历史归档或占位产物,**不得**用于推断属性名与事件名。
466
504
  - 需要 `qtx-*` 参数时以本包 `dist` 内的类型声明为准;需要平台 `qt-*` 参数时查平台官网或 `@quicktvui/ai` 的 `.docs`。
package/README.md CHANGED
@@ -4,19 +4,19 @@
4
4
 
5
5
  QuickTVUI 官方扩展库:Vue 3 侧的 `qtx-*` 原生高性能组件封装,原生能力由 QuickTVUI 平台运行时提供。
6
6
 
7
- > 面向整个扩展库的源码级文档,不只是某一个组件
7
+ > 用 qtx 开发 TV 应用所需的组件、页面与设计规范
8
8
 
9
- > 当前版本 **`0.9.0-alpha.1`**(0.9 预发布阶段):用于第三方在真实 TV 场景试用并反馈。**本阶段允许破坏性变更,不承诺向下兼容**;先用一个真实项目完整验证后再发 `1.0.0`。
9
+ > 当前版本 **`0.9.0-alpha.3`**(0.9 预发布阶段):用于第三方在真实 TV 场景试用并反馈。**本阶段允许破坏性变更,不承诺向下兼容**;先用一个真实项目完整验证后再发 `1.0.0`。
10
10
 
11
11
  > **给 AI / 接入方**:先读同包内 `AI_CONTRACT.md`(《给 AI 的接入契约》)。它给出宿主依赖、真实脚手架命令、完整 `main.ts` + `App.vue` + 双页路由示例与装机链路;仅凭包内两份 md 可完成 qtx 接入与最小双页应用,平台原生 `qt-*` 组件 / 播放器 / 高级路由能力仍需读平台资料(见下)。qtx 是 **QuickTVUI 平台之上的扩展库**:渲染器、焦点、按键、路由、生命周期与播放器由平台提供,平台前置资料(项目根 `AGENTS.md` 与 `node_modules/@quicktvui/ai/rules/.docs/`)由平台模板项目提供,**不随本 npm 包分发**。
12
12
 
13
13
  ## 安装
14
14
 
15
15
  ```bash
16
- npm i @quicktvui/qtx@0.9.0-alpha.1
16
+ npm i @quicktvui/qtx@alpha
17
17
  ```
18
18
 
19
- 不要省略版本号:alpha 包只以 npm dist-tag `alpha` 分发,不设 `latest`;`0.y.z` 阶段允许破坏性变更。
19
+ `@alpha` 跟随 alpha 渠道最新发布;`npm i @quicktvui/qtx` 等于 `@latest`,不会随 `--tag alpha` 发布更新,可能拿到滞后版本。需要可复现构建时锁定具体版本号。`0.y.z` 阶段允许破坏性变更。
20
20
 
21
21
  | 依赖 | 版本 / 坐标 | 说明 |
22
22
  | --- | --- | --- |
@@ -80,14 +80,15 @@ export default defineComponent({
80
80
  - `<qtx-button>` 的确认动作用 `@click`(Vue attrs 透传到原生 onClick,真机 demo 已使用);生成 API 表登记的 `@onButtonCustomEvent` 是另一条自定义事件通道。其他 `qtx-*` 组件按各自生成页的事件表接线。
81
81
  - 宿主运行时未就绪时组件显示占位,就绪后自动渲染;业务代码无需参与原生能力的装载与兼容判断。
82
82
 
83
- ## 组件清单(21)
83
+ ## 组件清单(22)
84
84
 
85
85
  由 `js/qtx/src/index.ts` 的导出清单生成,不是手写清单;仅列出对外公开的组件。
86
86
 
87
- ### 原生桥接组件(17)
87
+ ### 原生桥接组件(18)
88
88
 
89
89
  - `<qtx-app-icon>` 应用图标卡片
90
90
  - `<qtx-button>` 按钮
91
+ - `<qtx-channel-nav>` 频道导航
91
92
  - `<qtx-checkbox>` 复选框
92
93
  - `<qtx-collapse-menu-group>` 折叠菜单分组
93
94
  - `<qtx-collapse-menu-list>` 折叠菜单列表
@@ -0,0 +1,10 @@
1
+ import type { QtxFileMethods } from './file';
2
+ /** qtx.file 命名空间(懒引导 + 直连原生) */
3
+ export declare const file: import("../core/capabilities").QtxCapabilityReservedMethods & QtxFileMethods;
4
+ /** qtx.file 事件名常量(EventBus 订阅用) */
5
+ export declare const QTX_FILE_EVENTS: {
6
+ /** USB / 存储卷热插拔(系统广播监听,引擎销毁注销);payload:{ volume: QtxFileVolume, action: 'mounted'|'unmounted', timestamp: number }(volume 结构同 getVolumes;REMOVED/BAD_REMOVAL/EJECT 映射为 unmounted) */
7
+ readonly volumeChanged: "onQtxVolumeChanged";
8
+ /** copy/move 任务进度与终态(协议 §5『完整文件传输进度走事件』;payload 必带 taskId);payload:{ taskId: string, op: 'copy'|'move', state: 'running'|'done'|'error'|'cancelled', src: string, dst: string, bytesDone: number, bytesTotal: number, speedBps: number, elapsedMs?: number, durationMs?: number, fastPath?: boolean, error?: {code, message} }(running 节流 ≥150ms 且 ≥2%;speedBps 原生计算 JS 不再除时间;fastPath=true 为同卷 move rename 快路径) */
9
+ readonly task: "onQtxFileTask";
10
+ };
@@ -0,0 +1,48 @@
1
+ import type { QtxChannelNavProps, QtxChannelNavState, QtxChannelNavItem, QtxChannelNavEventPayload, QtxChannelNavScrollPayload } from './types';
2
+ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<QtxChannelNavProps>>, {
3
+ getNativeNode(): any;
4
+ setActive(key: string): void;
5
+ getActiveKey(): Promise<string>;
6
+ getFocusedKey(): Promise<string>;
7
+ requestFocus(): Promise<string>;
8
+ clearFocus(): Promise<string>;
9
+ getState(): Promise<QtxChannelNavState>;
10
+ scrollToKey(key: string): Promise<string>;
11
+ updateItems(items: QtxChannelNavItem[]): Promise<string>;
12
+ setOrientation(orientation: string): Promise<string>;
13
+ setStyle(tokens: Partial<QtxChannelNavProps>): Promise<string>;
14
+ getItemCount(): Promise<number>;
15
+ getItemAt(index: number): Promise<QtxChannelNavItem>;
16
+ getScrollState(): Promise<QtxChannelNavState>;
17
+ }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
18
+ change: (key: string, payload: QtxChannelNavEventPayload) => void;
19
+ "update:active": (key: string) => void;
20
+ focus: (key: string, payload: QtxChannelNavEventPayload) => void;
21
+ blur: (key: string, payload: QtxChannelNavEventPayload) => void;
22
+ longClick: (key: string, payload: QtxChannelNavEventPayload) => void;
23
+ scroll: (payload: QtxChannelNavScrollPayload) => void;
24
+ }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<QtxChannelNavProps>>> & Readonly<{
25
+ onBlur?: ((key: string, payload: QtxChannelNavEventPayload) => any) | undefined;
26
+ onChange?: ((key: string, payload: QtxChannelNavEventPayload) => any) | undefined;
27
+ onFocus?: ((key: string, payload: QtxChannelNavEventPayload) => any) | undefined;
28
+ onScroll?: ((payload: QtxChannelNavScrollPayload) => any) | undefined;
29
+ "onUpdate:active"?: ((key: string) => any) | undefined;
30
+ onLongClick?: ((key: string, payload: QtxChannelNavEventPayload) => any) | undefined;
31
+ }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>, {
32
+ default?(_: {}): any;
33
+ }>;
34
+ export default _default;
35
+ type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
36
+ type __VLS_TypePropsToRuntimeProps<T> = {
37
+ [K in keyof T]-?: {} extends Pick<T, K> ? {
38
+ type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
39
+ } : {
40
+ type: import('vue').PropType<T[K]>;
41
+ required: true;
42
+ };
43
+ };
44
+ type __VLS_WithTemplateSlots<T, S> = T & {
45
+ new (): {
46
+ $slots: S;
47
+ };
48
+ };
@@ -0,0 +1,133 @@
1
+ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
2
+ items?: any;
3
+ active?: string | undefined;
4
+ orientation?: string | undefined;
5
+ itemWidth?: any;
6
+ itemHeight?: any;
7
+ gap?: any;
8
+ paddingLeft?: any;
9
+ paddingTop?: any;
10
+ paddingRight?: any;
11
+ paddingBottom?: any;
12
+ reverseLayout?: boolean | undefined;
13
+ iconPosition?: string | undefined;
14
+ itemPadding?: any;
15
+ iconMargin?: any;
16
+ focusedKey?: string | undefined;
17
+ gravity?: string | undefined;
18
+ align?: string | undefined;
19
+ crossAlign?: string | undefined;
20
+ fontSize?: any;
21
+ borderRadius?: any;
22
+ iconSize?: any;
23
+ focusBorderWidth?: any;
24
+ normalBg?: string | undefined;
25
+ normalText?: string | undefined;
26
+ focusBg?: string | undefined;
27
+ focusText?: string | undefined;
28
+ focusBorderColor?: string | undefined;
29
+ selectedBg?: string | undefined;
30
+ selectedText?: string | undefined;
31
+ disabledBg?: string | undefined;
32
+ disabledText?: string | undefined;
33
+ indicator?: string | undefined;
34
+ indicatorColor?: string | undefined;
35
+ indicatorSize?: any;
36
+ badgeBg?: string | undefined;
37
+ badgeText?: string | undefined;
38
+ scrollMode?: string | undefined;
39
+ smoothScroll?: boolean | undefined;
40
+ focusable?: boolean | undefined;
41
+ selectOnFocus?: boolean | undefined;
42
+ focusMemory?: boolean | undefined;
43
+ defaultFocusKey?: string | undefined;
44
+ maxPoolSize?: any;
45
+ }>>, {
46
+ getNativeNode: () => any;
47
+ setActive: (...args: any[]) => void;
48
+ getActiveKey: (...args: any[]) => void;
49
+ getFocusedKey: (...args: any[]) => void;
50
+ requestFocus: (...args: any[]) => void;
51
+ clearFocus: (...args: any[]) => void;
52
+ getState: (...args: any[]) => void;
53
+ scrollToKey: (...args: any[]) => void;
54
+ updateItems: (...args: any[]) => void;
55
+ setOrientation: (...args: any[]) => void;
56
+ setStyle: (...args: any[]) => void;
57
+ getItemCount: (...args: any[]) => void;
58
+ getItemAt: (...args: any[]) => void;
59
+ getScrollState: (...args: any[]) => void;
60
+ }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
61
+ onChange: (payload?: any) => void;
62
+ onFocus: (payload?: any) => void;
63
+ onBlur: (payload?: any) => void;
64
+ onLongClick: (payload?: any) => void;
65
+ onScroll: (payload?: any) => void;
66
+ }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
67
+ items?: any;
68
+ active?: string | undefined;
69
+ orientation?: string | undefined;
70
+ itemWidth?: any;
71
+ itemHeight?: any;
72
+ gap?: any;
73
+ paddingLeft?: any;
74
+ paddingTop?: any;
75
+ paddingRight?: any;
76
+ paddingBottom?: any;
77
+ reverseLayout?: boolean | undefined;
78
+ iconPosition?: string | undefined;
79
+ itemPadding?: any;
80
+ iconMargin?: any;
81
+ focusedKey?: string | undefined;
82
+ gravity?: string | undefined;
83
+ align?: string | undefined;
84
+ crossAlign?: string | undefined;
85
+ fontSize?: any;
86
+ borderRadius?: any;
87
+ iconSize?: any;
88
+ focusBorderWidth?: any;
89
+ normalBg?: string | undefined;
90
+ normalText?: string | undefined;
91
+ focusBg?: string | undefined;
92
+ focusText?: string | undefined;
93
+ focusBorderColor?: string | undefined;
94
+ selectedBg?: string | undefined;
95
+ selectedText?: string | undefined;
96
+ disabledBg?: string | undefined;
97
+ disabledText?: string | undefined;
98
+ indicator?: string | undefined;
99
+ indicatorColor?: string | undefined;
100
+ indicatorSize?: any;
101
+ badgeBg?: string | undefined;
102
+ badgeText?: string | undefined;
103
+ scrollMode?: string | undefined;
104
+ smoothScroll?: boolean | undefined;
105
+ focusable?: boolean | undefined;
106
+ selectOnFocus?: boolean | undefined;
107
+ focusMemory?: boolean | undefined;
108
+ defaultFocusKey?: string | undefined;
109
+ maxPoolSize?: any;
110
+ }>>> & Readonly<{
111
+ onOnBlur?: ((payload?: any) => any) | undefined;
112
+ onOnChange?: ((payload?: any) => any) | undefined;
113
+ onOnFocus?: ((payload?: any) => any) | undefined;
114
+ onOnScroll?: ((payload?: any) => any) | undefined;
115
+ onOnLongClick?: ((payload?: any) => any) | undefined;
116
+ }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>, {
117
+ default?(_: {}): any;
118
+ }>;
119
+ export default _default;
120
+ type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
121
+ type __VLS_TypePropsToRuntimeProps<T> = {
122
+ [K in keyof T]-?: {} extends Pick<T, K> ? {
123
+ type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
124
+ } : {
125
+ type: import('vue').PropType<T[K]>;
126
+ required: true;
127
+ };
128
+ };
129
+ type __VLS_WithTemplateSlots<T, S> = T & {
130
+ new (): {
131
+ $slots: S;
132
+ };
133
+ };
@@ -0,0 +1,13 @@
1
+ import type { App } from 'vue';
2
+ import QtxChannelNav from './QtxChannelNav.vue';
3
+ export declare const QtxChannelNavPlugin: {
4
+ install: (app: App) => void;
5
+ };
6
+ export { QtxChannelNav };
7
+ export default QtxChannelNavPlugin;
8
+ declare module 'vue' {
9
+ interface GlobalComponents {
10
+ QtxChannelNav: typeof QtxChannelNav;
11
+ 'qtx-channel-nav': typeof QtxChannelNav;
12
+ }
13
+ }
@@ -0,0 +1,242 @@
1
+ /**
2
+ * @description 频道导航的单项数据。items 数组顺序即遥控器遍历顺序。
3
+ */
4
+ export interface QtxChannelNavItem {
5
+ /** 唯一标识,与 qtx-tabs 的 tabKey / active 同源 */
6
+ key: string;
7
+ /** 频道名 */
8
+ label: string;
9
+ /** 可选图标地址,走站内 SVG 加载通道;省略时只显示文字 */
10
+ icon?: string;
11
+ /** 可选角标文本,如数字或「新」;省略时不显示 */
12
+ badge?: string;
13
+ /** 业务透传数据,原样随 change / focus / longClick 事件回传 */
14
+ payload?: any;
15
+ /** 禁用项:不可获焦、不可点击、视觉灰化 */
16
+ disabled?: boolean;
17
+ }
18
+ /**
19
+ * @description 频道导航组件属性。渲染、复用、三态与焦点滚动全部由 native RecyclerView 完成;
20
+ * 所有视觉与行为 token 均有默认值,最简用法只需 items / active / @change。
21
+ */
22
+ export interface QtxChannelNavProps {
23
+ /** 频道数据,默认 [];数组顺序即遥控器遍历顺序 */
24
+ items?: QtxChannelNavItem[];
25
+ /** 当前选中频道 key,默认 '';受控属性,组件不自行修改 */
26
+ active?: string;
27
+ /** 布局方向,默认 horizontal(顶部横排),vertical 为左侧竖排 */
28
+ orientation?: 'horizontal' | 'vertical' | string;
29
+ /** 单项宽度(px),默认 160 */
30
+ itemWidth?: number;
31
+ /** 单项高度(px),默认 72 */
32
+ itemHeight?: number;
33
+ /** 项间距(px),默认 12 */
34
+ gap?: number;
35
+ /** 频道项内容区内边距(px),四边统一;避免图标/文字贴着 item 边缘,默认 16 */
36
+ itemPadding?: number;
37
+ /** 图标与频道文字之间的间距(px),随 iconPosition 作用于对应方向,默认 12 */
38
+ iconMargin?: number;
39
+ /** 受控焦点频道 key;ES 把方向键派发给页面 onKeyDown,由上层回写此属性驱动焦点态 */
40
+ focusedKey?: string;
41
+ /** 栏内左内边距(px),默认 0 */
42
+ paddingLeft?: number;
43
+ /** 栏内上内边距(px),默认 0 */
44
+ paddingTop?: number;
45
+ /** 栏内右内边距(px),默认 0 */
46
+ paddingRight?: number;
47
+ /** 栏内下内边距(px),默认 0 */
48
+ paddingBottom?: number;
49
+ /** 反转排列方向:横排从右往左、竖排从下往上,默认 false */
50
+ reverseLayout?: boolean;
51
+ /** 图标相对文字的位置 left / top / right / bottom,默认 left */
52
+ iconPosition?: 'left' | 'top' | 'right' | 'bottom' | string;
53
+ /** 频道文字项内对齐 start / center / end,默认 center(只作用于项内文字,不移动频道序列) */
54
+ gravity?: 'start' | 'center' | 'end' | string;
55
+ /** 频道序列在整栏内的主轴对齐;横排=水平轴、竖排=垂直轴,默认 start */
56
+ align?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | string;
57
+ /** 频道项在整栏内的交叉轴对齐;横排=垂直轴、竖排=水平轴,默认 start */
58
+ crossAlign?: 'start' | 'center' | 'end' | string;
59
+ /** 整栏宽度(px);显式声明可避免宿主布局把容器压成 0,也是 align 计算的基准 */
60
+ width?: number | string;
61
+ /** 整栏高度(px);显式声明可避免宿主布局把容器压成 0,也是 crossAlign 计算的基准 */
62
+ height?: number | string;
63
+ /** 频道文字字号(px),默认 28 */
64
+ fontSize?: number;
65
+ /** 单项圆角(px),默认 36 */
66
+ borderRadius?: number;
67
+ /** 图标尺寸(px),默认 32;设为 0 隐藏图标 */
68
+ iconSize?: number;
69
+ /** 焦点描边宽度(px),默认 3;设为 0 关闭描边 */
70
+ focusBorderWidth?: number;
71
+ /** 普通态底色,默认 #1B2530 */
72
+ normalBg?: string;
73
+ /** 普通态文字色,默认 #A9B8C7 */
74
+ normalText?: string;
75
+ /** 未选中项获焦时的底色,默认 #33465A */
76
+ focusBg?: string;
77
+ /** 获焦态文字色,默认 #FFFFFF */
78
+ focusText?: string;
79
+ /** 焦点描边颜色,默认 #FFFFFF;描边与选中底色正交叠加 */
80
+ focusBorderColor?: string;
81
+ /** 选中态底色,默认 #FF7A1A */
82
+ selectedBg?: string;
83
+ /** 选中态文字色,默认 #FFFFFF */
84
+ selectedText?: string;
85
+ /** 禁用项底色,默认 #141A22 */
86
+ disabledBg?: string;
87
+ /** 禁用项文字色,默认 #5A6675 */
88
+ disabledText?: string;
89
+ /** 选中指示器 none / underline / bar,默认 none */
90
+ indicator?: 'none' | 'underline' | 'bar' | string;
91
+ /** 选中指示器颜色,默认 #FFD479 */
92
+ indicatorColor?: string;
93
+ /** 选中指示器厚度(px),默认 6 */
94
+ indicatorSize?: number;
95
+ /** 角标底色,默认 #E5484D */
96
+ badgeBg?: string;
97
+ /** 角标文字色,默认 #FFFFFF */
98
+ badgeText?: string;
99
+ /** 滚动策略 center / edge / none,默认 center(焦点项自动居中) */
100
+ scrollMode?: 'center' | 'edge' | 'none' | string;
101
+ /** 命令式滚动是否使用平滑动画,默认 true */
102
+ smoothScroll?: boolean;
103
+ /** 频道项是否可获焦,默认 true;关闭后只展示不参与遥控器焦点 */
104
+ focusable?: boolean;
105
+ /** 焦点移动即切换选中频道,默认 false;开启后仍派发 change */
106
+ selectOnFocus?: boolean;
107
+ /** 数据更新后恢复之前的焦点项,默认 true,避免写操作后丢焦点 */
108
+ focusMemory?: boolean;
109
+ /** 首次进入时默认获焦的频道 key,默认 ''(回退到当前 active) */
110
+ defaultFocusKey?: string;
111
+ /** 复用池容量上限(1~128),默认 16;长列表调大可减少创建次数 */
112
+ maxPoolSize?: number;
113
+ }
114
+ /**
115
+ * @description 细粒度事件的完整载荷。事件第一个参数仍是 key 字符串,
116
+ * 便于 @change="current = $event";第二个参数才是结构化载荷。
117
+ */
118
+ export interface QtxChannelNavEventPayload {
119
+ /** 触发事件的频道 key */
120
+ key: string;
121
+ /** 频道在 items 中的位置 */
122
+ position: number;
123
+ /** 仅 change 事件携带:切换前的选中 key */
124
+ previous?: string;
125
+ /** 触发事件的频道项快照 */
126
+ item?: QtxChannelNavItem;
127
+ }
128
+ /** 滚动事件的载荷:首个可见项变化时触发 */
129
+ export interface QtxChannelNavScrollPayload {
130
+ /** 首个可见项位置 */
131
+ first: number;
132
+ /** 最后一个可见项位置 */
133
+ last: number;
134
+ }
135
+ /**
136
+ * @description 频道导航对外事件。事件首参为 key 字符串,第二参为完整载荷;
137
+ * 组件受控,change 与 update:active 只回传 key,不修改 active。
138
+ */
139
+ export interface QtxChannelNavEvents {
140
+ /** 确认某个频道时回传该频道 key 与完整载荷 */
141
+ change: (key: string, payload: QtxChannelNavEventPayload) => void;
142
+ /** v-model:active 语法糖的回传事件,载荷与 change 的 key 一致 */
143
+ 'update:active': (key: string) => void;
144
+ /** 焦点落到某个频道 */
145
+ focus: (key: string, payload: QtxChannelNavEventPayload) => void;
146
+ /** 焦点离开某个频道 */
147
+ blur: (key: string, payload: QtxChannelNavEventPayload) => void;
148
+ /** 长按某个频道 */
149
+ longClick: (key: string, payload: QtxChannelNavEventPayload) => void;
150
+ /** 首个可见项变化 */
151
+ scroll: (payload: QtxChannelNavScrollPayload) => void;
152
+ }
153
+ /** 组件对外事件名清单,供生成器抽取 API 表与下游校验使用 */
154
+ export declare const QTX_CHANNEL_NAV_EVENTS: readonly ["change", "update:active", "focus", "blur", "longClick", "scroll"];
155
+ /**
156
+ * @description getState() 返回的状态快照,可直接用于排查焦点、复用与滚动状态。
157
+ */
158
+ export interface QtxChannelNavState {
159
+ /** 当前选中频道 key */
160
+ active: string;
161
+ /** 当前获焦频道 key */
162
+ focused: string;
163
+ /** 当前布局方向 */
164
+ orientation: string;
165
+ /** 频道总数 */
166
+ count: number;
167
+ /** 数据更新代数,用于观测回收防串位 */
168
+ generation: number;
169
+ /** 当前滚动策略 */
170
+ scrollMode: string;
171
+ /** 当前图标位置 */
172
+ iconPosition: string;
173
+ /** 当前指示器形态 */
174
+ indicator: string;
175
+ /** 是否反转排列 */
176
+ reverseLayout: boolean;
177
+ /** 是否焦点即选中 */
178
+ selectOnFocus: boolean;
179
+ /** 是否焦点记忆 */
180
+ focusMemory: boolean;
181
+ /** 是否可获焦 */
182
+ focusable: boolean;
183
+ /** 是否平滑滚动 */
184
+ smoothScroll: boolean;
185
+ /** 复用池容量 */
186
+ poolSize: number;
187
+ /** 单项宽度 */
188
+ itemWidth: number;
189
+ /** 单项高度 */
190
+ itemHeight: number;
191
+ /** 频道项内容区内边距 */
192
+ itemPadding: number;
193
+ /** 图标与文字间距 */
194
+ iconMargin: number;
195
+ /** 当前主轴对齐方式 */
196
+ align: string;
197
+ /** 当前交叉轴对齐方式 */
198
+ crossAlign: string;
199
+ /** 首项主轴偏移(px),内容超出一屏时为 0 */
200
+ alignLeading: number;
201
+ /** 项间额外主轴间距(px),space-* 时大于 0 */
202
+ alignBetween: number;
203
+ /** 交叉轴偏移(px) */
204
+ alignCross: number;
205
+ /** 首个可见项位置 */
206
+ firstVisible?: number;
207
+ /** 最后一个可见项位置 */
208
+ lastVisible?: number;
209
+ }
210
+ /**
211
+ * @description 通过 defineExpose 暴露的命令式方法;带返回值的方法均为异步 Promise。
212
+ */
213
+ export interface QtxChannelNavExpose {
214
+ /** 取到底层原生节点,供高级场景直接调用 */
215
+ getNativeNode(): any;
216
+ /** 命令式设置选中频道,并回传 change 供上层同步受控值 */
217
+ setActive(key: string): void;
218
+ /** 读取当前选中频道 key */
219
+ getActiveKey(): Promise<string>;
220
+ /** 读取当前获焦频道 key */
221
+ getFocusedKey(): Promise<string>;
222
+ /** 把遥控器焦点请求到当前选中频道 */
223
+ requestFocus(): Promise<string>;
224
+ /** 清除频道栏焦点与焦点态 */
225
+ clearFocus(): Promise<string>;
226
+ /** 读取完整状态快照 */
227
+ getState(): Promise<QtxChannelNavState>;
228
+ /** 滚动到指定频道 key */
229
+ scrollToKey(key: string): Promise<string>;
230
+ /** 差量更新频道数据;key 序列不变时只刷新内容变化的项 */
231
+ updateItems(items: QtxChannelNavItem[]): Promise<string>;
232
+ /** 运行时切换横竖方向,内部清池并重建布局 */
233
+ setOrientation(orientation: 'horizontal' | 'vertical' | string): Promise<string>;
234
+ /** 批量覆盖视觉 token,避免逐个 prop 触发多次刷新 */
235
+ setStyle(tokens: Partial<QtxChannelNavProps>): Promise<string>;
236
+ /** 读取频道总数 */
237
+ getItemCount(): Promise<number>;
238
+ /** 按位置读取单个频道项 */
239
+ getItemAt(index: number): Promise<QtxChannelNavItem>;
240
+ /** 读取可见区间与滚动状态快照 */
241
+ getScrollState(): Promise<QtxChannelNavState>;
242
+ }