hypercross
/
ttrpg-tools
2
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix: docs

This commit is contained in:
hypercross 2026-03-16 14:26:42 +08:00
parent 1f8f1b0c7d
commit a144af6015
1 changed files with 157 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

315
docs/markdown.md
View File

@ -38,10 +38,10 @@
## 图标语法 ## 图标语法
使用简单的 `:icon-name` 语法插入图标： 使用简单的 `:[icon-name]` 语法插入图标：
```markdown ```markdown
:attack :defense :potion :sword :[attack] :[defense] :[potion] :[sword]
``` ```
图标会渲染为 `<icon class="icon-attack"></icon>` 形式。 图标会渲染为 `<icon class="icon-attack"></icon>` 形式。
@ -65,8 +65,8 @@
### 🎲 骰子组件 (md-dice) ### 🎲 骰子组件 (md-dice)
```markdown ```markdown
:dice[2d6+d8] :md-dice[2d6+d8]
:dice[1d20+5]{key="attack"} :md-dice[1d20+5]{key="attack"}
``` ```
**功能：** **功能：**
@ -83,15 +83,15 @@
**示例：** **示例：**
```markdown ```markdown
攻击检定 :dice[1d20+5]{key="attack"} 攻击检定 :md-dice[1d20+5]{key="attack"}
伤害掷骰 :dice[2d6+3]{key="damage"} 伤害掷骰 :md-dice[2d6+3]{key="damage"}
``` ```
### 🔗 链接组件 (md-link) ### 🔗 链接组件 (md-link)
```markdown ```markdown
:link[./other-page.md] :md-link[./other-page.md]
:link[./rules.md#combat-section] :md-link[./rules.md#combat-section]
``` ```
**功能：** **功能：**
@ -108,16 +108,16 @@
**示例：** **示例：**
```markdown ```markdown
查看完整规则 :link[./rules.md] 查看完整规则 :md-link[./rules.md]
查看战斗章节 :link[./rules.md#combat] 查看战斗章节 :md-link[./rules.md#combat]
``` ```
### 🖼️ 背景组件 (md-bg) ### 🖼️ 背景组件 (md-bg)
```markdown ```markdown
:bg[./images/background.jpg] :md-bg[./images/background.jpg]
:bg[./images/pattern.png]{fit="contain"} :md-bg[./images/pattern.png]{fit="contain"}
``` ```
**功能：** **功能：**
@ -133,124 +133,177 @@
**示例：** **示例：**
```markdown ```markdown
:bg[./images/dungeon-bg.jpg]{fit="cover"} :md-bg[./images/dungeon-bg.jpg]{fit="cover"}
# 地牢探险 # 地牢探险
这里是地牢的描述内容... 这里是地牢的描述内容...
``` ```
### 🪙 代币组件 (md-token) ### 📍 标记组件 (md-pins)
```markdown ```markdown
:md-token[./token-image.png] :md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}
:md-token[./hero.png]{size=60 defaultThickness=2.5} :md-pins[./images/city-map.png]
``` ```
**功能：** **功能：**
- 将 2D 图片转换为 3D 打印模型 - 在图片上显示标记点（A-Z, AA-ZZ, AAA-ZZZ...）
- 自动进行图像矢量追踪分层 - `fixed` 模式：仅显示标记，不可编辑
- 支持预览和导出 STL 文件 - 非 fixed 模式：点击图片添加标记，点击标记删除
- 提供复制按钮生成标记代码
**属性：** **属性：**
| 属性 | 类型 | 默认值 | 说明 | | 属性 | 类型 | 说明 |
|------|------|--------|------| |------|------|------|
| `size` | number | `50` | 模型整体尺寸 (mm) | | `pins` | string | 标记列表，格式 `"A:30,40 B:10,30"` (标签：x,y) |
| `defaultThickness` | number | `2` | 默认图层厚度 (mm) | | `fixed` | boolean | 是否为固定模式（只读） |
**使用流程：** **标记标签生成规则：**
- 0-25: A-Z
1. 引用图片（PNG/JPG 等） - 26-51: AA-ZZ
2. 等待矢量追踪完成 - 52-77: AAA-ZZZ
3. 在设置面板调整图层厚度
4. 点击「生成 3D 模型」
5. 预览并下载 STL 文件
**示例：** **示例：**
```markdown ```markdown
<!-- 基础代币 --> <!-- 固定标记模式 -->
:md-token[./images/warrior-token.png] :md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30 C:50,80" fixed}
<!-- 指定尺寸 --> <!-- 可编辑模式 - 点击添加标记 -->
:md-token[./images/dragon.png]{size=75 defaultThickness=3} :md-pins[./images/blank-map.png]
<!-- 复制生成的格式 -->
:md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}
``` ```
### 📊 表格组件 (md-table)
```markdown
:md-table[./data.csv]
:md-table[./data.csv]{roll=true}
:md-table[./data.csv]{roll=true remix=true}
```
**CSV 格式要求：**
```csv
label,body,group
第一页，这是**第一页**的内容，group1
第二页，这是*第二页*的内容，group1
第三页，这是第三页的内容，group2
```
- 使用英文逗号分隔
- 支持 `#` 开头的注释行
- 包含逗号或 `#` 的字段用双引号包裹
**特殊列：**
| 列名 | 说明 |
|------|------|
| `label` | 标签页名称 |
| `body` | 标签页内容（支持 Markdown） |
| `group` | 分组标识（可选） |
**属性：**
| 属性 | 类型 | 说明 |
|------|------|------|
| `roll` | boolean | 添加随机切换按钮 |
| `remix` | boolean | `{{prop}}` 引用随机行内容 |
**变量引用语法：**
在 `body` 列中可使用 `{{prop}}` 引用同行其他列：
```csv
label,name,description,body
战士，约翰，勇敢的战士，{{name}}是一位{{description}}。
```
**Front Matter 支持：**
CSV 可包含 YAML front matter，所有行会继承这些属性：
```csv
---
source: 玩家手册
version: 1.0
---
label,name,description
1，战士，近战专家
2，法师，奥术施法者
```
**示例：**
```markdown
<!-- 基础表格 -->
:md-table[./npcs.csv]
<!-- 带随机切换 -->
:md-table[./encounters.csv]{roll=true}
<!-- 随机引用变量 -->
:md-table[./quests.csv]{roll=true remix=true}
```
### 🃏 卡牌组件 (md-deck)
```markdown
:md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-5,8f3"}
```
**CSV 格式：**
```csv
label,title,body
1,卡牌名称，这张卡牌的**效果**描述
2,另一张牌，更多效果
```
**属性：**
| 属性 | 类型 | 说明 |
|------|------|------|
| `grid` | string | 卡牌布局（行 x 列） |
| `layers` | string | 图层定义 |
**图层语法：**
```
layers="字段：起始行，起始列 - 结束列，字体大小"
```
示例：`title:1,1-5,1f8` 表示 title 字段从第 1 行开始，占据 1-5 列，8mm字体。
### 🧶 叙事线组件 (md-yarn-spinner) ### 🧶 叙事线组件 (md-yarn-spinner)
```markdown 用于展示分支叙事结构，支持 Yarn Spinner 格式文件。
:md-yarn-spinner[./story.yarn]{start="start"}
```
**功能：**
- 运行 Yarn Spinner 叙事脚本
- 显示对话历史和选项
- 支持命令和变量替换
**属性：**
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `start` | string | `start` | 起始节点名称 |
**Yarn 文件格式：**
```yarn
title: start
tags:
colorID: 0
position: 0,0
---
NPC: 欢迎来到村庄！
玩家：谢谢！[[继续]]
===
title: 继续
tags:
colorID: 0
position: 200,0
---
NPC: 有什么我可以帮你的吗？
-> 询问任务
最近有什么危险的任务吗？
-> 离开
再见！
[[结束]]
===
```
**示例：**
```markdown ```markdown
:md-yarn-spinner[./dialogues/village-elder.yarn] :md-yarn-spinner[./story.yarn]
```
:md-yarn-spinner[./quest-branch.yarn]{start="intro"} ### 🪙 代币组件 (md-token)
用于展示游戏代币/棋子。
```markdown
:md-token[./token.png]
``` ```
### 📋 命令追踪器 (md-commander) ### 📋 命令追踪器 (md-commander)
支持命令历史和状态追踪。
```markdown ```markdown
:md-commander :md-commander
:md-commander[./commands.csv]{placeholder="输入命令..."}
``` ```
**功能：** **追踪器命令：**
- 命令历史视图
- 追踪器视图（角色状态、进度等）
- 支持 Emmet 简写语法
- 命令自动补全
**属性：**
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `placeholder` | string | - | 输入框占位符 |
| `class` | string | - | 额外 CSS 类 |
| `height` | string | `400px` | 组件高度 |
| `commandTemplates` | string | - | CSV 模板文件路径 |
**追踪器命令语法：**
``` ```
track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"] track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
@ -266,63 +319,9 @@ track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
| 类型 | 格式 | 显示 | | 类型 | 格式 | 显示 |
|------|------|------| |------|------|------|
| `progress` | `x/y` | 进度条 (如 `hp=4/4`) | | progress | `x/y` | 进度条 |
| `count` | 整数 | 数字计数器 (如 `ac=15`) | | count | 整数 | 数字计数器 |
| `string` | 文本 | 文本字段 (如 `name="John"`) | | string | 文本 | 文本字段 |
**内置命令：**
| 命令 | 说明 |
|------|------|
| `track` | 添加追踪项 |
| `remove` | 移除追踪项 |
| `update` | 更新属性 |
| `clear` | 清空追踪 |
**示例：**
```markdown
<!-- 基础追踪器 -->
:md-commander
<!-- 带占位符 -->
:md-commander{placeholder="输入 /help 查看命令"}
<!-- 从 CSV 加载命令模板 -->
:md-commander[./my-commands.csv]
<!-- 示例追踪命令 -->
track enemy#goblin.soldier[hp=7/7 ac=12]
track ally#cleric[hp=24/24 spells=4/4]
```
### 📁 文件树 (FileTree)
文件树组件自动在侧边栏显示，无需手动插入。
**功能：**
- 自动扫描内容目录
- 显示文件层级结构
- 支持文件夹展开/收起
- 显示当前文件的标题导航
**目录结构示例：**
```
content/
├── index.md # 首页
├── rules/
│ ├── index.md # 规则首页
│ ├── combat.md # 战斗规则
│ └── magic.md # 魔法系统
└── characters/
└── npc-list.md # NPC 列表
```
侧边栏会自动显示：
- 📁 rules/
- 📄 combat.md
- 📄 magic.md
## YAML 标签 ## YAML 标签
@ -390,13 +389,13 @@ graph TD
```markdown ```markdown
<!-- 引用同目录文件 --> <!-- 引用同目录文件 -->
:table[./data.csv] :md-table[./data.csv]
<!-- 引用子目录文件 --> <!-- 引用子目录文件 -->
:deck[./cards/deck.csv] :md-deck[./cards/deck.csv]
<!-- 引用上级目录文件 --> <!-- 引用上级目录文件 -->
:table[../shared/npcs.csv] :md-table[../shared/npcs.csv]
<!-- 引用图片 --> <!-- 引用图片 -->
![地图](./images/map.png) ![地图](./images/map.png)
@ -415,7 +414,7 @@ graph TD
组件支持 Tailwind CSS 类： 组件支持 Tailwind CSS 类：
```markdown ```markdown
:dice[1d20]{class="text-red-500"} :md-dice[1d20]{class="text-red-500"}
``` ```
### 自定义 CSS ### 自定义 CSS
@ -440,9 +439,9 @@ graph TD
### 规则说明 ### 规则说明
:dice[2d6] 掷骰决定结果。 :md-dice[2d6] 掷骰决定结果。
:table[./options.csv]{roll=true} :md-table[./options.csv]{roll=true}
> [!TIP] > [!TIP]
> 这是一个有用的提示。 > 这是一个有用的提示。