Qt-Waterfall 模板替换原理

chenddcoder

1. 核心概念
   
2. 
   
3.   这是 Hippy/quicktvui 框架的一个数据驱动模板渲染机制，将 Vue 组件作为模板，通过 ${prop} 占位符实现数据绑定。
   
4. 
   
5.   ---
   
6. 
   
7.   1. 模板定义
   
8. 
   
9.   在 Vue 组件中使用 ${prop} 语法定义占位符：
   
10. 
    
11.    <!-- packages/quicktvui/src/waterfall/item/card-item.vue -->
    
12.    <es-card-container
    
13.      layout="${layout}"
    
14.      flexStyle="${style}"
    
15.      cardId="${cardId}"
    
16.      focusScale="${cardPlaceHolder.focusScale}"
    
17.      text="${title}"
    
18.    />
    
19. 
    
20.   语法特点：
    
21.    - ${propName} - 直接属性引用
    
22.    - ${obj.subProp} - 支持嵌套路径
    
23.    - ${prop==true} - 支持表达式
    
24. 
    
25.   ---
    
26. 
    
27.   2. 数据结构
    
28. 
    
29.   数据通过 JavaScript 对象传入，与占位符一一对应：
    
30. 
    
31.    // 数据项定义
    
32.    const item: QTWaterfallCardItem = {
    
33.      _id: '1',
    
34.      type: QTWaterfallItemType.QT_WATERFALL_ITEM_TYPE_CARD,
    
35.      cardId: '1717748409857474561',
    
36.      style: { width: 850, height: 400 },
    
37.      cardPlaceHolder: { enable: true, radius: 100, focusScale: 1.2 },
    
38.      decoration: { left: 90, top: 40 }
    
39.    }
    
40. 
    
41.   ---
    
42. 
    
43.   3. 渲染流程
    
44. 
    
45.    ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
    
46.    │  Vue 模板组件    │ ──▶ │  数据绑定引擎    │ ──▶ │  最终 DOM 元素   │
    
47.    │  ${prop} 占位符  │     │  replacePlaceholders│     │  实际属性值      │
    
48.    └─────────────────┘     └─────────────────┘     └─────────────────┘
    
49. 
    
50.   Web 平台实现（QtFastListView.js）：
    
51. 
    
52.    // 1. 捕获子组件作为模板
    
53.    insertChild(view, index) {
    
54.      this._templateChildren.push({
    
55.        dom: view.dom,
    
56.        component: view,
    
57.        type: view.props.type
    
58.      })
    
59.      view.dom.style.display = 'none' // 隐藏模板
    
60.    }
    
61. 
    
62.    // 2. 数据驱动渲染
    
63.    _createItemFromData(itemData, index) {
    
64.      // 克隆模板
    
65.      const clonedNode = matchingTemplate.dom.cloneNode(true)
    
66. 
    
67.      // 绑定数据
    
68.      this._bindDataToNode(clonedNode, itemData)
    
69. 
    
70.      return clonedNode
    
71.    }
    
72. 
    
73.    // 3. 占位符替换核心算法
    
74.    _replacePlaceholders(str, data) {
    
75.      return str.replace(/\$\{([^}]+)\}/g, (match, propPath) => {
    
76.        // 支持嵌套路径: "style.fontSize" → data.style.fontSize
    
77.        let value = propPath.split('.').reduce((obj, key) => {
    
78.          return obj?.[key]
    
79.        }, data)
    
80. 
    
81.        return value !== undefined ? String(value) : match
    
82.      })
    
83.    }
    
84. 
    
85.   ---
    
86. 
    
87.   4. 特殊属性处理
    
88. 
    
89. 
    
90.   ┌───────────────┬───────────────────────────────┐
    
91.   │ 属性          │ 处理方式                      │
    
92.   ├───────────────┼───────────────────────────────┤
    
93.   │ flexStyle     │ 对象展开为 CSS 样式           │
    
94.   │ list/listData │ 递归渲染子列表                │
    
95.   │ textSize      │ 转换为 fontSize 样式          │
    
96.   │ src           │ 支持 {url, uri, src} 对象解构 │
    
97.   │ showIf        │ 条件渲染控制                  │
    
