menav/src/helpers/README.md

# 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" 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" 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. **保持简单** - 每个助手函数应只完成一个明确的任务