# 文本类组件

> `basic-text` / `basic-markdown` / `basic-paragraph`。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 1. basic-text —— 文本

- **type**: `basic-text`　**默认尺寸**: `[300,60]`　**默认名**: `text` 值或"文本"
- 用途：静态文本，或绑定一个字段显示其首行值（动态文本）。

样式 options：

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `text` | `string` | `文本` | 固定文本内容 |
| `text-arrangement` | `select` | `horizontal` | `horizontal`/`vertical` 排列 |
| `content-overflow` | `select` | `hidden` | `hidden` 裁剪 / `auto` 滚动条（颜色跟随 `text-font`）。超出组件宽高时出滚动条，内容变长会滚到最底；日志类文本建议配合 `text-vertical: top` |
| `text-font` | `font` | `{size:20,color:'#ffffff'}` | 字体（含颜色/大小/粗体等） |
| `text-position` | `select` | `center` | 水平对齐 left/center/right |
| `text-vertical` | `select` | `center` | 竖直对齐 top/center/bottom |
| `font-spacing`/`text-indent` | `number` | `0` | 字间距/缩进 |
| `font-line-height` | `number` | `0` | 行高。0=默认。⚠️ **≤4 按倍数，更大按 px**——写 `1.7` 旧逻辑会变成 `1.7px` 叠行；新逻辑按倍数。14px 字配 `22` |
| 发光：`font-shadow-color/blur/offset-x/offset-y` | — | — | 文字发光 |
| 投影：`shadow-color/blur/offset-x/offset-y` | — | — | 文字投影 |
| 展示动画：`animation-display`(false)、`animation-type`(scroll)、`animation-easing`、`animation-duration`… | — | — | 滚动/闪烁动画 |

**绑定字段**：

| name | 约束 | 说明 |
|---|---|---|
| `value-field` | `field(recommend=string,min=0,max=1)` | 绑一个字段→显示其首行值，覆盖固定 `text` |

---

## 1b. basic-markdown —— Markdown 富文本（Markdown 预览）

- **type**: `basic-markdown`　**默认尺寸**: `[360,280]`　**默认名**: 内容首行或"Markdown"
- 用途：把 Markdown 源文本渲染为带样式的富文本（标题/列表/表格/代码高亮/引用/链接/图片等），相当于 Markdown 预览；适合公告、说明、动态报告。内核 markdown-it + highlight.js；`allow-html` 开启时经 DOMPurify 清洗防 XSS。

样式 options：

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `content` | `string(textarea,rows=8)` | 示例 Markdown | Markdown 源文本（双击组件可编辑回写） |
| `md-theme` | `select` | `dark` | 主题 `dark`/`light`（大屏默认深色） |
| `md-overflow` | `select` | `auto` | 内容溢出 `auto`(滚动)/`hidden`/`visible` |
| `text-font` | `font` | `{size:14,color:'#e6edf3'}` | 正文字体/字号/颜色 |
| `font-line-height` | `number<float>` | `1.7` | 行高倍数 |
| `text-align` | `select` | `left` | 水平对齐 left/center/right |
| `text-padding` | `vector<左,右,上,下>` | `[16,16,12,12]` | 内边距(px) |
| `link-color` | `color` | `#4aa3ff` | 链接颜色 |
| `link-target-blank` | `boolean` | `true` | 链接在新窗口打开 |
| `highlight-code` | `boolean` | `true` | 代码块语法高亮 |
| `linkify` | `boolean` | `true` | 自动识别裸 URL 为链接 |
| `breaks` | `boolean` | `false` | 单个回车渲染为 `<br>` |
| `allow-html` | `boolean` | `false` | 允许源文本内联 HTML（开启后经 DOMPurify 清洗防 XSS） |

**绑定字段**：

| name | 约束 | 说明 |
|---|---|---|
| `value-field` | `field(recommend=string,min=0,max=1)` | 绑一个字段→用其首行值作为 Markdown 内容，覆盖固定 `content` |

---

## 1c. basic-paragraph —— 段落

- **type**: `basic-paragraph`　**默认尺寸**: `[360,200]`　**默认名**: "段落"
- 用途：多段说明文字（长文案）；与 basic-text 的区别是自带行高/首行缩进/两端对齐等排版项。

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `text` | `string(textarea)` | 示例段落 | 段落文本（`\n` 分段；双击可编辑） |
| `font` | `font` | `{size:16,color:'#ffffff'}` | 字体（注意：**是 `font` 不是 `text-font`**） |
| `font-line-height` | `number(px)` | `40` | 行高。⚠️ **≤4 按倍数，更大按 px**——旧逻辑把 `1.7` 写成 `1.7px` 会叠行；现在 `1.7` 可用，13px 字也可写 `22~24` |
| `text-indent` | `number(字)` | `2` | 首行缩进（单位=字） |
| `text-position` | `select` | `left` | `left`/`center`/`right`/`justify`(两端对齐) |
| `text-padding` | `vector<左,右,上,下>` | `[0,0,0,0]` | 内边距 px |
| `font-shadow-*` / `animation-*` | — | — | 投影 / 滚动动画（同 basic-text） |

**绑定字段**：`value-field`（string, 0~1）绑一个字段显示其首行值。