WXML（WeiXin Markup Language）语法基础
以下是对 WXML（WeiXin Markup Language）语法基础 的全面整理，涵盖所有列出的知识点，每个知识点均附有 详细说明 和 带注释的案例代码，最后还提供 综合性案例 供参考。
一、WXML 文件介绍
WXML 是微信小程序的结构描述语言，类似于 HTML，但专为小程序设计，配合 WXSS（样式）、JS（逻辑）和 JSON（配置）共同构建页面。
<!-- pages/index/index.wxml --><view class="container"><text>Hello WXML!</text></view>注：WXML 文件必须放在
pages目录下，并在app.json中注册。
二、数据绑定
1. 简单内容绑定
使用双大括号 {{}} 将 JS 中的 data 数据绑定到 WXML。
<!-- WXML -->
<view>{{ message }}</view>// pages/index/index.js
Page({
data: {
message: "欢迎使用 WXML 数据绑定！"
}
})注：
{{}}中可写简单表达式（如{{ a + b }}），但不能写复杂语句。
2. 属性绑定
将动态值绑定到组件属性上，使用 {{}} 包裹。
<image src="{{ imageUrl }}" mode="aspectFit"></image>
<view class="{{ dynamicClass }}">动态样式类</view>Page({
data: {
imageUrl: "/images/logo.png",
dynamicClass: "highlight"
}
})注：属性值若为字符串常量，无需
{{}}；若为变量或表达式，必须用{{}}。
三、模板运算
1. 简单表达式
支持三元运算、字符串拼接、数组/对象访问等。
<view>{{ flag ? '显示' : '隐藏' }}</view>
<view>{{ 'Hello, ' + name }}</view>
<view>{{ list[0].title }}</view>
<view>{{ a + b }}</view>Page({
data: {
flag: true,
name: "小明",
list: [{ title: "第一条" }],
a: 10,
b: 20
}
})注：不支持函数调用、new、this 等复杂操作。
四、标记的公共属性
所有组件都支持以下公共属性：
id：组件唯一标识class：样式类style：内联样式hidden：是否隐藏（仍占位）data-*：自定义数据（用于事件传递）
<view id="main" class="box" style="color: red;" hidden="{{ isHidden }}" data-user-id="123">公共属性示例
</view>Page({
data: {
isHidden: false
}
})五、条件渲染
1. 基础语法：wx:if / wx:elif / wx:else
根据条件决定是否渲染节点。
<view wx:if="{{ type === 1 }}">类型1</view>
<view wx:elif="{{ type === 2 }}">类型2</view>
<view wx:else>其他类型</view>Page({
data: {
type: 2
}
})注：
wx:if是“惰性渲染”，条件为 false 时不创建节点。
2. 条件渲染与 hidden 属性对比
wx:if：条件为 false 时不渲染节点（适合运行时条件变化少的场景）hidden：始终渲染，仅视觉隐藏（适合频繁切换的场景）
<!-- 频繁切换用 hidden -->
<view hidden="{{ showTip }}">提示信息（频繁显示/隐藏）</view><!-- 初次加载后很少变用 wx:if --><view wx:if="{{ hasPermission }}">权限区域</view>六、列表渲染
1. 基本语法：wx:for
遍历数组或对象。
<view wx:for="{{ items }}" wx:key="id">{{ index }}: {{ item.name }}
</view>Page({
data: {
items: [
{ id: 1, name: "苹果" },
{ id: 2, name: "香蕉" }
]
}
})默认变量名：
item（当前项）、index（索引）
可通过wx:for-item和wx:for-index自定义：
<view wx:for="{{ users }}" wx:for-item="user" wx:for-index="i" wx:key="userId">{{ i }} - {{ user.name }}
</view>2. key 属性
用于提升列表渲染性能，建议使用唯一且稳定的字段（如 ID）。
<checkbox-group wx:for="{{ tasks }}" wx:key="taskId">
<checkbox value="{{ item.taskId }}">{{ item.title }}</checkbox>
</checkbox-group>若无唯一 ID，可用
wx:key="*this"（仅当列表项为字符串或数字时）
七、模板与引用
1. WXML 模板（<template>）
定义可复用的代码块。
<!-- 定义模板 --><template name="productCard"><view class="card"><text>{{ name }}</text><text>¥{{ price }}</text></view></template><!-- 使用模板 --><template is="productCard" data="{{ ...product }}"></template>Page({
data: {
product: { name: "手机", price: 2999 }
}
})
data="{{ ...obj }}"表示将 obj 的所有属性展开传入模板。
2. WXML 引用（<import> / <include>）
import：引用模板（需配合is使用）include：直接嵌入整个 WXML 文件内容
<!-- 引用模板文件 --><import src="../templates/card.wxml" /><template is="productCard" data="{{ ...item }}" /><!-- include 示例：嵌入 footer.wxml --><include src="../common/footer.wxml" />注意：
import有作用域，include无作用域，直接合并代码。
八、事件处理
1. 什么是事件
用户操作（点击、滑动等）触发的响应机制。
2. 事件类型和事件对象
常见事件：
bindtap：点击bindinput：输入框内容变化bindchange：选择器值变化
事件对象 event 包含：
target：触发事件的组件currentTarget：绑定事件的组件detail：附加信息（如 input 的 value）
3. 事件绑定与冒泡/捕获
bind：冒泡阶段触发（常用）catch：阻止冒泡capture-bind/capture-catch：捕获阶段
<view bindtap="handleViewTap" data-id="100">点击我（会冒泡）
</view><view catchtap="handleCatchTap">点击我（阻止冒泡）
</view>Page({
handleViewTap(e) {
console.log("点击了", e.currentTarget.dataset.id); // 输出: 100
},
handleCatchTap(e) {
console.log("阻止冒泡的点击");
}
})自定义数据通过
data-*传递，JS 中通过e.currentTarget.dataset获取（自动转为驼峰）。
九、本章小结（核心要点）
- WXML 使用
{{}}进行数据绑定 - 条件渲染用
wx:if，频繁切换用hidden - 列表渲染必须加
wx:key提升性能 - 模板用
<template>+<import>复用 - 事件通过
bind/catch绑定，可传参和阻止冒泡
十、综合性案例
场景：商品列表页（含条件渲染、列表渲染、事件、模板）
1. WXML（pages/product/product.wxml）
<!-- 引入商品卡片模板 --><import src="../../templates/productCard.wxml" /><view class="container"><!-- 加载状态 --><view wx:if="{{ loading }}">加载中...</view><!-- 无数据提示 --><view wx:elif="{{ products.length === 0 }}">暂无商品</view><!-- 商品列表 --><view wx:else><block wx:for="{{ products }}" wx:key="id"><!-- 使用模板渲染商品 --><template is="productCard" data="{{ ...item, onSale: item.price < 100 }}" /></block></view><!-- 刷新按钮 --><button bindtap="refreshList" hidden="{{ loading }}">刷新</button></view>2. 模板文件（templates/productCard.wxml）
<template name="productCard"><view class="product-item" bindtap="onProductClick" data-product-id="{{ id }}"><text>{{ name }}</text><text class="{{ onSale ? 'on-sale' : '' }}">¥{{ price }}</text><text wx:if="{{ onSale }}" style="color: red;">特价！</text></view>
</template>3. JS 逻辑（pages/product/product.js）
Page({
data: {
loading: false,
products: []
},
onLoad() {
this.loadProducts();
},
loadProducts() {
this.setData({ loading: true });
// 模拟异步请求
setTimeout(() => {
this.setData({
products: [
{ id: 1, name: "牛奶", price: 80 },
{ id: 2, name: "面包", price: 120 },
{ id: 3, name: "鸡蛋", price: 60 }
],
loading: false
});
}, 1000);
},
refreshList() {
this.loadProducts();
},
onProductClick(e) {
const productId = e.currentTarget.dataset.productId;
wx.showToast({ title: `点击了商品 ${productId}` });
}
});4. WXSS（简略）
.product-item {
padding: 20rpx;
border-bottom: 1px solid #eee;
}
.on-sale {
font-weight: bold;
}✅ 此综合案例涵盖了：
- 数据绑定（
{{}}） - 条件渲染（
wx:if/wx:elif/wx:else） - 列表渲染（
wx:for+wx:key） - 模板定义与引用（
<template>+<import>） - 事件绑定与传参（
bindtap+data-*） - 属性动态绑定（
class条件样式）
如有需要，还可扩展 表单绑定、slot 插槽（在自定义组件中）等进阶内容。以上内容已覆盖 WXML 核心语法体系。