文件引用实践

前言

在真实项目中，一个页面的 WXML 往往会越写越长。如果所有结构都堆在一个文件里，维护起来会很痛苦。小程序的 WXML 提供了把公共片段拆成独立文件、再在页面里引用的能力，本篇就用一个"科技进展简报"页面来演示include的用法。

项目结构

text

├── app.js ├── app.json ├── app.wxss ├── sitemap.json ├── components/ │ └── navigation-bar/ # 自定义导航栏（复用之前项目） ├── files/ # WXML 片段目录 │ ├── header.wxml │ ├── main.wxml │ ├── footer.wxml │ ├── extend.wxml │ └── expand.wxml └── pages/ └── index/ ├── index.js ├── index.json ├── index.wxml └── index.wxss

我把所有可复用的 WXML 片段统一放在files/目录下，页面通过include src="/files/xxx.wxml"引入。注意路径以/开头表示从项目根目录算起。

一、页面逻辑（index.js）

javascript

Page({ data: { // 控制扩展阅读是否显示，初始默认隐藏 isShowExtend: false }, // 显示扩展内容 showExtend() { this.setData({ isShowExtend: true }) }, // 隐藏扩展内容 hideExtend() { this.setData({ isShowExtend: false }) } })

逻辑非常直白：一个布尔开关isShowExtend，两个按钮分别把它置为true/false。

二、页面结构（index.wxml）

xml

<navigation-bar title="文件引用" back="{{false}}" color="black" background="#FFF"></navigation-bar> <scroll-view class="scrollarea" scroll-y type="list"> <view class="box"> <include src="/files/header.wxml"/> <include src="/files/main.wxml"/> <include src="/files/footer.wxml"/> </view> <view class="btn-group"> <button bind:tap="showExtend">显示扩展内容</button> <button bind:tap="hideExtend">隐藏扩展内容</button> </view> <block wx:if="{{isShowExtend}}"> <include src="/files/extend.wxml"/> </block> </scroll-view>

这里的关键写法：

• 头部、正文、页脚三个片段用三个<include>依次拼接，整段结构清晰得像搭积木。

• 扩展阅读片段包在<block wx:if="{{isShowExtend}}">里，实现"按钮控制显示/隐藏"。

• 注意<include>是自闭合标签，src属性指向 WXML 文件路径。

三、各个片段文件

头部片段（header.wxml）

xml

<!--header.wxml 头部片段--> <view class="header"> 2026 年重大科技进展 </view>

正文片段（main.wxml）

xml

<!--main.wxml 正文片段--> <view class="main"> 天问二号小行星探测（2026.7）、轻舟试验飞船（2026.3.30发射）、地月双向高速激光通信验证（2026.8）、中国空间站常态化运营、九章四号光量子原型机（2026.5）、AI辅助新药靶点发现、多模态大模型向工业落地深化、核光钟研制成功、柔性光子芯片 </view>

页脚片段（footer.wxml）

xml

<!--footer.wxml 页脚片段--> <view class="footer"> 2026年10月17日 </view>

扩展阅读片段（extend.wxml）

xml

<!--extend.wxml 拓展阅读片段--> <view class="box extend-box"> <view>拓展阅读：我国航天后续重大规划</view> <view>1、天问三号火星采样返回任务</view> <view>2、载人登月工程</view> <view>3、大型空间基础设施建设</view> </view>

另一个扩展片段（expand.wxml）

xml

<!-- expand.wxml --> <view class="expand" wx:if="{{showExpand}}"> <view>拓展阅读：我国航天后续重大规划</view> <view>1、天问三号火星采样返回任务</view> <view>2、载人登月工程</view> <view>3、大型空间基础设施建设</view> </view>

注意：extend.wxml和expand.wxml内容几乎一样，区别是前者由页面层的wx:if控制显示，后者自己内部带wx:if="{{showExpand}}"。这个对比很有教学意义，后面会展开讲。

四、样式

app.wxss（全局）

css

.box { margin: 20rpx; padding: 20rpx; border: 6rpx solid #F4C2C8; } .header { text-align: center; margin: 20rpx; color: #1E40AF; font-size: x-large; font-weight: bolder; } .main { font-size: large; text-indent: 2em; margin: 20rpx; line-height: 2em; text-align: justify; color: #475569; } .footer { margin-right: 30rpx; font-size: medium; text-align: right; color: #475569; } .extend-box { margin-top: 20rpx; } .btn-group { display: flex; gap: 20rpx; margin: 20rpx; } button { flex: 1; background-color: #39c5bb; color: #fff; }

几个值得说的点：

• font-size: x-large/large/medium：这些都是 CSS 关键字字号，比写死px更语义化，配合rpx体系也能自适应。

• .main的text-indent: 2em：实现中文段落首行缩进两个字符，是很标准的中文排版写法。

• text-align: justify：两端对齐，正文观感更整齐。

• .btn-group的 flex +gap：两个按钮并排、等宽（flex: 1）且有间距，比用margin互推干净得多。

• 主题色#39c5bb：初音绿（蓝绿色），清新好看。

index.wxss（页面级）

css

page { height: 100vh; display: flex; flex-direction: column; } .scrollarea { flex: 1; }

老规矩，page撑满全屏 flex 布局，scroll-view用flex: 1撑满剩余高度，保证内容可滚动。

五、核心知识点：include 到底怎么工作

include是"整体替换"

<include src="xxx.wxml"/>的语义是：把目标文件的全部内容（除<template>/<wxs>之外）原样替换到这个位置。

所以：

xml

<view class="box"> <include src="/files/header.wxml"/> ... </view>

编译后等价于：

xml

<view class="box"> <view class="header">2026 年重大科技进展</view> ... </view>

片段里的class="header"会直接参与页面样式计算，所以app.wxss里的.header能正常生效。样式是跟着类名走的，不跟着文件走，这是理解 include 的关键。

include 与 import 的区别

这是面试和实战中常被问到的对比：

简单记：include是"贴进来"，import是"导入模板定义"。本文演示的是include，适合头部/正文/页脚这种纯静态或共享页面数据的场景。

src路径的写法

• /files/header.wxml：以/开头，从项目根目录算起，最稳妥，推荐使用。

• 相对路径（如../../files/header.wxml）也可以，但容易数错层级，不建议。

六、一个有意思的对比：wx:if 放页面还是放片段

项目里有两个几乎一样的片段，正好拿来对比：

方案 A（extend.wxml，推荐）：条件放在页面层

xml

<block wx:if="{{isShowExtend}}"> <include src="/files/extend.wxml"/> </block>

• 片段文件是"傻瓜式"的纯结构，谁引用都能直接用。

• 控制逻辑集中在一个地方，好排查。

方案 B（expand.wxml）：条件写在片段内部

xml

<view class="expand" wx:if="{{showExpand}}">...</view>

• 片段自带显示逻辑，但要求引用它的页面必须提供showExpand这个 data 字段，否则wx:if会因变量未定义而永远为假，导致内容不显示。

• 片段与页面数据产生了隐式耦合，复用性变差。

结论：纯展示型片段尽量保持"无状态"，把wx:if这类控制逻辑留在页面层；只有片段确实需要自管理显示逻辑时，才把条件写进去。这个原则在拆分 WXML 时非常实用。

七、踩坑记录

1. include 不会引入<template>和<wxs>

如果片段文件里写了<template>或<wxs>，include会忽略它们。需要复用模板的话请改用import。

2. 片段里的变量来自引用它的页面

include进来的片段没有独立数据作用域，它用到的{{xxx}}都从当前页面的 data 里取。所以像方案 B 那样在片段里写wx:if="{{showExpand}}"，页面就必须有showExpand这个字段。

3.scroll-view里放 include 没问题，但要注意结构

scroll-view只对直接子节点做滚动布局。本例中所有内容（包括 include 进来的片段）都在scroll-view内，整体滚动正常。但如果把 include 放在scroll-view外面的兄弟位置，就要重新考虑滚动区域的划分了。

4. 类名冲突要留意

因为 include 是"贴进来"的，片段里的类名会和页面、其他片段共享同一个样式作用域。所以片段里的类名最好带点前缀或语义，避免和别处冲突。本例用.header/.main/.footer/.extend-box，语义清晰且互不干扰。

5.font-size: x-large在小程序里能用

虽然一些资料说小程序对部分 CSS 关键字支持有限，但x-large/large/medium在 WebView 渲染下实测可用（本项目renderer为skyline，但相关字号关键字同样生效）。如果担心兼容性，也可以换成32rpx之类的具体值。

八、效果预览

运行后的效果：

• 顶部：自定义导航栏，标题"文件引用"。

• 粉色边框卡片：由header.wxml、main.wxml、footer.wxml三块拼成——蓝色加粗居中的大标题、首行缩进两端对齐的正文、右下角灰色日期。

• 两个并排的绿色按钮："显示扩展内容"和"隐藏扩展内容"。

• 点击"显示扩展内容"：下方出现一个带粉色边框的扩展阅读卡片，列出我国航天后续三大规划；点击"隐藏"则消失。

整个页面没有任何一处结构是"手动复制粘贴"出来的，全部靠片段组合，改一处片段，所有引用它的地方同步生效。

九、总结

本文用一个科技简报页面，把 WXML 文件引用的核心用法串了一遍：

• <include>整体引入：适合页头、正文、页脚这类静态或共享页面数据的片段。

• includevsimport：前者"贴内容"，后者"导模板"，别混用。

• src用绝对路径：以/开头从根目录算，最稳妥。

• 片段保持无状态：wx:if等控制逻辑优先放页面层，片段只负责结构。