min

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 加载）：

  
  <img
    src='https://t3.gstatic.com/faviconV2?url=&size=32&drop_404_icon=true'
    alt=' favicon'
  />

  <i class='fas fa-link'></i>

工具函数

位置：src/helpers/utils.js

提供各种实用工具功能，包括：

数组与字符串操作
集合长度计算
范围数组生成
对象属性选择

encodeURIComponent

对字符串进行 URL 组件编码（同名于浏览器 API，用作模板内联助手），适用于将动态 URL 参数安全拼接到查询串：

<img
  src='https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&url=&size=32&drop_404_icon=true'
  alt='favicon'
/>

核心函数

位置：src/helpers/index.js

提供基础的 HTML 处理功能：

HTML 转义
安全输出 HTML

使用方法

在 Handlebars 模板中使用助手函数有多种方式：

1. 内联表达式

用于生成内容的助手函数：

2. 块级表达式

用于控制结构的助手函数：

  <span class='badge'>文章</span>

  <span class='badge'>页面</span>

  <span></span>

3. 助手函数组合

多个助手函数可以组合使用：


  <li></li>

函数详解

格式化函数

formatDate

格式化日期：

支持的格式：

YYYY: 四位年份
MM: 两位月份
DD: 两位日期
HH: 两位小时（24小时制）
mm: 两位分钟
ss: 两位秒数

limit

限制文本长度，超出部分显示省略号：

toLowerCase / toUpperCase

转换文本大小写：

json

将对象转换为 JSON 字符串（用于调试）：

extractDomain

从 URL 中提取“干净的域名”（不包含协议、路径与查询串），常用于站点描述兜底显示：

条件判断函数

ifEquals / ifNotEquals

比较两个值是否相等/不相等：

  当前状态：活跃

  当前状态：非活跃

ifCond

通用条件比较：

  有
  8
  个项目

  没有项目

支持的运算符：

==, ===, !=, !==
<, <=, >, >=
&&, ||

isEmpty / isNotEmpty

检查值是否为空：

  <p>暂无数据</p>

  <ul>
    
      <li></li>
    
  </ul>

and / or / not

逻辑操作：

  高级活跃用户

  有访问权限

  此功能可用

工具函数

slice

数组或字符串切片：


  <li></li>

concat

合并数组：


  <li></li>

size

获取数组、字符串或对象的长度/大小：

总共  个项目

first / last

获取数组的第一个/最后一个元素：

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

range

创建一个连续范围的数组：


  <span></span>

pick

从对象中选择指定的属性：

keys

将对象的所有键转换为数组：


  <li></li>

encodeURIComponent

对字符串做 URL 组件编码，常用于拼接第三方请求参数（例如 favicon 的 url= 参数）：

add

数字加法，用于根据层级动态计算标题级别等场景：

<h>...</h>

核心函数

escapeHtml

转义 HTML 特殊字符：

safeHtml

安全输出 HTML（不转义）：

扩展指南

添加新的助手函数

选择适当的分类文件（formatters.js、conditions.js 或 utils.js）
添加新的函数并导出
函数会自动通过 index.js 中的 registerAllHelpers 注册

示例：添加一个新的格式化函数到 formatters.js：

/**
 * 将数字格式化为带千位分隔符的字符串
 * @param {number} number 要格式化的数字
 * @returns {string} 格式化后的字符串
 * @example  -> 1,000,000
 */
function formatNumber(number) {
  if (typeof number !== 'number') return '';
  return number.toLocaleString();
}

// 在导出中添加新函数
module.exports = {
  formatDate,
  limit,
  toLowerCase,
  toUpperCase,
  json,
  formatNumber, // 添加新函数
};

添加新的分类

如果需要添加新的分类：

在 src/helpers/ 创建新的 JS 文件
在 index.js 中导入并注册新的助手函数集

const newHelpers = require('./new-helpers');

function registerAllHelpers(handlebars) {
  // 现有注册代码...

  // 注册新的助手函数
  Object.entries(newHelpers).forEach(([name, helper]) => {
    handlebars.registerHelper(name, helper);
  });
}

最佳实践

文档化函数 - 使用 JSDoc 风格为所有函数添加文档注释
- 描述函数功能
- 列出参数和返回值
- 提供使用示例
参数校验 - 增加参数类型和有效性检查
- 检查必要参数是否存在
- 验证参数类型
- 为无效输入提供默认值或空结果
命名规范
- 使用描述性名称，清晰表达函数用途
- 遵循现有命名风格（如 kebab-case）
- 保持命名一致性（如条件判断函数以 is 或 if 开头）
避免副作用 - 助手函数应为纯函数，不修改传入的数据
保持简单 - 每个助手函数应只完成一个明确的任务

This site is open source. Improve this page.