@quicktvui/qtx 0.9.0-alpha.2 → 0.9.0-alpha.4

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/package.json CHANGED
@@ -1,13 +1,14 @@
1
1
  {
2
2
  "name": "@quicktvui/qtx",
3
- "version": "0.9.0-alpha.2",
3
+ "version": "0.9.0-alpha.4",
4
4
  "description": "Vue 3 wrappers for QuickTVUI Native Addons",
5
5
  "main": "dist/qtx.cjs.js",
6
6
  "module": "dist/qtx.es.js",
7
7
  "types": "dist/index.d.ts",
8
8
  "files": [
9
9
  "dist",
10
- "AI_CONTRACT.md"
10
+ "AI_CONTRACT.md",
11
+ "plugin"
11
12
  ],
12
13
  "scripts": {
13
14
  "dev": "vite build --watch",
@@ -0,0 +1,233 @@
1
+ /**
2
+ * qtx 编译期 Web 对齐注入(随 @quicktvui/qtx 包分发的独立副本)。
3
+ *
4
+ * 与 js/qtx-compiler/qtx-tpl-loader.js 里的 applyClipFix / applyOverflowClipFix
5
+ * 同源;scripts/verify/qtx-tpl-loader-cases.mjs 的 C28 逐字比对两者产物,防止漂移。
6
+ *
7
+ * 为什么需要它:
8
+ * - AOSP ViewGroup.setClipChildren() 把值设给「直接子」的 RenderNode,容器自己
9
+ * 写 clipChildren=true 不会给自己加回裁切;默认放行必须逐层由父容器给出。
10
+ * - View.setClipBounds() 直接作用于当前 View,是编译期唯一能给「自己这一层」
11
+ * 加裁剪的入口。故把 Web 的 overflow:hidden 翻译成 clipBounds。
12
+ *
13
+ * 对外效果:业务源码只写 Web 写法 —— 不写 = 不裁,写 overflow:hidden = 裁。
14
+ * Android 属性不出现在业务代码里。
15
+ */
16
+ let parse;
17
+ try {
18
+ ({ parse } = require('@vue/compiler-sfc'));
19
+ } catch (e) {
20
+ throw new Error('[qtx/plugin] 缺少 @vue/compiler-sfc;请安装 vue@3(或显式安装 @vue/compiler-sfc)');
21
+ }
22
+
23
+ const CLIP_FIX_TAGS = new Set(['div', 'qt-view']);
24
+ const CLIP_FIX_PROPS = ['clipChildren', 'clipPadding'];
25
+ const CLIP_FIX_OFF = /<!--\s*qtx-clip-fix:\s*off\s*-->/;
26
+ const STATIC_HIDDEN = /^\s*(?:'hidden'|"hidden")\s*$/;
27
+
28
+ /** SFC <style> 的 class → [[prop, value]](与 loader 的 collectStyles 同实现) */
29
+ function collectStyles(descriptor) {
30
+ const map = new Map();
31
+ for (const style of descriptor.styles) {
32
+ if (style.scoped) continue;
33
+ const text = style.content || '';
34
+ const re = /\.([A-Za-z0-9_-]+)\s*\{([^}]*)\}/g;
35
+ let m;
36
+ while ((m = re.exec(text)) !== null) {
37
+ const cls = m[1];
38
+ const decls = [];
39
+ for (const line of m[2].split(';')) {
40
+ const idx = line.indexOf(':');
41
+ if (idx > 0) decls.push([line.slice(0, idx).trim(), line.slice(idx + 1).trim()]);
42
+ }
43
+ if (!map.has(cls)) map.set(cls, []);
44
+ map.get(cls).push(...decls);
45
+ }
46
+ }
47
+ return map;
48
+ }
49
+
50
+ function isNamedSlot(el) {
51
+ return el && el.type === 1 && el.tag === 'template'
52
+ && (el.props || []).some((p) => p.type === 7 && p.name === 'slot');
53
+ }
54
+
55
+ function declaredClipProps(el) {
56
+ const found = new Set();
57
+ for (const p of el.props || []) {
58
+ if (p.type === 6 && CLIP_FIX_PROPS.includes(p.name)) found.add(p.name);
59
+ else if (p.type === 7 && p.name === 'bind' && p.arg && CLIP_FIX_PROPS.includes(p.arg.content)) {
60
+ found.add(p.arg.content);
61
+ }
62
+ }
63
+ return found;
64
+ }
65
+
66
+ function collectClipInjects(root) {
67
+ const out = [];
68
+ const walk = (el) => {
69
+ if (!el) return;
70
+ if (el.type === 0) { for (const c of el.children || []) walk(c); return; }
71
+ if (el.type !== 1 || isNamedSlot(el)) return;
72
+ if (CLIP_FIX_TAGS.has(el.tag) && el.loc && el.loc.start) {
73
+ const declared = declaredClipProps(el);
74
+ const missing = CLIP_FIX_PROPS.filter((k) => !declared.has(k));
75
+ if (missing.length) out.push({ offset: el.loc.start.offset, tag: el.tag, missing });
76
+ }
77
+ for (const c of el.children || []) walk(c);
78
+ };
79
+ walk(root);
80
+ return out;
81
+ }
82
+
83
+ /** 默认放行:给页面层 div / qt-view 补齐两个 false(跳过 #item 具名插槽) */
84
+ function applyClipFix(source, filename) {
85
+ let descriptor;
86
+ try { descriptor = parse(source, { filename }).descriptor; } catch (e) { return source; }
87
+ if (!descriptor.template || !descriptor.template.ast) return source;
88
+ const injects = collectClipInjects(descriptor.template.ast).sort((a, b) => b.offset - a.offset);
89
+ let out = source;
90
+ for (const inj of injects) {
91
+ const head = /^<([A-Za-z][\w-]*)/.exec(out.slice(inj.offset));
92
+ if (!head || head[1] !== inj.tag) continue;
93
+ const at = inj.offset + head[0].length;
94
+ const attrs = inj.missing.map((k) => `:${k}="false"`).join(' ');
95
+ out = out.slice(0, at) + ' ' + attrs + out.slice(at);
96
+ }
97
+ return out;
98
+ }
99
+
100
+ function staticClasses(el) {
101
+ const out = [];
102
+ for (const p of el.props || []) {
103
+ if (p.type === 6 && p.name === 'class' && p.value) {
104
+ for (const c of p.value.content.split(/\s+/)) if (c) out.push(c);
105
+ }
106
+ }
107
+ return out;
108
+ }
109
+
110
+ function hasOverflowHidden(el, styles) {
111
+ for (const p of el.props || []) {
112
+ if (p.type === 6 && p.name === 'overflow' && p.value
113
+ && p.value.content.trim() === 'hidden') return true;
114
+ if (p.type === 7 && p.name === 'bind' && p.arg && p.arg.content === 'overflow'
115
+ && p.exp && STATIC_HIDDEN.test(p.exp.content || '')) return true;
116
+ }
117
+ for (const cls of staticClasses(el)) {
118
+ if ((styles.get(cls) || []).some(([k, v]) => k === 'overflow' && v === 'hidden')) return true;
119
+ }
120
+ return false;
121
+ }
122
+
123
+ function hasClipBounds(el) {
124
+ return (el.props || []).some((p) =>
125
+ (p.type === 6 && p.name === 'clipBounds')
126
+ || (p.type === 7 && p.name === 'bind' && p.arg && p.arg.content === 'clipBounds'));
127
+ }
128
+
129
+ /** 尺寸表达式:优先复用 :width / :height 原表达式,其次 CSS class 固定 px */
130
+ function sizeExpr(el, key, styles) {
131
+ for (const p of el.props || []) {
132
+ if (p.type === 6 && p.name === key && p.value) {
133
+ const v = p.value.content.trim();
134
+ if (/^\d+(?:\.\d+)?$/.test(v)) return v;
135
+ } else if (p.type === 7 && p.name === 'bind' && p.arg && p.arg.content === key && p.exp) {
136
+ const v = (p.exp.content || '').trim();
137
+ if (v && !v.includes('"')) return v;
138
+ }
139
+ }
140
+ for (const cls of staticClasses(el)) {
141
+ for (const [k, v] of styles.get(cls) || []) {
142
+ if (k === key && /^\d+(?:\.\d+)?px$/.test(v)) return v.replace('px', '');
143
+ }
144
+ }
145
+ return null;
146
+ }
147
+
148
+ function collectOverflowClipInjects(root, styles) {
149
+ const injects = [];
150
+ const warnings = [];
151
+ const walk = (el) => {
152
+ if (!el) return;
153
+ if (el.type === 0) { for (const c of el.children || []) walk(c); return; }
154
+ if (el.type !== 1 || isNamedSlot(el)) return;
155
+ if (CLIP_FIX_TAGS.has(el.tag) && el.loc && el.loc.start
156
+ && hasOverflowHidden(el, styles) && !hasClipBounds(el)) {
157
+ const w = sizeExpr(el, 'width', styles);
158
+ const h = sizeExpr(el, 'height', styles);
159
+ if (w && h) injects.push({ offset: el.loc.start.offset, tag: el.tag, w, h });
160
+ else warnings.push(`${el.tag}.${staticClasses(el).join('.') || '(no class)'} @${el.loc.start.line}`);
161
+ }
162
+ for (const c of el.children || []) walk(c);
163
+ };
164
+ walk(root);
165
+ return { injects, warnings };
166
+ }
167
+
168
+ /** Web 对齐:overflow:hidden → 当前 View 的 clipBounds 矩形裁剪 */
169
+ function applyOverflowClipFix(source, filename) {
170
+ let descriptor;
171
+ try { descriptor = parse(source, { filename }).descriptor; } catch (e) { return source; }
172
+ if (!descriptor.template || !descriptor.template.ast) return source;
173
+ const styles = collectStyles(descriptor);
174
+ const { injects, warnings } = collectOverflowClipInjects(descriptor.template.ast, styles);
175
+ for (const w of warnings) {
176
+ console.warn(`[QTX-OVERFLOW] ${filename}: overflow:hidden 容器缺少静态尺寸(${w}),`
177
+ + '无法生成 clipBounds;请用 :width / :height 显式声明尺寸');
178
+ }
179
+ let out = source;
180
+ for (const inj of injects.sort((a, b) => b.offset - a.offset)) {
181
+ const head = /^<([A-Za-z][\w-]*)/.exec(out.slice(inj.offset));
182
+ if (!head || head[1] !== inj.tag) continue;
183
+ const at = inj.offset + head[0].length;
184
+ const attr = `:clipBounds="{left:0,top:0,right:${inj.w},bottom:${inj.h}}"`;
185
+ out = out.slice(0, at) + ' ' + attr + out.slice(at);
186
+ }
187
+ return out;
188
+ }
189
+
190
+ /**
191
+ * dev 期诊断:动态 :style 绑 CSS 字符串会在运行时抛 Style is Not Object 并黑屏。
192
+ * 静态 style / class 由编译期转成样式对象,运行时绑定不转,两者类型契约不同。
193
+ *
194
+ * 只报告、不改写源码 —— qtxClipFix 的注入产物必须保持不变(C28 逐字比对)。
195
+ */
196
+ const DYN_STYLE_BINDING = /:style\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
197
+ const styleWarned = new Set();
198
+
199
+ function diagnoseStyleBinding(source, filename) {
200
+ if (typeof source !== 'string' || !source.includes(':style')) return [];
201
+ const warnings = [];
202
+ DYN_STYLE_BINDING.lastIndex = 0;
203
+ let match;
204
+ while ((match = DYN_STYLE_BINDING.exec(source)) !== null) {
205
+ const raw = String(match[1] ?? match[2] ?? '').trim();
206
+ if (!raw) continue;
207
+ // 明确的字符串字面量或裸 CSS 文本才报警;对象字面量、数组与变量标识符不误报。
208
+ const stringLiteral = /^['"`]/.test(raw);
209
+ const cssText = /^[-\w]+\s*:/.test(raw) && /[;:]/.test(raw);
210
+ if (!stringLiteral && !cssText) continue;
211
+ const line = source.slice(0, match.index).split('\n').length;
212
+ const key = `${filename}:${line}:${raw}`;
213
+ if (styleWarned.has(key)) continue;
214
+ styleWarned.add(key);
215
+ const msg = `[QTX-STYLE] ${filename}:${line} 动态 :style 需要样式对象,`
216
+ + '不能绑定 CSS 字符串(运行时会抛 Style is Not Object 并导致页面无法渲染);'
217
+ + '静态 style / class 由编译期转成对象,两者类型契约不同。';
218
+ warnings.push(msg);
219
+ console.error(msg);
220
+ }
221
+ return warnings;
222
+ }
223
+
224
+ /** 插件入口:可被 Vite transform / webpack pre-loader 直接调用 */
225
+ function qtxClipFix(source, filename) {
226
+ if (process.env.QTX_TPL_NO_CLIP_FIX === '1' || CLIP_FIX_OFF.test(source)) return source;
227
+ return applyOverflowClipFix(applyClipFix(source, filename), filename);
228
+ }
229
+
230
+ module.exports = {
231
+ qtxClipFix, applyClipFix, applyOverflowClipFix, collectStyles, CLIP_FIX_OFF,
232
+ diagnoseStyleBinding,
233
+ };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * @quicktvui/qtx Vite 插件:让「依赖 qtx 的页面默认不裁、overflow:hidden 能裁」
3
+ * 在构建链上生效,无需业务写任何 Android 属性。
4
+ *
5
+ * 用法(vite.config.ts):
6
+ * import { qtx } from '@quicktvui/qtx/plugin/vite.mjs'
7
+ * export default defineConfig({ plugins: [vue(), qtx()] })
8
+ *
9
+ * enforce:'pre' 保证在 @vitejs/plugin-vue 拆分 SFC 之前处理完整 .vue 源码;
10
+ * 带 query 的子模块(?vue&type=template / style)跳过,避免重复注入。
11
+ */
12
+ import { createRequire } from 'node:module';
13
+
14
+ const require = createRequire(import.meta.url);
15
+ const { qtxClipFix, diagnoseStyleBinding } = require('./qtx-clip-inject.cjs');
16
+
17
+ export function qtx() {
18
+ return {
19
+ name: 'qtx:clip-align',
20
+ enforce: 'pre',
21
+ transform(code, id) {
22
+ if (id.includes('?')) return null;
23
+ if (!id.endsWith('.vue')) return null;
24
+ if (!code.includes('<template')) return null;
25
+ diagnoseStyleBinding(code, id);
26
+ const out = qtxClipFix(code, id);
27
+ return out === code ? null : { code: out, map: null };
28
+ },
29
+ };
30
+ }
31
+
32
+ export default qtx;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * @quicktvui/qtx webpack pre-loader:让「默认不裁 / overflow:hidden 能裁」在
3
+ * qt-dev / qt-build(quicktvui-template 默认构建链)上生效。
4
+ *
5
+ * 项目里放 scripts/qtx-webpack.config.js:
6
+ * module.exports = {
7
+ * module: { rules: [
8
+ * { test: /\.vue$/, enforce: 'pre',
9
+ * use: [require.resolve('@quicktvui/qtx/plugin/webpack.cjs')] },
10
+ * ] },
11
+ * };
12
+ *
13
+ * 然后给 dev / build 脚本加 -c:
14
+ * "dev": "qt-dev android -c scripts/qtx-webpack.config.js",
15
+ * "build:android": "qt-build android -c scripts/qtx-webpack.config.js"
16
+ *
17
+ * enforce:'pre' 保证在 vue-loader 拆分 SFC 之前处理完整 .vue 源码。
18
+ */
19
+ const { qtxClipFix, diagnoseStyleBinding } = require('./qtx-clip-inject.cjs');
20
+
21
+ module.exports = function qtxClipWebpackLoader(source) {
22
+ const filename = (this && this.resourcePath) || 'unknown.vue';
23
+ diagnoseStyleBinding(source, filename);
24
+ return qtxClipFix(source, filename);
25
+ };