@quicktvui/qtx 0.0.0-stage → 0.9.0-alpha.1

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.
Files changed (83) hide show
  1. package/AI_CONTRACT.md +472 -0
  2. package/README.md +173 -2
  3. package/dist/components/QtxAppIcon/QtxAppIcon.vue.d.ts +73 -0
  4. package/dist/components/QtxAppIcon/QtxAppIconBase.vue.d.ts +144 -0
  5. package/dist/components/QtxAppIcon/index.d.ts +13 -0
  6. package/dist/components/QtxAppIcon/types.d.ts +157 -0
  7. package/dist/components/QtxButton/QtxButton.vue.d.ts +24 -0
  8. package/dist/components/QtxButton/QtxButtonBase.vue.d.ts +64 -0
  9. package/dist/components/QtxButton/index.d.ts +13 -0
  10. package/dist/components/QtxCheckbox/QtxCheckbox.vue.d.ts +110 -0
  11. package/dist/components/QtxCheckbox/index.d.ts +13 -0
  12. package/dist/components/QtxCheckboxGroup/QtxCheckboxGroup.vue.d.ts +103 -0
  13. package/dist/components/QtxCheckboxGroup/index.d.ts +13 -0
  14. package/dist/components/QtxCollapseMenuGroup/QtxCollapseMenuGroup.vue.d.ts +9 -0
  15. package/dist/components/QtxCollapseMenuGroup/QtxCollapseMenuGroupBase.vue.d.ts +40 -0
  16. package/dist/components/QtxCollapseMenuGroup/index.d.ts +13 -0
  17. package/dist/components/QtxCollapseMenuList/QtxCollapseMenuList.vue.d.ts +12 -0
  18. package/dist/components/QtxCollapseMenuList/QtxCollapseMenuListBase.vue.d.ts +32 -0
  19. package/dist/components/QtxCollapseMenuList/index.d.ts +13 -0
  20. package/dist/components/QtxDatePicker/QtxDatePicker.vue.d.ts +28 -0
  21. package/dist/components/QtxDatePicker/index.d.ts +13 -0
  22. package/dist/components/QtxGridTabs/QtxGridTabs.vue.d.ts +11 -0
  23. package/dist/components/QtxGridTabs/index.d.ts +13 -0
  24. package/dist/components/QtxGridTabs/useGridItemPresence.d.ts +26 -0
  25. package/dist/components/QtxGridTabs/useGridTabs.d.ts +163 -0
  26. package/dist/components/QtxGridTabs/useGridTabsData.d.ts +20 -0
  27. package/dist/components/QtxGridTabs/useGridTabsUpdater.d.ts +24 -0
  28. package/dist/components/QtxHsvBackground/QtxHsvBackground.vue.d.ts +26 -0
  29. package/dist/components/QtxHsvBackground/index.d.ts +13 -0
  30. package/dist/components/QtxInputView/QtxInputView.vue.d.ts +42 -0
  31. package/dist/components/QtxInputView/QtxInputViewBase.vue.d.ts +46 -0
  32. package/dist/components/QtxInputView/index.d.ts +13 -0
  33. package/dist/components/QtxKeyboard/QtxKeyboard.vue.d.ts +59 -0
  34. package/dist/components/QtxKeyboard/index.d.ts +13 -0
  35. package/dist/components/QtxList/QtxList.vue.d.ts +96 -0
  36. package/dist/components/QtxList/QtxListBase.vue.d.ts +11 -0
  37. package/dist/components/QtxList/capture.d.ts +86 -0
  38. package/dist/components/QtxList/index.d.ts +13 -0
  39. package/dist/components/QtxList/types.d.ts +78 -0
  40. package/dist/components/QtxNumericKeyboard/QtxNumericKeyboard.vue.d.ts +28 -0
  41. package/dist/components/QtxNumericKeyboard/index.d.ts +13 -0
  42. package/dist/components/QtxPortalItem/QtxPortalItem.vue.d.ts +24 -0
  43. package/dist/components/QtxPortalItem/index.d.ts +13 -0
  44. package/dist/components/QtxPortalPool/QtxPortalPool.vue.d.ts +11 -0
  45. package/dist/components/QtxPortalPool/index.d.ts +13 -0
  46. package/dist/components/QtxPoster/QtxPoster.vue.d.ts +60 -0
  47. package/dist/components/QtxPoster/QtxPosterBase.vue.d.ts +117 -0
  48. package/dist/components/QtxPoster/index.d.ts +13 -0
  49. package/dist/components/QtxPoster/types.d.ts +133 -0
  50. package/dist/components/QtxRadioGroup/QtxRadioGroup.vue.d.ts +103 -0
  51. package/dist/components/QtxRadioGroup/index.d.ts +13 -0
  52. package/dist/components/QtxRatingBar/QtxRatingBar.vue.d.ts +34 -0
  53. package/dist/components/QtxRatingBar/index.d.ts +13 -0
  54. package/dist/components/QtxSettingSwitch/QtxSettingSwitch.vue.d.ts +111 -0
  55. package/dist/components/QtxSettingSwitch/index.d.ts +6 -0
  56. package/dist/components/QtxSvgImage/QtxSvgImage.vue.d.ts +26 -0
  57. package/dist/components/QtxSvgImage/index.d.ts +13 -0
  58. package/dist/components/QtxSwitcher/QtxSwitcher.vue.d.ts +52 -0
  59. package/dist/components/QtxSwitcher/index.d.ts +13 -0
  60. package/dist/components/QtxTabContent/QtxTabContent.vue.d.ts +24 -0
  61. package/dist/components/QtxTabs/QtxTabs.vue.d.ts +37 -0
  62. package/dist/components/QtxTabs/index.d.ts +16 -0
  63. package/dist/core/installQtx.d.ts +40 -0
  64. package/dist/core/portalCoordinator.d.ts +4 -0
  65. package/dist/core/qtxGate.d.ts +13 -0
  66. package/dist/core/theme.d.ts +12 -0
  67. package/dist/directives/v-portal-to.d.ts +4 -0
  68. package/dist/index.d.ts +139 -0
  69. package/dist/modules/AddonEnvModule.d.ts +4 -0
  70. package/dist/modules/ExtraUIConfigModule.d.ts +7 -0
  71. package/dist/modules/GridTabsConfigModule.d.ts +7 -0
  72. package/dist/modules/QtxVersionModule.d.ts +4 -0
  73. package/dist/preset-items/QtxStyledList.vue.d.ts +65 -0
  74. package/dist/preset-items/compact.d.ts +2 -0
  75. package/dist/preset-items/glint.d.ts +11 -0
  76. package/dist/preset-items/index.d.ts +45 -0
  77. package/dist/preset-items/retired-items.d.ts +22 -0
  78. package/dist/preset-items/types.d.ts +112 -0
  79. package/dist/qtx.cjs.js +1 -0
  80. package/dist/qtx.es.js +6375 -0
  81. package/dist/style.css +1 -0
  82. package/dist/types/index.d.ts +50 -0
  83. package/package.json +32 -4
