hello-uniapp 中的 uni-title 章节标题组件：从属性配置到统计上报的完整实践指南-平芜编程栈

示例工程
前端

【免费下载链接】hello-uniapp

uni-app框架演示示例

项目地址：https://gitcode.com/gh_mirrors/he/hello-uniapp

uni-title（代码块uTitle）是 uni-ui 提供的一款章节标题组件，通常用于记录页面标题；在 uni-app 开启统计功能时，使用该组件会自动上报页面标题数据。本文以 hello-uniapp 开源仓库中的 uni-title 组件源码与示例页为核心，完整讲解组件属性、多端样式实现、统计上报机制、示例运行方式，并延伸到与其同族的 uni-section、uni-group 等标题类组件的用法对比，帮助你在自己的 uni-app 项目中快速落地、准确选型。

组件定位：为什么需要 uni-title

在 hello-uniapp 的 uni-title 组件说明文档中，组件被定义为"章节标题"，通常用于记录页面标题。它有三个最直接的用途：

页面内容分区：在长页面中为不同章节提供层级清晰的标题，替代手写<view>+<text>的样式组合；
统一视觉规范：通过type属性天然提供 h1～h5 五个层级的字号、字重规范，保证全项目标题风格一致；
自动统计上报：uni-app 开启统计后，组件会在挂载和标题内容变化时自动调用uni.report('title', title)上报页面标题，让统计平台自动采集页面浏览情况。

从源码结构看，该组件完全由单文件组件 uni-title.vue 实现，不依赖图片资源，因此跨端体积极小、渲染稳定。它属于 uni-ui 通用组件，在 package.json 中声明了 App（vue/nvue）、H5 与各大小程序平台的支持，同时兼容 Vue2 / Vue3，这也是它在 hello-uniapp 各页面中被广泛使用的前提。

属性总览与默认值

组件源码中的 props 定义（见 uni-title.vue）完整说明了 5 个对外属性，整理如下：

属性	类型	默认值	说明
`type`	String	`''`	标题类型，取值为`h1`～`h5`，对应一级到五级标题；不填则使用基础样式
`title`	String	`''`	标题内容，渲染为组件内文本
`align`	String	`'left'`	对齐方式，取值为`left`/`center`/`right`
`color`	String	`'#333333'`	字体颜色，任意合法的 CSS 颜色值
`stat`	Boolean/String	`''`	是否开启统计上报；不填`type`时默认为开启，填写`type`后默认为关闭

type：五级标题体系

type决定标题的层级视觉样式，源码中对应 5 个样式类.uni-h1～.uni-h5（见 uni-title.vue），字号与字重如下：

取值	样式类	字号	字重
`h1`	`.uni-h1`	20px	bold
`h2`	`.uni-h2`	18px	bold
`h3`	`.uni-h3`	16px	bold
`h4`	`.uni-h4`	14px	bold
`h5`	`.uni-h5`	12px	bold

不传type时，组件使用基础样式.uni-title__base（15px、字重 500、颜色 #333），此时视觉上比 h5 略大，适合作为无层级要求的普通小节标题。

align：对齐方式的实现

align属性并不会直接写入内联样式，而是通过 computed 属性textAlign转换为 flex 布局的align-items值：

left→flex-start
center→center
right→flex-end

组件根节点.uni-title__box使用flex-direction: column并绑定align-items: textAlign，因此标题会在容器内按指定方向对齐。这里值得注意：hello-uniapp 的示例页在 App 端（nvue）也能正常渲染该组件，因为源码中通过#ifndef APP-NVUE条件编译包裹了display: flex，确保 nvue 下走原生 flex 布局、非 nvue 平台保留 flex 声明，这正是 uni-app 条件编译在组件层的一个典型应用。

color：颜色覆盖

color默认#333333，直接以内联样式绑定在文本节点上（{'color': color}），优先级高于样式表中的颜色声明，因此可以覆盖 h1～h5 各层级的默认#333。

stat：统计开关的判定逻辑

stat是组件中最有"心机"的一个属性，其实际生效逻辑位于isOpenStat()方法（见 uni-title.vue），规则如下：

当type为空时，统计默认开启；此时显式传入stat="false"可以关闭；
当type非空时，统计默认关闭；只有传入stat为布尔true或非空字符串（如stat="true"）才开启；
stat属性声明类型为[Boolean, String]，便于在模板中既可以用:stat="true"传布尔值，也可以用stat="true"传字符串。

这一设计意味着：只用它做普通章节标题时不产生多余上报；只有想借助组件做页面标题统计时才需要显式开启。

统计上报机制：uni.report 的调用时机

组件与统计能力关联的核心逻辑在watch与mounted两处（见 uni-title.vue）：

mounted时：若isOpenStat()判定为开启，且环境存在uni.report，立即上报一次当前标题；
watch: title：当标题内容变化时，再次上报最新标题。

