一、前言在小程序开发中一个页面代码量很大时可以把页眉、正文、页脚、扩展模块拆分成独立的 wxml 片段文件使用include标签引入复用。include的作用将目标 wxml 中除template、wxs以外的全部内容直接拷贝渲染到当前标签所在位置非常适合拆分静态 UI 片段减少重复代码。本案例实现效果将页面拆分为header.wxml、main.wxml、footer.wxml、expand.wxml四个独立片段使用include引入页眉、正文、页脚展示 2026 重大科技进展作业扩展增加两个按钮显示 / 隐藏拓展阅读模块通过wx:if控制被 include 引入的片段是否渲染还原 PPT 样式绿色功能按钮粉色边框容器。⚠️重要注意include标签本身不支持wx:if条件判断条件判断需要写在外层block标签上。二、项目目录结构file_test ├─ files # 被include引入的wxml片段文件夹 │ ├─ header.wxml │ ├─ main.wxml │ ├─ footer.wxml │ └─ expand.wxml # 拓展阅读片段 ├─ pages/index │ ├─ index.js │ ├─ index.json │ ├─ index.wxml │ └─ index.wxss ├─ app.js └─ app.json新建项目选择不使用云服务不使用模板项目存放路径不能包含中文否则会出现文件读取报错。三、代码app.json{ pages: [ pages/index/index ], window: { navigationBarTextStyle: black, navigationStyle: custom }, style: v2, renderer: webview, componentFramework: glass-easel, sitemapLocation: sitemap.json, lazyCodeLoading: requiredComponents }files/header.wxmlview classtitle text stylefont-size:34rpx; font-weight:bold; color:#224499;2026 年重大科技进展/text /viewfiles/main.wxmlview classcontent view stylemargin:20rpx 0;天问二号小行星探测2026.7、轻舟试验飞船2026.3.30发射、地月双向高速激光通信验证2026.8、中国空间站常态化运营、九章四号光量子原型机2026.5、AI辅助新药靶点发现、多模态大模型向工业落地深化、核光钟研制成功、柔性光子芯片/view view styletext-align:right; font-size:24rpx;2026年10月17日/view /viewfiles/expand.wxmlview classexpand-box stylepadding:20rpx; background:#fff; view stylemargin-bottom:10rpx;拓展阅读我国航天后续重大规划/view view1、天问三号火星采样返回任务/view view2、载人登月工程/view view3、大型空间基础设施建设/view /viewpages/index/index.wxml核心知识点include src/files/xxxsrc填写片段的绝对路径include不能直接加wx:if条件渲染写在外层block虚拟节点按钮bindtap绑定点击事件修改布尔变量控制拓展模块显隐。view classcontainer view classbox include src/files/header/include include src/files/main/include /view view classbtn-group button bindtapshowExpand显示扩展内容/button button bindtaphideExpand隐藏扩展内容/button /view !-- include写在block内部block做条件判断 -- block wx:if{{showExpandFlag}} include src/files/expand/include /block /viewpages/index.index.json{ navigationBarTitleText: 文件引用 }/**index.wxss**/ .container{ padding:20rpx; } .box{ border:2rpx solid #d67890; padding:30rpx; margin-bottom:20rpx; text-align:center; } .btn-group{ display:flex; gap:20rpx; margin-bottom:20rpx; } .btn-group button{ flex:1; background-color:#39c568; color:#fff; }四、实现效果五、核心知识点解析1. include 文件引用include会把目标 wxml 的标签内容原地复制渲染❗不会引入 template 模板、wxs 脚本src路径支持绝对路径/files/xxx或者相对路径适合静态 UI 片段页眉、页脚、弹窗模块。2. include wx:if 的坑高频易错❌错误写法!-- include标签本身不能写wx:if不生效 -- include wx:if{{flag}} src/files/expand/include✅正确写法外层套block虚拟节点block wx:if{{showExpandFlag}} include src/files/expand/include /blockblock是虚拟节点不会生成真实 DOM只做逻辑分组。3. 视图更新 setData修改data中的showExpandFlag必须使用this.setData()直接赋值this.data.showExpandFlagtrue页面不会刷新。六、作业扩展需求实现说明新建独立expand.wxml存放拓展阅读内容使用include引入拓展阅读片段两个按钮绑定 tap 事件修改布尔变量block wx:if控制整个 include 片段渲染 / 销毁实现点击显示、点击隐藏。七、踩坑记录unexpected character非法字符报错直接从 PPT、Word 复制代码会携带看不见的特殊不可见字符。解决粘贴到记事本中转一次再复制进开发者工具不要复制带中文注释的片段。路径错误找不到被 include 的文件src路径写错注意根目录 files 文件夹写绝对路径/files/xxx。给 include 写 wx:if 不生效条件判断移到外层 block 虚拟节点。项目路径包含中文会报找不到project.config.json整个项目文件夹必须使用英文命名。按钮没有绿色需要给 button 设置background-color和color:#fff文字白色。八、总结include是小程序实现 UI 片段复用的基础手段适合拆分静态页面模块减少重复代码。要记住它的限制条件渲染不能直接写在 include 标签需要借助block虚拟节点包裹。