package/AI_CONTRACT.md ADDED
@@ -0,0 +1,472 @@
1
+ <!-- GENERATED · DO NOT EDIT · 由 npm run docs:readme 从 docs-site/guide/ai-contract.md 同步 -->
2
+
3
+ > 本文件随 `@quicktvui/qtx` npm 包分发,供只读包内文件的 AI / 接入方使用。**源码仓库为私有维护仓库,不对外公开,接入方无需访问**;本文与包内 `README.md` 即是完整接入资料。
4
+
5
+ ---
6
+
7
+ # 给 AI 的接入契约
8
+
9
+ > 本文是面向「只读文档的 AI / 第三方接入方」的自足接入说明,属于语义层。API 参数一律以各组件生成页为准,本文不复制 API 表。
10
+ >
11
+ > 本文同时随 npm 包分发为 `@quicktvui/qtx/AI_CONTRACT.md`。安装本包后无需访问源码仓库或在线文档站,即可按本文完成接入与一个双页 TV 应用;门禁 D26 校验包内副本与语义页一致。
12
+
13
+ ## 0. 必读顺序与资料分工
14
+
15
+ qtx 是 **QuickTVUI 平台之上的扩展库**,不是一套独立的 TV 应用框架。平台提供渲染器、焦点、按键、路由、生命周期、播放器与 `qtx-*` 组件所需的原生能力;qtx 提供 `qtx-*` 组件与内置 item 风格包。两套资料的覆盖范围不同,必须按顺序读,不能互相替代。
16
+
17
+ | 顺序 | 资料 | 由谁提供 | 覆盖范围 | 缺失时会发生什么 |
18
+ | --- | --- | --- | --- | --- |
19
+ | 1 | 项目根 `AGENTS.md` / `CLAUDE.md` | 平台模板项目,随 `quicktvui-template` 分发 | 脚手架、`quicktvui-ai` 命令顺序、页面生命周期、按键与焦点约定、禁止的 Web 写法 | 生成通用 Vue 工程结构,或把生命周期函数写错名字 |
20
+ | 2 | `node_modules/@quicktvui/ai/rules/.docs/` 与 `https://www.quicktvui.com/zh-CN/` | `@quicktvui/ai` 依赖 / 平台官网 | 平台原生 `qt-*` 组件、CSS 扩展、模块 API、播放器与路由指南 | 把平台组件名、属性、事件按 Web 习惯推断 |
21
+ | 3 | 本包 `README.md` | `@quicktvui/qtx` npm 包 | 版本、组件清单、内置 item 清单、已知限制摘要 | 用错版本,或把内置 item 当成 Vue 组件 |
22
+ | 4 | **本文** | 本包 `AI_CONTRACT.md` / 站点 `docs-site/guide/ai-contract.md` | 依赖矩阵、宿主接入、完整工程示例、装机链路、资料边界 | 缺一份可复制、能跑起来的端到端工程 |
23
+ | 5 | 本包 `dist` 内的类型声明 | 随包分发 | 每个 `qtx-*` 组件的属性 / 事件 / 方法声明 | 只能凭名称猜测 `qtx-*` 参数 |
24
+
25
+ 必须明确的边界:
26
+
27
+ - `AGENTS.md` 与 `node_modules/@quicktvui/ai/rules/.docs/` **不随本 npm 包分发**,也不在 `peerDependencies` 中;它们属于平台模板项目,全文不含 `qtx-*` 组件定义。
28
+ - 文档站 **尚未部署在线地址**,也不随 npm 包分发;源码仓库为私有维护仓库,不对外公开。接入方以本包 `dist` 内的类型声明与本文为准。
29
+ - 因此「只读本包」可完成 qtx 接入与最小双页应用;要使用平台原生 `qt-*` 组件、播放器或高级路由能力,必须回到第 1、2 项资料。**不要把平台文档的 `qt-*` 属性套到 `qtx-*` 标签上**。
30
+
31
+ ## 1. 前置条件矩阵
32
+
33
+ | 项 | 要求 | 依据 / 位置 |
34
+ | --- | --- | --- |
35
+ | 宿主工程 | 由 `quicktvui-template` 克隆,不使用通用 Vue 脚手架 | `AGENTS.md`「Project Scaffolding」 |
36
+ | JS 运行时 | `@extscreen/es3-core >=3.0.0`、`@extscreen/es3-vue >=3.0.0`、`vue >=3.2.0`(`peerDependencies`) | `js/qtx/package.json` |
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` 版本路线 |
40
+ | 宿主运行时 | 由 QuickTVUI 平台提供;`qtx-*` 组件的原生能力随运行时就绪,**接入方无需安装或配置额外组件** | 平台模板项目 / `AGENTS.md` |
41
+ | 播放器 | 本包**不含播放器实现**,播放能力由平台提供,见平台文档的播放器章节 | `CHANGELOG.md` 已知限制 |
42
+ | 设备 | 一台已 `adb connect` 的 TV / 盒子类设备;多设备时须明确指定 serial。若使用线上快应用引擎验收,可跳过本地运行时安装步骤 | `AGENTS.md`「Run To TV Workflow」 |
43
+
44
+ `0.9.0-alpha.1` 属于语义化版本的 `0.y.z` 阶段,**允许破坏性变更,不承诺向下兼容**。升级前重新核对组件生成页。
45
+
46
+ > **开发者只需关心 Vue 侧**:安装本包、`app.use(qtx)`、按平台模板写页面。原生能力的探测、装载与版本兼容属于平台运行时的内部实现,不在接入范围内,也不需要写进业务代码或工程配置。若页面长时间停在骨架屏或出现诊断信息,属于运行时环境问题,请把日志交给平台侧排查。
47
+
48
+ ## 2. 从零到运行的固定顺序
49
+
50
+ 以下顺序来自平台 `AGENTS.md`,不得跳步、不得先跑 `yarn dev` / `npm run dev`:
51
+
52
+ ```bash
53
+ # 1 脚手架(不要生成通用 Vue 工程)
54
+ git clone https://github.com/quicktvui/quicktvui-template.git my-tv-app
55
+ cd my-tv-app && rm -rf .git
56
+ # 2 修改 package.json 的 name 为 my-tv-app、version 重置为 1.0.0
57
+ yarn install
58
+ # 3 安装 qtx(固定版本)
59
+ npm i @quicktvui/qtx@0.9.0-alpha.1
60
+ # 4 环境未就绪时先执行
61
+ quicktvui-ai setup-all-env --project <project-path>
62
+
63
+ # 5 上机运行(顺序固定,先发现 CLI 能力)
64
+ quicktvui-ai --help
65
+ quicktvui-ai doctor --project <project-path>
66
+ quicktvui-ai setup-vue-env --project <project-path>
67
+ quicktvui-ai setup-android-env --project <project-path>
68
+ quicktvui-ai run-dev --project <project-path>
69
+ ```
70
+
71
+ 运行链路的硬性要求:
72
+
73
+ 1. 执行环境与设备检查之前不要直接启动 dev server;若所需步骤没有对应 `quicktvui-ai` 命令,先明确声明 CLI gap,再使用手工回退链路。
74
+ 2. `adb devices` 确认目标;单设备时不强制区分 TV / 手机,多设备时必须先让用户选择 serial。
75
+ 3. 运行时 APK 只从 `quicktvui-runtime-apk` 的 Gitee / GitHub 可信仓库获取,按 `latest.json` → channel manifest → `repo_path` + `sha256` 校验后再 `adb install -r`。
76
+ 4. 启动前检查目标 runtime 暴露 `eskit.sdk.core.ui.BrowserProxyActivity`(`android.intent.action.VIEW` + `esapp` scheme),检查失败即停止并让用户重装 runtime。
77
+ 5. `run-dev` 到达 runtime launcher 页后,**必须发送一次确认动作**(`adb shell input keyevent 23` 或 `66`)让 runtime 拉取 dev bundle;随后通过 `quicktvui-ai runtime-status`(可用时)或日志确认加载结果,不能停在 launcher 页就宣称完成。
78
+ 6. 排错取 `logcat`、`uiautomator dump` 与构建输出原文,并注明宿主平台版本与 qtx 版本。
79
+
80
+ ## 3. 完整工程(可逐字复制)
81
+
82
+ 目录结构:
83
+
84
+ ```text
85
+ src/
86
+ main.ts 应用入口:ESApp、ESRouter、平台组件与 qtx 注册
87
+ App.vue 路由容器,定义应用级生命周期与返回键
88
+ routes.ts 路由表:index / detail / error
89
+ data/catalog.ts 数据层(示例为本地数据,可替换为接口)
90
+ pages/Index.vue 首页:qtx-list + qtx-button + 焦点 + 跳转
91
+ pages/Detail.vue 详情页:接收路由参数 + 返回键
92
+ pages/Error.vue 错误页
93
+ ```
94
+
95
+ 把 `examples/tv-app/src/` 下的文件按相同相对路径复制进 `quicktvui-template` 生成工程的 `src/` 目录,并在 `package.json` 中保留模板提供的 `@extscreen/*` / `@quicktvui/quicktvui3` 依赖,再按第 2 节执行安装与运行。
96
+
97
+ 以下代码与仓库 `examples/tv-app/` 下的真实文件逐字一致,由 `docs:check` 的 D27 逐文件校验,并用真实 `qtx-tpl-loader` 编译校验 `.vue` 文件无 `[QTX-T-EXPR]` 回落。
98
+
99
+ ### 3.1 `src/main.ts`
100
+
101
+ ```ts
102
+ import { createESApp } from '@extscreen/es3-core'
103
+ import { ESComponent } from '@extscreen/es3-component'
104
+ import { createESRouter, type Router } from '@extscreen/es3-router'
105
+ import { ESApp } from '@extscreen/es3-vue'
106
+ import '@quicktvui/quicktvui3/dist/index.css'
107
+ import { QuickTVUI } from '@quicktvui/quicktvui3'
108
+ import qtx from '@quicktvui/qtx'
109
+ import application from './App.vue'
110
+ import routes from './routes'
111
+
112
+ const router: Router = createESRouter({
113
+ main: 'index',
114
+ error: 'error',
115
+ limit: 10,
116
+ routes,
117
+ })
118
+
119
+ const app: ESApp = createESApp(application, router)
120
+ app.use(ESComponent)
121
+ app.use(QuickTVUI)
122
+ app.use(qtx)
123
+ ```
124
+
125
+ `app.use(qtx)` 注册全部 `qtx-*` 组件即可;原生能力由宿主运行时提供,业务代码无需参与装载或兼容判断。
126
+
127
+ ### 3.2 `src/App.vue`
128
+
129
+ ```vue
130
+ <template>
131
+ <div :width="1920" :height="1080" class="root">
132
+ <es-router-view :width="1920" :height="1080" />
133
+ </div>
134
+ </template>
135
+
136
+ <script lang="ts">
137
+ import { defineComponent } from 'vue'
138
+ import { useESRouterManager } from '@extscreen/es3-core'
139
+ import { useESRouter } from '@extscreen/es3-router'
140
+
141
+ export default defineComponent({
142
+ name: 'App',
143
+ setup() {
144
+ const router = useESRouter()
145
+ const routerManager = useESRouterManager()
146
+ routerManager.setAutoRedirectEnabled(false)
147
+
148
+ // 平台按精确函数名回调,函数必须定义在 setup() 内并出现在 return 中。
149
+ function onESCreate(app: unknown, params: Record<string, unknown>) {}
150
+ function onESCreated(success: boolean) {
151
+ if (success) {
152
+ router.push({ name: 'index', params: {} })
153
+ }
154
+ }
155
+ function onBackPressed() {
156
+ router.back()
157
+ }
158
+ return { onESCreate, onESCreated, onBackPressed }
159
+ },
160
+ })
161
+ </script>
162
+
163
+ <style scoped>
164
+ .root {
165
+ width: 1920px;
166
+ height: 1080px;
167
+ background-color: #101418;
168
+ display: flex;
169
+ flex-direction: column;
170
+ }
171
+ </style>
172
+ ```
173
+
174
+ ### 3.3 `src/routes.ts`
175
+
176
+ ```ts
177
+ import index from './pages/Index.vue'
178
+ import detail from './pages/Detail.vue'
179
+ import error from './pages/Error.vue'
180
+
181
+ export default [
182
+ { path: '/index', name: 'index', component: index },
183
+ { path: '/detail', name: 'detail', component: detail },
184
+ { path: '/error', name: 'error', component: error },
185
+ ]
186
+ ```
187
+
188
+ ### 3.4 `src/data/catalog.ts`
189
+
190
+ ```ts
191
+ export interface CatalogItem {
192
+ id: string
193
+ title: string
194
+ subtitle: string
195
+ description: string
196
+ }
197
+
198
+ // 示例数据层:真实项目把本文件替换为接口请求 + 缓存 + 错误态处理即可。
199
+ const CATALOG: CatalogItem[] = [
200
+ { id: 'm1', title: '影片 A', subtitle: '动作 · 2026', description: '影片 A 的剧情简介。' },
201
+ { id: 'm2', title: '影片 B', subtitle: '纪录 · 2025', description: '影片 B 的剧情简介。' },
202
+ { id: 'm3', title: '影片 C', subtitle: '动画 · 2026', description: '影片 C 的剧情简介。' },
203
+ { id: 'm4', title: '影片 D', subtitle: '家庭 · 2024', description: '影片 D 的剧情简介。' },
204
+ { id: 'm5', title: '影片 E', subtitle: '科幻 · 2026', description: '影片 E 的剧情简介。' },
205
+ { id: 'm6', title: '影片 F', subtitle: '喜剧 · 2025', description: '影片 F 的剧情简介。' },
206
+ ]
207
+
208
+ export function loadHomeRows(): CatalogItem[] {
209
+ return CATALOG.map((item) => ({ ...item }))
210
+ }
211
+
212
+ export function findCatalogItem(id: string): CatalogItem | undefined {
213
+ return CATALOG.find((item) => item.id === id)
214
+ }
215
+ ```
216
+
217
+ ### 3.5 `src/pages/Index.vue`
218
+
219
+ ```vue
220
+ <template>
221
+ <div :width="1920" :height="1080" class="page">
222
+ <qt-text text="qtx TV 首页" :width="1200" :height="70" class="title" />
223
+ <qtx-button
224
+ text="刷新数据"
225
+ :width="240"
226
+ :height="64"
227
+ :autofocus="true"
228
+ @click="onReload"
229
+ />
230
+ <qtx-list
231
+ :items="rows"
232
+ :columns="2"
233
+ :item-height="220"
234
+ key-field="id"
235
+ :width="1920"
236
+ :height="880"
237
+ @item-click="onItemClick"
238
+ >
239
+ <template #item="{ item }">
240
+ <div :width="900" :height="220" class="row">
241
+ <qt-text :text="item.title" :width="860" :height="60" class="row-title" />
242
+ <qt-text :text="item.subtitle" :width="860" :height="50" class="row-sub" />
243
+ </div>
244
+ </template>
245
+ </qtx-list>
246
+ </div>
247
+ </template>
248
+
249
+ <script lang="ts">
250
+ import { defineComponent, ref } from 'vue'
251
+ import { useESRouter } from '@extscreen/es3-router'
252
+ import type { QtxListItemEvent } from '@quicktvui/qtx'
253
+ import { loadHomeRows, type CatalogItem } from '../data/catalog'
254
+
255
+ export default defineComponent({
256
+ name: 'IndexPage',
257
+ setup() {
258
+ const router = useESRouter()
259
+ const rows = ref<CatalogItem[]>(loadHomeRows())
260
+
261
+ function onESCreate(params: Record<string, unknown>) {
262
+ rows.value = loadHomeRows()
263
+ }
264
+ function onReload() {
265
+ rows.value = loadHomeRows()
266
+ }
267
+ function onItemClick(event: QtxListItemEvent) {
268
+ const id = event?.item?.id
269
+ if (!id) return
270
+ router.push({
271
+ name: 'detail',
272
+ params: { id: String(id), title: String(event.item?.title ?? '') },
273
+ })
274
+ }
275
+ function onBackPressed() {
276
+ router.back()
277
+ }
278
+ return { rows, onESCreate, onReload, onItemClick, onBackPressed }
279
+ },
280
+ })
281
+ </script>
282
+
283
+ <style scoped>
284
+ .page {
285
+ width: 1920px;
286
+ height: 1080px;
287
+ background-color: #101418;
288
+ padding-left: 60px;
289
+ padding-top: 40px;
290
+ }
291
+ .title {
292
+ font-size: 40px;
293
+ color: #ffffff;
294
+ margin-bottom: 20px;
295
+ }
296
+ .row {
297
+ background-color: #1e2731;
298
+ border-radius: 12px;
299
+ padding-left: 20px;
300
+ justify-content: center;
301
+ }
302
+ .row-title {
303
+ font-size: 30px;
304
+ color: #ffffff;
305
+ }
306
+ .row-sub {
307
+ font-size: 22px;
308
+ color: #9fb0c0;
309
+ }
310
+ </style>
311
+ ```
312
+
313
+ `qtx-list` 的 `#item` 插槽词汇表封闭,只放框架标签与 `qt-*`;自定义 Vue 组件会被编译期回落并产生 `custom_component` 诊断。`@item-click` 的载荷为 `{ item, index, nodeId? }`,类型 `QtxListItemEvent` 随包导出。
314
+
315
+ ### 3.6 `src/pages/Detail.vue`
316
+
317
+ ```vue
318
+ <template>
319
+ <div :width="1920" :height="1080" class="page">
320
+ <qt-text :text="title" :width="1400" :height="80" class="title" />
321
+ <qt-text :text="description" :width="1400" :height="200" class="description" />
322
+ <qtx-button
323
+ text="返回首页"
324
+ :width="260"
325
+ :height="68"
326
+ :autofocus="true"
327
+ @click="onBackPressed"
328
+ />
329
+ </div>
330
+ </template>
331
+
332
+ <script lang="ts">
333
+ import { defineComponent, ref } from 'vue'
334
+ import { useESRouter } from '@extscreen/es3-router'
335
+ import { findCatalogItem } from '../data/catalog'
336
+
337
+ export default defineComponent({
338
+ name: 'DetailPage',
339
+ setup() {
340
+ const router = useESRouter()
341
+ const title = ref('详情')
342
+ const description = ref('')
343
+
344
+ function onESCreate(params: Record<string, unknown>) {
345
+ const id = String(params?.id ?? '')
346
+ const item = findCatalogItem(id)
347
+ title.value = String(params?.title ?? item?.title ?? '详情')
348
+ description.value = item?.description ?? '未找到该条目,请返回首页重新选择。'
349
+ }
350
+ function onBackPressed() {
351
+ router.back()
352
+ }
353
+ return { title, description, onESCreate, onBackPressed }
354
+ },
355
+ })
356
+ </script>
357
+
358
+ <style scoped>
359
+ .page {
360
+ width: 1920px;
361
+ height: 1080px;
362
+ background-color: #101418;
363
+ padding-left: 80px;
364
+ padding-top: 100px;
365
+ }
366
+ .title {
367
+ font-size: 48px;
368
+ color: #ffffff;
369
+ margin-bottom: 30px;
370
+ }
371
+ .description {
372
+ font-size: 26px;
373
+ color: #9fb0c0;
374
+ margin-bottom: 40px;
375
+ }
376
+ </style>
377
+ ```
378
+
379
+ ### 3.7 `src/pages/Error.vue`
380
+
381
+ ```vue
382
+ <template>
383
+ <div :width="1920" :height="1080" class="page">
384
+ <qt-text text="页面不存在" :width="1000" :height="80" class="title" />
385
+ <qtx-button
386
+ text="返回首页"
387
+ :width="260"
388
+ :height="68"
389
+ :autofocus="true"
390
+ @click="onBackPressed"
391
+ />
392
+ </div>
393
+ </template>
394
+
395
+ <script lang="ts">
396
+ import { defineComponent } from 'vue'
397
+ import { useESRouter } from '@extscreen/es3-router'
398
+
399
+ export default defineComponent({
400
+ name: 'ErrorPage',
401
+ setup() {
402
+ const router = useESRouter()
403
+ function onESCreate(params: Record<string, unknown>) {}
404
+ function onBackPressed() {
405
+ router.back()
406
+ }
407
+ return { onESCreate, onBackPressed }
408
+ },
409
+ })
410
+ </script>
411
+
412
+ <style scoped>
413
+ .page {
414
+ width: 1920px;
415
+ height: 1080px;
416
+ background-color: #101418;
417
+ padding-left: 80px;
418
+ padding-top: 100px;
419
+ }
420
+ .title {
421
+ font-size: 48px;
422
+ color: #ffffff;
423
+ margin-bottom: 40px;
424
+ }
425
+ </style>
426
+ ```
427
+
428
+ ## 4. 写页面的硬约束
429
+
430
+ 1. **不是浏览器**:没有 `window` / `document` / DOM API;禁止 `p` / `img` / `a` / `ul` / `li` / `h1`~`h6` / `label` / `button` / `section` / `main` / `article` 等标准 HTML 语义标签。`div` / `span` 是框架允许的容器,`qt-text` / `qt-image` / `qt-view` / `qt-row` / `qt-column` 是平台组件,两者与 `qtx-*` 可以在同一页面共存。
431
+ 2. **所有标签显式尺寸**:包括 `div`、`span`、`qt-*`、`qtx-*`,必须写 `width` / `height`(px),不能依赖内容或父布局自动撑开。
432
+ 3. **页面骨架固定**:根容器 1920×1080;每页至少一个 `:autofocus="true"` 的可获焦节点;`onESCreate(params)` 与 `onBackPressed()` 必须定义在 `setup()` 内并出现在 `return` 中。按键回调名是 `onKeyDown` / `onKeyUp`,返回键回调名是 `onBackPressed`,生命周期名是 `onESCreate` / `onESStart` / `onESResume` / `onESPause` / `onESStop` / `onESDestroy`,框架按精确名字匹配。
433
+ 4. **三套命名空间互不推断**:`qt-*` 是平台原生组件,`gt-*` 是 SDUI Grid-Tabs 协议组件,`qtx-*` 是本扩展库组件。三者不是别名,属性、事件与分页语义没有交集。
434
+ 5. **事件以生成页为准,注意双通道**:`<qtx-button>` 的确认动作可用 `@click`(Vue 透传 attrs → 原生 onClick,`js/demo/src/views/qtx-list-demo.vue` 真机使用);生成 API 表登记的 `@onButtonCustomEvent` 是另一条自定义事件通道,携带 native payload。两者不是同一个事件,**不要**据此推断其他 `qtx-*` 组件也有 `@click`;每个组件按各自生成页的事件表接线,自定义事件还须有 `eventNamesMap` 映射才能到达 Vue。
435
+ 6. **内置 item 不是 Vue 组件**:`presetItem()` / `styledRows()` / `QtxStyledList` 产出的是带 `viewType` 的列表行数据,由 Android 原生工厂渲染,不能放进 `#item` 插槽;内置样式行必须显式给 `aspectRatio`。
436
+ 7. **模板编译边界**:模板内禁用数组下标(`item.items[0]`)、`v-for` 的 index 别名引用、外部函数调用等超纲写法,否则回落运行时捕获并打印 `[QTX-T-EXPR]`。全仓以「0 条回落」为验收信号。
437
+
438
+ ## 5. 常见错误对照
439
+
440
+ | 写法 | 判定 | 依据 |
441
+ | --- | --- | --- |
442
+ | 用 `createApp(App)` + `vue-router` 搭工程 | 错误 | 宿主使用 `createESApp` + `createESRouter`,见 `src/main.ts` |
443
+ | `npm i @quicktvui/qtx` 不带版本 | 不推荐 | `0.9.0-alpha.1` 不设 `latest`,alpha 阶段允许破坏性变更 |
444
+ | 示例里 `:items="rows"` 但 `rows` 未定义 | 错误 | `rows` 必须是 `setup()` 中定义并返回的响应式数组 |
445
+ | 依据 `qt-list-view` 文档给 `qtx-list` 传属性 | 错误 | 平台资料不含 `qtx-*` 定义,参数查组件生成页 |
446
+ | 认为 `div` 完全禁用 | 错误 | 平台允许 `div` / `span` 容器,禁用的是标准 HTML 语义标签 |
447
+ | 认为所有 `qtx-*` 都能写 `@click` | 错误 | 仅按各组件生成页的事件表接线,见第 4 节第 5 条 |
448
+ | 在本包中找播放器组件 | 错误 | 播放器由宿主集成 ES SDK,本包不含实现 |
449
+ | 把 `CHANGELOG.md`、`docs-site/` 当包内路径打开 | 错误 | 两者不在 npm 包内,接入方无需也无法访问源码仓库;包内已知限制摘要见 `README.md` |
450
+
451
+ ## 6. 验收清单
452
+
453
+ - [ ] `yarn install` 与 `npm i @quicktvui/qtx@0.9.0-alpha.1` 均成功,宿主依赖版本满足 `peerDependencies`。
454
+ - [ ] `quicktvui-ai doctor` / `setup-vue-env` / `setup-android-env` 通过,`adb devices` 能看到目标。
455
+ - [ ] `run-dev` 到达 launcher 后已发送确认键,runtime 状态或日志显示 bundle 已加载。
456
+ - [ ] 首页渲染 6 行数据,遥控器上下左右能移动焦点,首屏存在一个自动获焦节点。
457
+ - [ ] 确认键打开详情页,详情页显示路由参数与数据层描述,返回键回到首页且焦点可用。
458
+ - [ ] 构建输出无 `[QTX-T-EXPR]`;`logcat` 无 `FATAL` / `ClassCastException` / `FallbackView` / `OOM` / `ANR`。
459
+ - [ ] 组件参数、事件载荷与当前版本的生成页一致;未使用 `DEPRECATED` 的历史手册。
460
+
461
+ ## 7. 版本与资料边界
462
+
463
+ - 当前版本 `0.9.0-alpha.1`。完整变更清单由维护方随发布说明提供;包内 `README.md` 内联了 alpha 摘要。**源码仓库为私有维护仓库,不对外公开,接入方无需访问**。
464
+ - 本包 `files` 只含 `dist`、`README.md` 与 `AI_CONTRACT.md`;`docs-site/`、`AGENTS.md`、`.docs/` 均不随包分发,文档站暂无在线部署地址。
465
+ - `docs/qtx-list-guide.md`、`docs/qtx-tabs-guide.md`、`docs/ai-guide/README.md` 与 `docs/components/*.md` 均为历史归档或占位产物,**不得**用于推断属性名与事件名。
466
+ - 需要 `qtx-*` 参数时以本包 `dist` 内的类型声明为准;需要平台 `qt-*` 参数时查平台官网或 `@quicktvui/ai` 的 `.docs`。
467
+
468
+ ## 8. 进一步阅读
469
+
470
+ - 平台官网:`https://www.quicktvui.com/zh-CN/`
471
+ - 平台完整应用范例:`https://github.com/quicktvui/hellotv.git`
472
+ - 平台模板:`https://github.com/quicktvui/quicktvui-template.git`
package/README.md CHANGED
@@ -1,3 +1,174 @@
1
- # Temporary Holding Version
1
+ <!-- GENERATED · DO NOT EDIT · 由 npm run docs:gen 从源码生成 -->
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # @quicktvui/qtx
4
+
5
+ QuickTVUI 官方扩展库:Vue 3 侧的 `qtx-*` 原生高性能组件封装,原生能力由 QuickTVUI 平台运行时提供。
6
+
7
+ > 面向整个扩展库的源码级文档,不只是某一个组件
8
+
9
+ > 当前版本 **`0.9.0-alpha.1`**(0.9 预发布阶段):用于第三方在真实 TV 场景试用并反馈。**本阶段允许破坏性变更,不承诺向下兼容**;先用一个真实项目完整验证后再发 `1.0.0`。
10
+
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
+
13
+ ## 安装
14
+
15
+ ```bash
16
+ npm i @quicktvui/qtx@0.9.0-alpha.1
17
+ ```
18
+
19
+ 不要省略版本号:alpha 包只以 npm dist-tag `alpha` 分发,不设 `latest`;`0.y.z` 阶段允许破坏性变更。
20
+
21
+ | 依赖 | 版本 / 坐标 | 说明 |
22
+ | --- | --- | --- |
23
+ | `@extscreen/es3-core` / `@extscreen/es3-vue` | `>=3.0.0`(peerDependencies) | 平台渲染器与运行时 |
24
+ | `vue` | `>=3.2.0`(peerDependencies) | Vue 3 |
25
+ | 常见宿主依赖 | `@extscreen/es3-component` / `@extscreen/es3-router` / `@quicktvui/quicktvui3` 均为 `^3.0.0` 系列 | 由 `quicktvui-template` 提供,见 `AI_CONTRACT.md` |
26
+ | 宿主运行时 | QuickTVUI 平台提供 | `qtx-*` 组件的原生能力随运行时就绪 |
27
+
28
+ 宿主工程由 QuickTVUI 平台运行时承载。**接入方只需在 Vue 工程中 `app.use(qtx)`,无需安装或配置额外原生组件**;原生能力的探测、装载与版本兼容是平台运行时的内部实现,不属于应用开发范围。页面若长时间停在骨架屏或显示诊断信息,请把日志交给平台侧排查。完整接入说明见同包 `AI_CONTRACT.md`。
29
+
30
+ ## 最小接入
31
+
32
+ ```ts
33
+ // src/main.ts —— 完整可运行版本见 AI_CONTRACT.md 第 3 节
34
+ import { createESApp } from '@extscreen/es3-core';
35
+ import { ESComponent } from '@extscreen/es3-component';
36
+ import { createESRouter } from '@extscreen/es3-router';
37
+ import { QuickTVUI } from '@quicktvui/quicktvui3';
38
+ import qtx from '@quicktvui/qtx';
39
+ import App from './App.vue';
40
+ import routes from './routes';
41
+
42
+ const router = createESRouter({ main: 'index', error: 'error', limit: 10, routes });
43
+ const app = createESApp(App, router);
44
+ app.use(ESComponent);
45
+ app.use(QuickTVUI);
46
+ app.use(qtx); // 注册全部 qtx-* 组件
47
+ ```
48
+
49
+ ```vue
50
+ <template>
51
+ <div :width="1920" :height="1080">
52
+ <qt-text text="首页" :width="600" :height="60" />
53
+ <qtx-list :items="rows" :columns="2" key-field="id" :width="1920" :height="880">
54
+ <template #item="{ item }">
55
+ <div :width="900" :height="220">
56
+ <qt-text :text="item.title" :width="860" :height="60" />
57
+ </div>
58
+ </template>
59
+ </qtx-list>
60
+ <qtx-button text="确定" :width="200" :height="60" :autofocus="true" @click="onOk" />
61
+ </div>
62
+ </template>
63
+ <script lang="ts">
64
+ import { defineComponent, ref } from 'vue';
65
+ import { useESRouter } from '@extscreen/es3-router';
66
+ export default defineComponent({
67
+ setup() {
68
+ const router = useESRouter();
69
+ const rows = ref([{ id: '1', title: '影片 A' }]); // 数据必须定义并 return
70
+ function onESCreate(params: Record<string, unknown>) {}
71
+ function onOk() { router.push({ name: 'detail', params: { id: '1' } }); }
72
+ function onBackPressed() { router.back(); }
73
+ return { rows, onESCreate, onOk, onBackPressed };
74
+ },
75
+ });
76
+ </script>
77
+ ```
78
+
79
+ - 平台按精确函数名回调:`onESCreate` / `onBackPressed` 等必须定义在 `setup()` 内并 return;每页至少一个 `:autofocus="true"` 节点,所有标签显式写 `width` / `height`。完整双页工程(路由 / 数据 / 焦点 / 返回键)见 `AI_CONTRACT.md` 第 3 节。
80
+ - `<qtx-button>` 的确认动作用 `@click`(Vue attrs 透传到原生 onClick,真机 demo 已使用);生成 API 表登记的 `@onButtonCustomEvent` 是另一条自定义事件通道。其他 `qtx-*` 组件按各自生成页的事件表接线。
81
+ - 宿主运行时未就绪时组件显示占位,就绪后自动渲染;业务代码无需参与原生能力的装载与兼容判断。
82
+
83
+ ## 组件清单(21)
84
+
85
+ 由 `js/qtx/src/index.ts` 的导出清单生成,不是手写清单;仅列出对外公开的组件。
86
+
87
+ ### 原生桥接组件(17)
88
+
89
+ - `<qtx-app-icon>` 应用图标卡片
90
+ - `<qtx-button>` 按钮
91
+ - `<qtx-checkbox>` 复选框
92
+ - `<qtx-collapse-menu-group>` 折叠菜单分组
93
+ - `<qtx-collapse-menu-list>` 折叠菜单列表
94
+ - `<qtx-date-picker>` 日期选择器
95
+ - `<qtx-hsv-background>` HSV 背景
96
+ - `<qtx-input-view>` 输入框
97
+ - `<qtx-keyboard>` 软键盘
98
+ - `<qtx-list>` 列表
99
+ - `<qtx-numeric-keyboard>` 数字键盘
100
+ - `<qtx-portal-item>` 传送门内容项
101
+ - `<qtx-portal-pool>` 传送门挂载区
102
+ - `<qtx-poster>` 海报卡片
103
+ - `<qtx-rating-bar>` 评分条
104
+ - `<qtx-svg-image>` SVG 图片
105
+ - `<qtx-switcher>` 开关
106
+
107
+ ### Vue 扩展组件(4)
108
+
109
+ - `<qtx-checkbox-group>` 复选框组
110
+ - `<qtx-radio-group>` 单选组
111
+ - `<qtx-setting-switch>` 设置开关
112
+ - `<qtx-tabs>` 标签页
113
+
114
+ 每个组件的 Props / Events / Methods 以本包 `dist` 内的类型声明与同包 `AI_CONTRACT.md` 为准。**文档站不随 npm 包分发、暂无在线地址,源码仓库为私有维护仓库且不对外公开**;包内不提供逐组件 API 表,不要从平台 `qt-*` 资料推断 `qtx-*` 参数。
115
+
116
+ ## 内置 item 风格包(6 种)
117
+
118
+ 除 `qtx-*` 组件外,库还提供一套固定风格的 TV 列表行:`presetItem()` / `styledRows()` / `QtxStyledList` 把业务行转成带 `viewType` 的预设行,交由 `QtxList` 复用 grid-tabs 的原生卡片工厂。**内置 item 不是 Vue 组件**,不能放进 `#item` 插槽;实际外观由 Android 原生工厂决定。
119
+
120
+ | 类型 | 名称 | viewType |
121
+ | --- | --- | --- |
122
+ | `header` | 版块标题 | `header` |
123
+ | `poster` | 标准海报卡片 | `poster` |
124
+ | `image` | 基础图片素材 | `image` |
125
+ | `text` | 状态化文本 | `text` |
126
+ | `spacer` | 物理间距 | `spacer` |
127
+ | `app_icon` | 应用图标 | `app_icon` |
128
+
129
+ 最小接入:
130
+
131
+ ```ts
132
+ import { styledRows } from '@quicktvui/qtx';
133
+
134
+ const cover = 'https://cdn.example.com/a.png'; // 接入时替换为业务 CDN 地址
135
+ const rows = styledRows([
136
+ { id: 'h1', type: 'header', title: '今日精选', span: 6 },
137
+ { id: 'p1', type: 'poster', image: cover, title: '影片 A', aspectRatio: 0.72 },
138
+ ]);
139
+ ```
140
+
141
+ `span` / `aspectRatio` 是行级协议字段;内置样式行**必须显式给出 `aspectRatio`**(宽 / 高),否则卡片高度会随图片内容塌陷。`qtx-list` 的跨列按 `span` 生效,约束在 `[1, columns]`。
142
+
143
+ 已下架 `banner` / `theme_card` / `tool_card`(规格定义与原生工厂保留,可从源码恢复)。完整字段规格、容器接线与真机结论由维护方内部资料维护,**不随 npm 包分发,也不对外提供地址**;接入方请以本包 `dist` 内的类型声明为准。
144
+
145
+ ## 写页面前必须知道
146
+
147
+ 1. **这不是浏览器**:没有 `window` / `document` / DOM API。禁止 `p` / `img` / `a` / `ul` / `li` / `h1`~`h6` / `label` / `button` / `section` / `main` / `article` 等标准 HTML 语义标签;`div` / `span` 是**框架允许的容器**,`qt-text` / `qt-image` / `qt-view` / `qt-row` / `qt-column` 是平台组件,可与 `qtx-*` 同页共存。
148
+ 2. **所有标签必须显式写 `width` / `height`(px)**,包括 `div` / `span`,不依赖内容或父布局自动撑开;根容器为 1920×1080,每页至少一个 `:autofocus="true"` 节点。
149
+ 3. **命名不可混用**:`qt-*` 是平台原生组件,`gt-*` 是 SDUI Grid-Tabs 协议组件,`qtx-*` 是本扩展库组件 —— 三者不是别名,props / 事件 / 分页语义无交集。
150
+ 4. **必读顺序**:平台模板项目的 `AGENTS.md` / `node_modules/@quicktvui/ai/rules/.docs/`(平台能力)→ 本包 `README.md` 与 `AI_CONTRACT.md`(qtx 接入)→ 本包 `dist` 内的类型声明(`qtx-*` 参数)。平台资料不含 `qtx-*` 定义;`docs/components/*.md` 是 qtx-cli 占位产物;`docs/qtx-list-guide.md` / `qtx-tabs-guide.md` / `docs/ai-guide/README.md` 已 DEPRECATED,**不要再从它们推断属性名 / 事件名**。
151
+ 5. **事件按生成页接线**:自定义事件需要 `eventNamesMap` 映射才能到达 Vue;`qtx-list` 的 `@item-click` 载荷为 `{ item, index, nodeId? }`。不要假设所有 `qtx-*` 都支持 `@click`。
152
+
153
+ ## 已知限制(alpha 摘要,包内内联)
154
+
155
+ 以下是包内可直接查阅的摘要;完整变更清单由维护方随发布说明提供。**源码仓库为私有维护仓库,不对外开放,接入方无需访问**:
156
+
157
+ - 图片圆角只作用于背景 / 描边,**不裁切图片内容**;
158
+ - 写操作 = 重建会丢焦点与滚动位置;高频更新(倒计时类)暂不可用;
159
+ - 模板内禁用数组下标(`item.items[0]`)、`v-for` index 别名、外部函数调用,会回落运行时捕获;
160
+ - 双引号文本经 JSON / 编译通道会被截断(`edge.E4-quotes`);
161
+ - 三个语义尚未定稿:顶栏滚动归属、`autoLoadToFill` 默认值、`qtx-list-ready` 的 `scopeKey` 身份契约 —— alpha 期间可能变更。
162
+
163
+ > 关于「runtime 组件 `ref` 是否取得到实例」:早期手册断言取不到,但当前源码已 `defineExpose(listApi)` 并在 `types.ts` 声明 `QtxListExpose`。**请真机复核,不要照抄任何一份文档的旧结论**;以文档站生成页的 Expose 表为准。
164
+
165
+ ## 文档与反馈
166
+
167
+ - **包内接入契约**:`AI_CONTRACT.md`(与本 README 同目录,随包分发;含完整工程示例与装机链路)。
168
+ - **组件参数**:以本包 `dist` 内的类型声明为准;文档站不随包分发、暂无在线地址。
169
+ - 平台资料:项目根 `AGENTS.md` 与 `https://www.quicktvui.com/zh-CN/`,由平台模板项目提供。
170
+ - 源码与贡献流程属于**私有维护仓库**,不对外公开,接入方无需访问;问题反馈请通过本包发布页或平台官方渠道提交。
171
+
172
+ ## 反馈
173
+
174
+ 问题请附最小复现 + `logcat` / `uiautomator dump` / 构建输出原文,并注明宿主平台版本与 qtx 版本。