上报数据统一为uni.report('title', this.title)，即事件名固定为title，事件值为标题文本。uni-app 的uni.report是跨端数据统计 API，开启统计后，页面标题会被自动采集，这正是 readme 中"uni-app 如果开启统计，将会自动统计页面标题"的源码级印证。

同样的模式在 uni-ui 其他组件中也能看到：例如 uni-section 与 uni-group 都会上报title事件，uni-nav-bar 则在stat开启且标题非空时上报。它们共同构成了 uni-ui 标题类组件的"内容统计"能力，如果你在做内容型应用（资讯、电商、文档类），可以据此统一规划埋点。

快速上手：三种典型用法

基础用法：五级标题

在template中直接声明即可：

<uni-title type="h1" title="h1 一级标题"></uni-title> <uni-title type="h2" title="h2 二级标题"></uni-title> <uni-title type="h3" title="h3 三级标题"></uni-title> <uni-title type="h4" title="h4 四级标题"></uni-title> <uni-title type="h5" title="h5 五级标题"></uni-title>

改色用法

通过color传入品牌色或主题色：

<uni-title type="h1" title="h1 一级标题" color="#027fff"></uni-title> <uni-title type="h2" title="h2 二级标题" color="#2490ff"></uni-title> <uni-title type="h3" title="h3 三级标题" color="#439ffc"></uni-title> <uni-title type="h4" title="h4 四级标题" color="#60adfb"></uni-title> <uni-title type="h5" title="h5 五级标题" color="#7db9f7"></uni-title>

对齐用法

<uni-title type="h1" title="h1 左对齐" align="left"></uni-title> <uni-title type="h2" title="h2 居中" align="center"></uni-title> <uni-title type="h3" title="h3 右对齐" align="right"></uni-title>

以上三类用法均直接取自 hello-uniapp 的官方示例页 pages/extUI/title/title.vue，可直接复制到自己的项目验证效果。

在 hello-uniapp 中如何查看与运行示例

uni-title 在 hello-uniapp 中注册在扩展组件（extUI）列表里：

页面注册：pages.json 中注册了pages/extUI/title/title页面，导航栏标题为Title 章节标题；
入口导航：pages/tabBar/extUI/extUI.nvue 的扩展组件列表中包含uni-title 章节标题，url 指向title；
运行方式：使用 HBuilderX 导入本项目后运行到 H5 / App / 小程序任意平台，进入"扩展组件" → "Title 章节标题"即可看到完整示例。

示例页还展示了一个组合场景（见 title.vue）：用h1居中标题作文章大标题、h3/h4作章节、h5配合color="#666"作列表项说明文字，并配合uni-card、uni-section组织版面——这正是一个内容页标题层级的实战模板，也印证了 readme 中"章节标题"的定位。

选型参考：uni-title 与同类标题组件的区别

uni-ui 中与标题相关的组件还有uni-section与uni-group，三者定位不同，容易混淆，建议按下表取舍：

组件	定位	特点	何时选用
`uni-title`	章节标题	五级标题 + 对齐 + 颜色 + 统计上报	需要页面内多层级标题，或希望自动统计标题
`uni-section`	标题栏（区块头）	带`line`/`circle`/`square`装饰线，可配副标题、右侧插槽，见 uni-section.vue	需要"区块标题 + 正文容器"的卡片式结构
`uni-group`	分组容器	以标题包裹一组表单/内容，自带分组样式	表单分组、设置项分组等场景

如果只是给示例页的卡片加一行区块标题，优先用uni-section；如果要表达文档、资讯类页面的章节层级并顺带统计，则用uni-title。

版本与变更记录

uni-title 当前在仓库中的版本为 1.1.1（见 package.json）。结合 changelog.md 可了解其演进脉络：

1.0.1（2021-02-05）：调整为 uni_modules 目录规范，此后可被 uni-app 直接通过 easycom 机制按标签自动引入；
1.0.2（2021-05-12）：新增示例地址，修复示例项目缺少组件的 Bug；
1.1.0（2021-11-19）：优化组件 UI 并提供设计资源，文档迁移至 uniui 官方文档；
1.1.1（2022-05-19）：修改组件描述。

组件依赖uni-scss（见 package.json），使用 uni_modules 方式安装时会自动处理依赖。在 HBuilderX 中可通过插件市场免费安装，也可直接从当前仓库的uni_modules/uni-title目录整体拷贝到目标项目的同名目录使用。

小结

uni-title 是一个"小而精"的跨端章节标题组件：type提供 h1～h5 层级规范，align/color提供布局与视觉定制，stat与uni.report打通统计上报。通过 hello-uniapp 的示例页和组件源码，你可以在一份代码内同时验证其在小程序、H5、App（含 nvue）上的表现，并以此为模板规划自己项目的内容标题体系。