# Huozi 文本标签语法

Huozi 支持使用标签来为文本添加样式效果。标签语法类似 BBCode 或 HTML，使用方括号 `[]` 包裹标签名称。

> **📌 关于标签符号**  
> 本文档以默认的方括号 `[]` 为例进行说明。如果你的项目配置了其他标签符号（如 `<>`、`{}`、`【】` 等），请将文档中的 `[` 和 `]` 替换为你实际使用的符号。标签语法规则保持一致。

## 目录

- [基础标签语法](#基础标签语法)
  - [基本标签](#基本标签)
  - [带参数的标签](#带参数的标签)
  - [嵌套标签](#嵌套标签)
- [参数语法](#参数语法)
  - [简单参数](#简单参数)
  - [带引号的参数](#带引号的参数)
  - [空格处理](#空格处理)
- [特殊字符处理](#特殊字符处理)
  - [显示方括号](#显示方括号)
  - [转义规则](#转义规则)
- [常见样式标签](#常见样式标签)
- [完整示例](#完整示例)
- [注意事项](#注意事项)

---

## 基础标签语法

### 基本标签

标签由**开始标签**和**结束标签**组成，结束标签以 `/` 开头：

```
[标签名]要应用样式的文本[/标签名]
```

**示例：**

```
[bold]这段文字是粗体[/bold]
[italic]这段文字是斜体[/italic]
```

**混合使用：**

```
普通文字[bold]粗体文字[/bold]又是普通文字
```

### 带参数的标签

标签可以带一个参数值，用等号 `=` 连接：

```
[标签名=参数值]文本[/标签名]
```

**示例：**

```
[color=red]红色文字[/color]
[fontSize=24]24号字[/fontSize]
[fontFamily=宋体]宋体文字[/fontFamily]
```

### 嵌套标签

标签可以互相嵌套，实现组合效果：

```
[bold]粗体[italic]粗体+斜体[/italic]只是粗体[/bold]
```

**复杂嵌套示例：**

```
[color=blue]
  蓝色文字
  [bold]蓝色粗体[/bold]
  [fontSize=20]蓝色大字[/fontSize]
[/color]
```

---

## 参数语法

### 简单参数

当参数值不包含空格和特殊字符时，可以直接写：

```
[color=red]红色[/color]
[fontSize=16]正常大小[/fontSize]
[opacity=0.5]半透明[/opacity]
```

### 带引号的参数

当参数值包含空格或特殊字符时，需要用引号包裹。支持双引号和单引号：

**使用双引号：**

```
[fontFamily="Source Han Sans"]文本[/fontFamily]
[style="bold italic"]文本[/style]
```

**使用单引号：**

```
[fontFamily='Source Han Sans']文本[/fontFamily]
[style='bold italic']文本[/style]
```

### 空格处理

标签名、等号、参数值周围允许有空格：

```
[ color = "red" ]红色文字[/ color ]
```

以下写法都是等效的：

```
[color=red]文字[/color]
[color ="red"]文字[/color]
[ color= "red" ]文字[ /color ]
```

---

## 特殊字符处理

### 显示方括号

如果你想在文本中显示字面的方括号 `[` 或 `]`，而不是作为标签，需要使用**双字符转义**：

- `[[` → 显示为 `[`
- `]]` → 显示为 `]`

**示例：**

```
要显示 [[bold]] 标签本身，而不是应用粗体效果
输出：要显示 [bold] 标签本身，而不是应用粗体效果
```

### 转义规则

**基本规则：**

- `[[` 总是显示为单个 `[`
- `]]` 总是显示为单个 `]`
- 单独的 `[` 会尝试解析为标签开始
- 单独的 `]` 会尝试解析为标签结束

**多重转义：**

```
[[[[text]]]]
输出：[[text]]
```

解释：

- 第一个 `[[` → `[`
- 第二个 `[[` → `[`
- `text` → `text`
- 第一个 `]]` → `]`
- 第二个 `]]` → `]`

**在标签内使用转义：**

```
[bold]解释 [[tag]] 的用法[/bold]
```

输出：**解释 [tag] 的用法**

---

## 常见样式标签

以下是一些常用的文本样式标签示例（具体支持哪些标签取决于你使用的 Huozi 配置）：

### 字体样式

```
[bold]粗体文字[/bold]
[italic]斜体文字[/italic]
[underline]下划线文字[/underline]
```

### 颜色

```
[color=red]红色文字[/color]
[color=#FF6600]橙色文字[/color]
[color=rgb(255,0,0)]RGB 红色[/color]
```

### 字号

```
[fontSize=12]小字号[/fontSize]
[fontSize=24]大字号[/fontSize]
[fontSize=48]超大字号[/fontSize]
```

### 字体

```
[fontFamily=宋体]宋体文字[/fontFamily]
[fontFamily="Source Han Sans"]思源黑体[/fontFamily]
```

### 描边和填充

```
[strokeColor=red]红色描边[/strokeColor]
[fillColor=blue]蓝色填充[/fillColor]
[strokeWidth=2]较粗描边[/strokeWidth]
```

### 透明度

```
[opacity=0.5]半透明文字[/opacity]
[opacity=0.2]更透明的文字[/opacity]
```

### 组合使用

```
[fontSize=32][color=red][bold]大号红色粗体[/bold][/color][/fontSize]
```

---

## 注意事项

### 1. 标签必须正确闭合

开始标签和结束标签必须**完全匹配**：

**❌ 错误示例：**

```
[bold]文本[/italic]        # 标签名不匹配
[color=red]文本[/blue]     # 标签名不匹配
[bold]文本                 # 缺少结束标签
```

**✅ 正确示例：**

```
[bold]文本[/bold]
[color=red]文本[/color]
```

### 2. 嵌套顺序要正确

标签嵌套时，必须按照正确的顺序闭合（后开先闭）：

**❌ 错误示例：**

```
[bold][italic]文本[/bold][/italic]    # 顺序错误
```

**✅ 正确示例：**

```
[bold][italic]文本[/italic][/bold]    # 后开先闭
```

### 3. 何时需要引号

- **不需要引号：** 参数值是单个词，不含空格和特殊字符

  ```
  [color=red]文本[/color]
  [fontSize=24]文本[/fontSize]
  ```

- **需要引号：** 参数值包含空格或特殊字符
  ```
  [fontFamily="Source Han Sans"]文本[/fontFamily]
  [style="bold italic"]文本[/style]
  ```

### 4. 特殊字符说明

以下字符在标签语法中有特殊含义：

- `[` - 开始标签
- `]` - 结束标签
- `=` - 连接标签名和参数
- `/` - 标记结束标签
- `"` 和 `'` - 包裹参数值

如需在标签参数中使用这些字符，请用引号包裹。

---

## 快速参考

### 基本语法

| 语法                      | 说明       | 示例                          |
| ------------------------- | ---------- | ----------------------------- |
| `[tag]文本[/tag]`         | 基本标签   | `[bold]粗体[/bold]`           |
| `[tag=value]文本[/tag]`   | 带参数标签 | `[color=red]红色[/color]`     |
| `[tag="value"]文本[/tag]` | 引号参数   | `[font="宋体"]文本[/font]`    |
| `[[`                      | 显示 `[`   | `使用 [[tag]]` → `使用 [tag]` |
| `]]`                      | 显示 `]`   | `使用 [[tag]]` → `使用 [tag]` |

### 常用标签

| 标签         | 说明 | 示例                                 |
| ------------ | ---- | ------------------------------------ |
| `bold`       | 粗体 | `[bold]粗体[/bold]`                  |
| `italic`     | 斜体 | `[italic]斜体[/italic]`              |
| `color`      | 颜色 | `[color=red]红色[/color]`            |
| `fontSize`   | 字号 | `[fontSize=24]大字[/fontSize]`       |
| `fontFamily` | 字体 | `[fontFamily=宋体]文本[/fontFamily]` |

---