98.   └───────────────┴───────────────────────────────┘
    
99. 
    
100.    // flexStyle 处理示例
     
101.    if (keyLower === 'flexstyle') {
     
102.      const styleObj = this._extractValue(attrValue, data)
     
103.      this._applyFlexStyleToElement(node, styleObj)
     
104.      // { width: 850, height: 400 } → style="width:850px;height:400px"
     
105.    }
     
106. 
     
107.   ---
     
108. 
     
109.   5. 类型匹配机制
     
110. 
     
111.   通过 type 属性实现模板与数据的匹配：
     
112. 
     
113.    <!-- 模板定义 -->
     
114.    <qt-poster :type="10001" />    <!-- 海报类型 -->
     
115.    <card-item :type="10003" />    <!-- 卡片类型 -->
     
116. 
     
117.    // 数据项
     
118.    const item = { type: 10003, ... } // 匹配 card-item 模板
     
119. 
     
120.    // 匹配逻辑
     
121.    let template = this._templateChildren.find(t => t.type === itemData.type)
     
122. 
     
123.   ---
     
124. 
     
125.   6. 单例模板
     
126. 
     
127.   singleton 属性标记只渲染一次的模板：
     
128. 
     
129.    <!-- 单例模板：只匹配一条数据，不克隆 -->
     
130.    <header-view singleton :type="100" />
     
131. 
     
132.    if (hasSingleton) {
     
133.      this._singletonTemplates.push({ dom: node, type })
     
134.      // 直接显示，不克隆
     
135.    }
     
136. 
     
137.   ---
     
138. 
     
139.   架构图
     
140. 
     
141.    ┌──────────────────────────────────────────────────────────────────┐
     
142.    │                        QtWaterfall                               │
     
143.    ├──────────────────────────────────────────────────────────────────┤
     
144.    │  setSectionList([section1, section2, ...])                       │
     
145.    │                                                                   │
     
146.    │  ┌─────────────────────────────────────────────────────────────┐ │
     
147.    │  │ Section (type: FLEX/CARD/PLUGIN...)                         │ │
     
148.    │  │  ├── titleStyle: { fontSize: 50 }                           │ │
     
149.    │  │  ├── itemList: [item1, item2, ...]                          │ │
     
150.    │  │  └── cardId: "模板ID"                                        │ │
     
151.    │  └─────────────────────────────────────────────────────────────┘ │
     
152.    │                            │                                      │
     
153.    │                            ▼                                      │
     
154.    │  ┌─────────────────────────────────────────────────────────────┐ │
     
155.    │  │ QtFastListView / tv-flex                                    │ │
     
156.    │  │  ├── Template Children (隐藏)                               │ │
     
157.    │  │  │    ├── <qt-poster type="10001"/>                        │ │
     
158.    │  │  │    └── <card-item type="10003"/>                        │ │
     
159.    │  │  └── Rendered Items (数据驱动克隆)                          │ │
     
160.    │  │       ├── Item[0] → clone(template) + bind(data[0])        │ │
     
161.    │  │       └── Item[1] → clone(template) + bind(data[1])        │ │
     
162.    │  └─────────────────────────────────────────────────────────────┘ │
     
163.    └──────────────────────────────────────────────────────────────────┘
     
164. 
     
165.   ---
     
166. 
     
167.   总结
     
168. 
     
169. 
     
170.   ┌───────────┬───────────────────────────────────┐
     
171.   │ 概念      │ 说明                              │
     
172.   ├───────────┼───────────────────────────────────┤
     
173.   │ 模板      │ Vue 组件，使用 ${prop} 定义占位符 │
     
174.   │ 数据      │ JS 对象，属性路径与占位符对应     │
     
175.   │ type      │ 匹配模板与数据的标识              │
     
176.   │ 渲染      │ 克隆模板 → 替换占位符 → 插入 DOM  │
     
177.   │ singleton │ 单例模板，不克隆，直接绑定数据    │
     
178.   └───────────┴───────────────────────────────────┘
     
179. 
     
180. 
     
181. ✦ 这种设计让 UI 模板可以完全复用，只需传入不同数据即可生成列表项，是典型的数据驱动视图模式。

复制代码