| # MeNav Handlebars 助手函数说明文档 |
|
|
| ## 目录 |
|
|
| - [助手函数概述](#助手函数概述) |
| - [助手函数分类](#助手函数分类) |
| - [格式化函数](#格式化函数) |
| - [条件判断函数](#条件判断函数) |
| - [工具函数](#工具函数) |
| - [核心函数](#核心函数) |
| - [使用方法](#使用方法) |
| - [函数详解](#函数详解) |
| - [扩展指南](#扩展指南) |
| - [最佳实践](#最佳实践) |
|
|
| ## 助手函数概述 |
|
|
| MeNav 项目使用 Handlebars 助手函数扩展模板功能，使模板更加强大和灵活。助手函数可用于： |
|
|
| - 数据格式化（日期、文本等） |
| - 条件判断和逻辑控制 |
| - 数组与对象操作 |
| - HTML 安全处理 |
|
|
| 所有助手函数都在 `src/helpers/` 目录下定义，并通过 `src/helpers/index.js` 统一注册到 Handlebars 实例。 |
|
|
| ## 助手函数分类 |
|
|
| MeNav 的助手函数分为四类： |
|
|
| ### 格式化函数 |
|
|
| 位置：`src/helpers/formatters.js` |
|
|
| 提供各种数据格式化功能，包括： |
|
|
| - 日期格式化 |
| - 文本长度限制 |
| - 大小写转换 |
| - 调试数据显示 |
|
|
| ### 条件判断函数 |
|
|
| 位置：`src/helpers/conditions.js` |
|
|
| 提供条件判断与逻辑操作功能，包括： |
|
|
| - 相等与不等判断 |
| - 通用比较操作 |
| - 空值检查 |
| - 逻辑运算（与、或、非） |
|
|
| #### ifHttpUrl |
|
|
| 判断字符串是否为 http/https URL，用于在模板中分支渲染仅对外链生效的逻辑（如 favicon 加载）： |
|
|
| ```handlebars |
| {{#ifHttpUrl url}} |
| {{! 只有 http/https 才尝试加载 favicon }} |
| <img |
| src='https://t3.gstatic.com/faviconV2?url={{encodeURIComponent url}}&size=32&drop_404_icon=true' |
| alt='{{name}} favicon' |
| /> |
| {{else}} |
| <i class='fas fa-link'></i> |
| {{/ifHttpUrl}} |
| ``` |
|
|
| ### 工具函数 |
|
|
| 位置：`src/helpers/utils.js` |
|
|
| 提供各种实用工具功能，包括： |
|
|
| - 数组与字符串操作 |
| - 集合长度计算 |
| - 范围数组生成 |
| - 对象属性选择 |
|
|
| #### encodeURIComponent |
|
|
| 对字符串进行 URL 组件编码（同名于浏览器 API，用作模板内联助手），适用于将动态 URL 参数安全拼接到查询串： |
|
|
| ```handlebars |
| {{! 构造第三方 Favicon API 的 url 参数 }} |
| <img |
| src='https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&url={{encodeURIComponent |
| url |
| }}&size=32&drop_404_icon=true' |
| alt='favicon' |
| /> |
| ``` |
|
|
| ### 核心函数 |
|
|
| 位置：`src/helpers/index.js` |
|
|
| 提供基础的 HTML 处理功能： |
|
|
| - HTML 转义 |
| - 安全输出 HTML |
|
|
| ## 使用方法 |
|
|
| 在 Handlebars 模板中使用助手函数有多种方式： |
|
|
| ### 1. 内联表达式 |
|
|
| 用于生成内容的助手函数： |
|
|
| ```handlebars |
| {{formatDate created 'YYYY-MM-DD'}} |
| {{limit description 100}} |
| {{json data}} |
| ``` |
|
|
| ### 2. 块级表达式 |
|
|
| 用于控制结构的助手函数： |
|
|
| ```handlebars |
| {{#ifEquals type 'article'}} |
| <span class='badge'>文章</span> |
| {{else}} |
| <span class='badge'>页面</span> |
| {{/ifEquals}} |
| |
| {{#each (range 1 5)}} |
| <span>{{this}}</span> |
| {{/each}} |
| ``` |
|
|
| ### 3. 助手函数组合 |
|
|
| 多个助手函数可以组合使用： |
|
|
| ```handlebars |
| {{#each (slice items 0 5)}} |
| <li>{{toUpperCase name}}</li> |
| {{/each}} |
| ``` |
|
|
| ## 函数详解 |
|
|
| ### 格式化函数 |
|
|
| #### formatDate |
|
|
| 格式化日期： |
|
|
| ```handlebars |
| {{formatDate date 'YYYY-MM-DD'}} |
| {{! 2023-05-15 }} |
| {{formatDate date 'YYYY年MM月DD日'}} |
| {{! 2023年05月15日 }} |
| {{formatDate date 'YYYY-MM-DD HH:mm:ss'}} |
| {{! 2023-05-15 14:30:00 }} |
| ``` |
|
|
| 支持的格式： |
|
|
| - `YYYY`: 四位年份 |
| - `MM`: 两位月份 |
| - `DD`: 两位日期 |
| - `HH`: 两位小时（24小时制） |
| - `mm`: 两位分钟 |
| - `ss`: 两位秒数 |
|
|
| #### limit |
|
|
| 限制文本长度，超出部分显示省略号： |
|
|
| ```handlebars |
| {{limit '这是一段很长的文本内容' 5}} {{! 这是一段... }} |
| ``` |
|
|
| #### toLowerCase / toUpperCase |
|
|
| 转换文本大小写： |
|
|
| ```handlebars |
| {{toLowerCase 'Hello'}} |
| {{! hello }} |
| {{toUpperCase 'world'}} |
| {{! WORLD }} |
| ``` |
|
|
| #### json |
|
|
| 将对象转换为 JSON 字符串（用于调试）： |
|
|
| ```handlebars |
| {{json this}} |
| ``` |
|
|
| #### extractDomain |
|
|
| 从 URL 中提取“干净的域名”（不包含协议、路径与查询串），常用于站点描述兜底显示： |
|
|
| ```handlebars |
| {{extractDomain url}} |
| ``` |
|
|
| ### 条件判断函数 |
|
|
| #### ifEquals / ifNotEquals |
|
|
| 比较两个值是否相等/不相等： |
|
|
| ```handlebars |
| {{#ifEquals status 'active'}} |
| 当前状态：活跃 |
| {{else}} |
| 当前状态：非活跃 |
| {{/ifEquals}} |
| ``` |
|
|
| #### ifCond |
|
|
| 通用条件比较： |
|
|
| ```handlebars |
| {{#ifCond count '>' 0}} |
| 有 |
| {{count}} |
| 个项目 |
| {{else}} |
| 没有项目 |
| {{/ifCond}} |
| ``` |
|
|
| 支持的运算符： |
|
|
| - `==`, `===`, `!=`, `!==` |
| - `<`, `<=`, `>`, `>=` |
| - `&&`, `||` |
|
|
| #### isEmpty / isNotEmpty |
|
|
| 检查值是否为空： |
|
|
| ```handlebars |
| {{#isEmpty items}} |
| <p>暂无数据</p> |
| {{else}} |
| <ul> |
| {{#each items}} |
| <li>{{this}}</li> |
| {{/each}} |
| </ul> |
| {{/isEmpty}} |
| ``` |
|
|
| #### and / or / not |
|
|
| 逻辑操作： |
|
|
| ```handlebars |
| {{#and isPremium isActive}} |
| 高级活跃用户 |
| {{/and}} |
| |
| {{#or isPremium isAdmin}} |
| 有访问权限 |
| {{/or}} |
| |
| {{#not isDisabled}} |
| 此功能可用 |
| {{/not}} |
| ``` |
|
|
| ### 工具函数 |
|
|
| #### slice |
|
|
| 数组或字符串切片： |
|
|
| ```handlebars |
| {{#each (slice array 0 3)}} |
| <li>{{this}}</li> |
| {{/each}} |
| ``` |
|
|
| #### concat |
|
|
| 合并数组： |
|
|
| ```handlebars |
| {{#each (concat array1 array2)}} |
| <li>{{this}}</li> |
| {{/each}} |
| ``` |
|
|
| #### size |
|
|
| 获取数组、字符串或对象的长度/大小： |
|
|
| ```handlebars |
| 总共 {{size items}} 个项目 |
| ``` |
|
|
| #### first / last |
|
|
| 获取数组的第一个/最后一个元素： |
|
|
| ```handlebars |
| 第一项: |
| {{first items}} |
| 最后一项: |
| {{last items}} |
| ``` |
|
|
| #### range |
|
|
| 创建一个连续范围的数组： |
|
|
| ```handlebars |
| {{#each (range 1 5)}} |
| <span>{{this}}</span> |
| {{/each}} |
| ``` |
|
|
| #### pick |
|
|
| 从对象中选择指定的属性： |
|
|
| ```handlebars |
| {{json (pick user 'name' 'email')}} |
| ``` |
|
|
| #### keys |
|
|
| 将对象的所有键转换为数组： |
|
|
| ```handlebars |
| {{#each (keys object)}} |
| <li>{{this}}</li> |
| {{/each}} |
| ``` |
|
|
| #### encodeURIComponent |
|
|
| 对字符串做 URL 组件编码，常用于拼接第三方请求参数（例如 favicon 的 `url=` 参数）： |
|
|
| ```handlebars |
| {{encodeURIComponent url}} |
| ``` |
|
|
| #### add |
|
|
| 数字加法，用于根据层级动态计算标题级别等场景： |
|
|
| ```handlebars |
| <h{{add level 1}}>...</h{{add level 1}}> |
| ``` |
|
|
| ### 核心函数 |
|
|
| #### escapeHtml |
|
|
| 转义 HTML 特殊字符： |
|
|
| ```handlebars |
| {{escapeHtml content}} |
| ``` |
|
|
| #### safeHtml |
|
|
| 安全输出 HTML（不转义）： |
|
|
| ```handlebars |
| {{safeHtml htmlContent}} |
| ``` |
|
|
| ## 扩展指南 |
|
|
| ### 添加新的助手函数 |
|
|
| 1. 选择适当的分类文件（`formatters.js`、`conditions.js` 或 `utils.js`） |
| 2. 添加新的函数并导出 |
| 3. 函数会自动通过 `index.js` 中的 `registerAllHelpers` 注册 |
|
|
| 示例：添加一个新的格式化函数到 `formatters.js`： |
|
|
| ```javascript |
| /** |
| * 将数字格式化为带千位分隔符的字符串 |
| * @param {number} number 要格式化的数字 |
| * @returns {string} 格式化后的字符串 |
| * @example {{formatNumber 1000000}} -> 1,000,000 |
| */ |
| function formatNumber(number) { |
| if (typeof number !== 'number') return ''; |
| return number.toLocaleString(); |
| } |
| |
| // 在导出中添加新函数 |
| module.exports = { |
| formatDate, |
| limit, |
| toLowerCase, |
| toUpperCase, |
| json, |
| formatNumber, // 添加新函数 |
| }; |
| ``` |
|
|
| ### 添加新的分类 |
|
|
| 如果需要添加新的分类： |
|
|
| 1. 在 `src/helpers/` 创建新的 JS 文件 |
| 2. 在 `index.js` 中导入并注册新的助手函数集 |
|
|
| ```javascript |
| const newHelpers = require('./new-helpers'); |
| |
| function registerAllHelpers(handlebars) { |
| // 现有注册代码... |
| |
| // 注册新的助手函数 |
| Object.entries(newHelpers).forEach(([name, helper]) => { |
| handlebars.registerHelper(name, helper); |
| }); |
| } |
| ``` |
|
|
| ## 最佳实践 |
|
|
| 1. **文档化函数** - 使用 JSDoc 风格为所有函数添加文档注释 |
| - 描述函数功能 |
| - 列出参数和返回值 |
| - 提供使用示例 |
|
|
| 2. **参数校验** - 增加参数类型和有效性检查 |
| - 检查必要参数是否存在 |
| - 验证参数类型 |
| - 为无效输入提供默认值或空结果 |
|
|
| 3. **命名规范** |
| - 使用描述性名称，清晰表达函数用途 |
| - 遵循现有命名风格（如 `kebab-case`） |
| - 保持命名一致性（如条件判断函数以 `is` 或 `if` 开头） |
|
|
| 4. **避免副作用** - 助手函数应为纯函数，不修改传入的数据 |
|
|
| 5. **保持简单** - 每个助手函数应只完成一个明确的任务 |
|
|
