---
description: 微信小程序 WXML 编写规范
globs: **/*.wxml
alwaysApply: false
---
# WXML 编写规范

## 基本语法规范
- 使用小写标签名和属性名
- 属性值必须用双引号包围
- 自闭合标签使用 `<tag />` 格式
- 保持标签的正确嵌套和闭合
- 合理使用缩进，保持代码层次清晰

## 数据绑定
- 使用 `{{}}` 进行数据绑定，表达式内避免复杂逻辑
- 布尔属性使用 `attr="{{condition}}"` 格式
- 事件绑定使用 `bind:` 或 `catch:` 前缀
- 避免在模板中进行复杂的数据处理，应在 JS 中预处理

## 条件渲染
- 简单条件使用 `wx:if`，复杂条件在 JS 中处理后绑定布尔值
- `wx:if` 与 `hidden` 的选择：频繁切换用 `hidden`，条件较少变化用 `wx:if`
- 多条件分支使用 `wx:if`、`wx:elif`、`wx:else`
- 避免过深的条件嵌套，考虑拆分为子组件

## 列表渲染
- 必须设置 `wx:key`，优先使用唯一标识符
- `wx:for-item` 和 `wx:for-index` 使用有意义的名称
- 避免在循环中嵌套复杂逻辑，考虑使用子组件
- 长列表考虑使用虚拟列表或分页加载

## 组件使用
- 组件标签名使用 kebab-case 格式
- 属性传递使用描述性名称
- 事件监听使用 `bind:` 前缀，事件名使用 kebab-case
- 合理使用 slot 进行内容分发

## 样式类名
- 类名使用 kebab-case 格式
- 避免使用内联样式，统一在 WXSS 中定义
- 使用 TDesign 提供的工具类和组件类名
- 自定义类名应具有语义化

## 性能优化
- 减少不必要的节点嵌套
- 合理使用 `wx:if` 和 `hidden` 控制渲染
- 避免在模板中使用复杂表达式
- 图片懒加载使用 `lazy-load` 属性

## 无障碍访问
- 为交互元素添加 `aria-label` 属性
- 使用语义化标签，如 `button`、`navigator` 等
- 确保键盘导航的可用性
- 为图片添加 `alt` 属性描述

## 代码组织
- 模板结构应与页面/组件的逻辑结构保持一致
- 相关的元素应当组织在一起
- 使用注释标记复杂的模板区块
- 保持模板的简洁性，复杂逻辑拆分为子组件