WXML 格式化：小程序模板代码排版与常见写法错误

WXML 和 HTML 有什么区别

微信小程序用的模板语言叫 WXML（WeiXin Markup Language），看起来跟 HTML 长得很像，但有不少细节不一样。很多刚从前端转过来的同学容易按 HTML 的习惯去写，结果编译报错或者渲染异常。下面这张表整理了主要的语法差异：

最大的区别在于 WXML 引入了以 wx: 开头的指令来做条件判断和循环遍历，而 HTML 本身不具备这些能力，需要依赖 Vue / React 这类框架来实现类似效果。另外 WXML 对标签闭合的要求比 HTML 严格得多，HTML 里 <img> 不加斜杠也能跑，但在 WXML 里 <image> 必须写成 <image />，否则编辑器会标红。

WXML 格式化前后有什么区别

手写的 WXML 经常缩进混乱、属性排列随意，看着费劲也不利于团队协作。格式化工具的作用就是把这些整理成统一的风格。来看一个实际的例子：

格式化前

<view wx:if="{{showBanner}}"><image src="{{bannerImg}}" mode="aspectFill" class="banner-img"/><text class="title" >{{title}}</text></view>
<view wx:for="{{items}}" wx:key="id"><view class="item"><text>{{item.name}}</text><text class="desc">{{item.desc}}</text></view></view>

格式化后

<view wx:if="{{showBanner}}">
  <image src="{{bannerImg}}" mode="aspectFill" class="banner-img" />
  <text class="title">{{title}}</text>
</view>

<view wx:for="{{items}}" wx:key="id">
  <view class="item">
    <text>{{item.name}}</text>
    <text class="desc">{{item.desc}}</text>
  </view>
</view>

格式化后的代码每个层级都有清晰的缩进，标签之间有换行分隔，属性排列整齐。这在项目代码量变大之后尤其重要——别人接手维护的时候不用花时间猜这段结构到底嵌套了几层。

新手常犯的几个错误

下面这些坑是新手写小程序时经常踩的，大部分跟 WXML 和 HTML 的差异有关。

1. image 标签忘记闭合

<!-- 错误写法 -->
<image src="/images/logo.png">

<!-- 正确写法 -->
<image src="/images/logo.png" />

微信小程序里 image 是一个组件，必须自闭合。漏掉斜杠在某些情况下不会立刻报错，但会导致后续元素解析错位。

2. 把 onclick 当成事件绑定

<!-- 错误写法 -->
<button onclick="handleClick()">提交</button>

<!-- 正确写法 -->
<button bindtap="handleClick">提交</button>

WXML 里绑定事件用 bind 或 catch 开头的属性，onclick、onchange 这些 HTML 事件在这里不生效。bindtap 相当于 click，bindinput 相当于 input 事件的监听。

3. pagePath 没有注册到 app.json

新建了一个页面但忘了在 app.json 的 pages 数组里添加路径，导致页面无法被访问或跳转时报错。这是一个很常见的遗漏，尤其是复制粘贴别人的页面代码过来的时候。

4. wx:for 和 wx:if 同时用在同一个标签上

<!-- 性能不理想的写法 -->
<view wx:if="{{showList}}" wx:for="{{list}}" wx:key="id">
  {{item.name}}
</view>

<!-- 更好的做法是把 wx:if 放到外层 -->
<block wx:if="{{showList}}">
  <view wx:for="{{list}}" wx:key="id">
    {{item.name}}
  </view>
</block>

wx:if 和 wx:for 放在同一个标签上虽然能用，但每次渲染都会重复判断条件。用 <block> 包裹一层把条件判断提到外面，可以减少不必要的运算。

5. 数据绑定的双花括号漏掉

有时候写着写着就直接写了 src="url" 而忘了应该是 src="{{url}}"。WXML 里变量必须用双花括号包裹，否则会被当成纯字符串处理。

微信开发者工具和在线格式化工具有什么区别

微信开发者工具其实内置了格式化功能，快捷键通常是 Shift + Alt + F（Windows）。它的好处是不用离开编辑器，保存时还能自动触发。

在线格式化工具有它自己的适用场景：

• 别人发给你一段乱糟糟的 WXML 代码，你想快速看看结构
• 不在自己的开发环境上，没有装微信开发者工具
• 想把格式化后的代码贴到文档或聊天窗口里给别人看
• 批量处理多个文件的格式化需求

两者并不冲突，日常开发用 IDE 内置功能，临时处理用线上工具，各管各的场景就好。

常见问题