309 lines
8.4 KiB
Markdown
309 lines
8.4 KiB
Markdown
# 视图层（WXML / WXSS / WXS）
|
||
|
||
> 官方文档：https://developers.weixin.qq.com/miniprogram/dev/framework/view/
|
||
|
||
## WXML — 模板语法
|
||
|
||
### 数据绑定
|
||
|
||
```xml
|
||
<!-- 简单绑定 -->
|
||
<view>{{ message }}</view>
|
||
|
||
<!-- 组件属性绑定（需在双引号内） -->
|
||
<view id="item-{{id}}"></view>
|
||
|
||
<!-- 控制属性绑定 -->
|
||
<view wx:if="{{condition}}"></view>
|
||
|
||
<!-- 关键字绑定（注意 true/false 需要在 {{}} 内） -->
|
||
<checkbox checked="{{false}}"></checkbox>
|
||
<!-- ⚠️ 错误写法：checked="false" 会被当作字符串 "false"，结果为 true -->
|
||
|
||
<!-- 运算 -->
|
||
<view>{{ a + b }} + {{ c }} + d</view>
|
||
<view>{{"hello " + name}}</view>
|
||
<view>{{object.key}} {{array[0]}}</view>
|
||
|
||
<!-- 三元运算 -->
|
||
<view hidden="{{flag ? true : false}}">Hidden</view>
|
||
|
||
<!-- 组合（数组） -->
|
||
<view wx:for="{{[zero, 1, 2, 3, 4]}}">{{item}}</view>
|
||
|
||
<!-- 组合（对象） -->
|
||
<template is="objectCombine" data="{{for: a, bar: b}}"></template>
|
||
<!-- 展开运算符 -->
|
||
<template is="objectCombine" data="{{...obj1, ...obj2, e: 5}}"></template>
|
||
```
|
||
|
||
### 列表渲染 wx:for
|
||
|
||
```xml
|
||
<!-- 基本用法：默认 item 和 index -->
|
||
<view wx:for="{{array}}">
|
||
{{index}}: {{item.message}}
|
||
</view>
|
||
|
||
<!-- 自定义变量名 -->
|
||
<view wx:for="{{array}}" wx:for-index="idx" wx:for-item="itemName">
|
||
{{idx}}: {{itemName.message}}
|
||
</view>
|
||
|
||
<!-- 嵌套 -->
|
||
<view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="i">
|
||
<view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="j">
|
||
<view wx:if="{{i <= j}}">
|
||
{{i}} * {{j}} = {{i * j}}
|
||
</view>
|
||
</view>
|
||
</view>
|
||
|
||
<!-- ⚠️ wx:key 非常重要，用于列表项的唯一标识 -->
|
||
<!-- 值为字符串：item 的某个 property 名（该 property 值需唯一） -->
|
||
<switch wx:for="{{objectArray}}" wx:key="unique">{{item.id}}</switch>
|
||
|
||
<!-- 值为 *this：item 本身是唯一字符串或数字 -->
|
||
<switch wx:for="{{numberArray}}" wx:key="*this">{{item}}</switch>
|
||
```
|
||
|
||
**wx:key 的作用**：当数据改变触发重新渲染时，带有 key 的组件会被重新排序而非重新创建，保持自身状态（如 `<input>` 的输入内容、`<switch>` 的选中状态）。
|
||
|
||
### 条件渲染
|
||
|
||
```xml
|
||
<!-- wx:if / wx:elif / wx:else -->
|
||
<view wx:if="{{length > 5}}">1</view>
|
||
<view wx:elif="{{length > 2}}">2</view>
|
||
<view wx:else>3</view>
|
||
|
||
<!-- block wx:if（不会渲染为真实 DOM） -->
|
||
<block wx:if="{{true}}">
|
||
<view>view1</view>
|
||
<view>view2</view>
|
||
</block>
|
||
```
|
||
|
||
**wx:if vs hidden**：
|
||
- `wx:if` 是惰性的，条件为 false 时不渲染，切换时销毁/重建
|
||
- `hidden` 始终渲染，只是切换显示/隐藏（类似 CSS display:none）
|
||
- 频繁切换用 `hidden`，运行时条件不大可能改变用 `wx:if`
|
||
|
||
### 模板 template
|
||
|
||
```xml
|
||
<!-- 定义模板 -->
|
||
<template name="msgItem">
|
||
<view>
|
||
<text>{{index}}: {{msg}}</text>
|
||
<text>Time: {{time}}</text>
|
||
</view>
|
||
</template>
|
||
|
||
<!-- 使用模板 -->
|
||
<template is="msgItem" data="{{...item}}"/>
|
||
|
||
<!-- 动态模板名 -->
|
||
<template is="{{item % 2 == 0 ? 'even' : 'odd'}}"/>
|
||
```
|
||
|
||
### 引用
|
||
|
||
```xml
|
||
<!-- import：引入目标文件中定义的 template -->
|
||
<import src="item.wxml"/>
|
||
<template is="item" data="{{text: 'forbar'}}"/>
|
||
<!-- ⚠️ import 有作用域：只会引入目标文件中定义的 template，不会引入目标文件 import 的 template（不递归） -->
|
||
|
||
<!-- include：将目标文件除 <template/> <wxs/> 外的整个代码引入 -->
|
||
<include src="header.wxml"/>
|
||
<view>body</view>
|
||
<include src="footer.wxml"/>
|
||
```
|
||
|
||
## WXSS — 样式
|
||
|
||
### rpx 单位
|
||
|
||
rpx（responsive pixel）：可以根据屏幕宽度进行自适应。规定屏幕宽为 750rpx。
|
||
|
||
| 设备 | rpx 换算 px | px 换算 rpx |
|
||
|------|------------|------------|
|
||
| iPhone5 | 1rpx = 0.42px | 1px = 2.34rpx |
|
||
| iPhone6 | 1rpx = 0.5px | 1px = 2rpx |
|
||
| iPhone6 Plus | 1rpx = 0.552px | 1px = 1.81rpx |
|
||
|
||
**建议**：开发时以 iPhone6 为视觉稿标准（750px 宽），1px = 1rpx。
|
||
|
||
### 样式导入
|
||
|
||
```css
|
||
/* common.wxss */
|
||
.small-p { padding: 5px; }
|
||
|
||
/* app.wxss */
|
||
@import "common.wxss";
|
||
.middle-p { padding: 15px; }
|
||
```
|
||
|
||
### 选择器支持
|
||
|
||
| 选择器 | 示例 | 说明 |
|
||
|--------|------|------|
|
||
| .class | `.intro` | 类选择器 |
|
||
| #id | `#firstname` | ID 选择器 |
|
||
| element | `view` | 元素选择器 |
|
||
| element, element | `view, checkbox` | 群组选择器 |
|
||
| ::after | `view::after` | 伪元素 |
|
||
| ::before | `view::before` | 伪元素 |
|
||
|
||
### 内联样式
|
||
|
||
```xml
|
||
<!-- style：动态样式，运行时解析，尽量避免静态样式写在 style 中 -->
|
||
<view style="color:{{color}};"/>
|
||
|
||
<!-- class：静态样式写在 class 中 -->
|
||
<view class="normal_view"/>
|
||
```
|
||
|
||
### 全局样式与局部样式
|
||
- `app.wxss` 为全局样式，作用于每个页面
|
||
- 页面的 `.wxss` 只对当前页面生效，会覆盖 `app.wxss` 中相同的选择器
|
||
|
||
## WXS（WeiXin Script）
|
||
|
||
WXS 是小程序的一套脚本语言，可以在 WXML 中使用。**WXS 运行在视图层**，比 JS 逻辑层快（不需要跨线程通信）。
|
||
|
||
```xml
|
||
<!-- 内联 WXS -->
|
||
<wxs module="m1">
|
||
var msg = "hello world";
|
||
module.exports.message = msg;
|
||
</wxs>
|
||
<view>{{m1.message}}</view>
|
||
|
||
<!-- 外部 WXS 文件 -->
|
||
<wxs src="./tools.wxs" module="tools"/>
|
||
<view>{{tools.msg}}</view>
|
||
<view>{{tools.bar(tools.FOO)}}</view>
|
||
```
|
||
|
||
```javascript
|
||
// tools.wxs
|
||
var foo = "'hello world' from tools.wxs"
|
||
var bar = function(d) {
|
||
return d
|
||
}
|
||
module.exports = {
|
||
FOO: foo,
|
||
bar: bar,
|
||
}
|
||
// ⚠️ WXS 不支持 ES6 语法（箭头函数、let/const、解构等）
|
||
// ⚠️ WXS 中不能调用小程序 API（wx.xxx）
|
||
```
|
||
|
||
**WXS 典型用途**：
|
||
- 格式化数据（日期、金额、文本截断）
|
||
- 在视图层做简单计算，避免 setData 开销
|
||
- 响应事件（WXS 事件响应，iOS 上性能更好）
|
||
|
||
## 事件系统
|
||
|
||
### 事件分类
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| 冒泡事件 | 向父节点传递 | tap, longpress, touchstart, touchmove, touchend, touchcancel |
|
||
| 非冒泡事件 | 不向父节点传递 | submit, input, scroll 等组件特有事件 |
|
||
|
||
### 事件绑定
|
||
|
||
```xml
|
||
<!-- bind：不阻止冒泡 -->
|
||
<view bindtap="handleTap">Click me</view>
|
||
<view bind:tap="handleTap">Click me</view>
|
||
|
||
<!-- catch：阻止冒泡 -->
|
||
<view catchtap="handleTap">Click me</view>
|
||
|
||
<!-- mut-bind：互斥事件绑定（基础库 2.8.2+） -->
|
||
<view mut-bind:tap="handleTap">
|
||
<button mut-bind:tap="handleButtonTap">按钮</button>
|
||
</view>
|
||
<!-- 同一冒泡路径上的 mut-bind 只会有一个被触发 -->
|
||
|
||
<!-- capture-bind：捕获阶段绑定 -->
|
||
<view capture-bind:tap="handleCapture">
|
||
<view bindtap="handleTap">inner</view>
|
||
</view>
|
||
|
||
<!-- capture-catch：捕获阶段中断 -->
|
||
<view capture-catch:tap="handleCapture">
|
||
<view bindtap="handleTap">inner（不会触发）</view>
|
||
</view>
|
||
```
|
||
|
||
### 事件对象
|
||
|
||
```javascript
|
||
Page({
|
||
handleTap(e) {
|
||
e.type // 事件类型，如 "tap"
|
||
e.timeStamp // 事件生成时的时间戳
|
||
e.target // 触发事件的源组件（可能是子组件）
|
||
e.currentTarget // 事件绑定的当前组件
|
||
e.detail // 额外信息，如 tap 的 { x, y }
|
||
e.touches // 触摸事件的触摸点信息数组
|
||
e.changedTouches // 变化的触摸点信息数组
|
||
e.mark // 事件标记（基础库 2.7.1+）
|
||
|
||
// target 和 currentTarget 的区别
|
||
e.target.id // 触发事件的组件 id
|
||
e.target.dataset // 触发事件的组件的 data-xxx 属性集合
|
||
e.currentTarget.id // 绑定事件的组件 id
|
||
e.currentTarget.dataset
|
||
}
|
||
})
|
||
```
|
||
|
||
### dataset
|
||
|
||
```xml
|
||
<!-- data-xxx 属性传递数据 -->
|
||
<view data-alpha-beta="1" data-alphaBeta="2" bindtap="handleTap">
|
||
Click
|
||
</view>
|
||
```
|
||
|
||
```javascript
|
||
handleTap(e) {
|
||
e.currentTarget.dataset.alphaBeta // "1"（连字符转驼峰）
|
||
e.currentTarget.dataset.alphabeta // "2"（大写转小写）
|
||
}
|
||
```
|
||
|
||
### mark（基础库 2.7.1+）
|
||
|
||
```xml
|
||
<!-- mark 可以在冒泡路径上所有节点收集 -->
|
||
<view mark:myMark="last" bindtap="bindViewTap">
|
||
<button mark:anotherMark="leaf" bindtap="bindButtonTap">按钮</button>
|
||
</view>
|
||
```
|
||
|
||
```javascript
|
||
bindButtonTap(e) {
|
||
e.mark // { myMark: "last", anotherMark: "leaf" }
|
||
// mark 会合并冒泡路径上所有的 mark
|
||
}
|
||
```
|
||
|
||
## 在线查询
|
||
|
||
如需更详细信息，可抓取：
|
||
- WXML 语法：https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/
|
||
- WXSS：https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html
|
||
- WXS：https://developers.weixin.qq.com/miniprogram/dev/reference/wxs/
|
||
- 事件：https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxml/event.html
|