meojson
meojson C++ JSON 库使用指南。用于 MaaFramework C++ 项目中的 JSON 解析、序列化、MEO_JSONIZATION、json::value 操作、ext::jsonization 自定义类型支持，以及 Custom 参数解析。
ソース情報
- リポジトリ
- 1204244136/MDA
- ソースの最終更新活動
- 2026年5月28日 22:01
- 検出された SKILL.md の言語
- 中国語
- スター
- 114
- フォーク
- 32
インストール方法
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
ソースファイルを確認
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
ファイルエクスプローラー
2 ファイルSKILL.md を表示中
SKILL.md
ソースの指示 · 読み取り専用プレビュー- name
- meojson
- description
- meojson C++ JSON 库使用指南。用于 MaaFramework C++ 项目中的 JSON 解析、序列化、MEO_JSONIZATION、json::value 操作、ext::jsonization 自定义类型支持，以及 Custom 参数解析。
# meojson 使用指南
meojson 是 MaaFramework 依赖中常用的 header-only C++ JSON 库。通常通过以下头文件引入：
```cpp
#include <meojson/json.hpp>
```
## 核心类型
| 类型 | 说明 |
| -------------- | ------------------------------------------------------------ |
| `json::value` | 通用 JSON 值：null / bool / number / string / array / object |
| `json::array` | JSON 数组，包装 `std::vector<json::value>` |
| `json::object` | JSON 对象，包装 `std::map<std::string, json::value>` |
## 解析
```cpp
auto opt = json::parse(str); // std::optional<json::value>
auto file = json::open(path); // 从文件读取
auto jsonc = json::parsec(str); // JSONC，支持注释
```
推荐安全模式：
```cpp
template <typename T>
T ParseParam(const char* text)
{
if (text == nullptr || std::strlen(text) == 0) {
return T {};
}
auto opt = json::parse(text);
if (!opt) {
LogError << "failed to parse json param" << VAR(text);
return T {};
}
T result {};
if (!result.from_json(*opt)) {
LogError << "failed to deserialize json param" << VAR(text);
return T {};
}
return result;
}
```
避免：
```cpp
json::parse(str).value_or(json::object {}).as<T>();
```
这会静默吞掉 parse 失败，并可能在 required 字段缺失时抛异常。
## 构造 JSON 值
```cpp
json::value v1 = 42;
json::value v2 = "hello";
json::value v3 = true;
json::value v4 = nullptr;
json::array arr { 1, 2, "three" };
json::object obj {
{ "key1", "value1" },
{ "key2", 42 },
};
std::vector<int> vec = { 1, 2, 3 };
json::value v5 = vec;
std::map<std::string, int> map = { { "a", 1 } };
json::value v6 = map;
```
## 读取值
### 类型检查
```cpp
v.is_null();
v.is_boolean();
v.is_number();
v.is_string();
v.is_array();
v.is_object();
v.is<int>();
```
### 直接访问
```cpp
v.as_string();
v.as_string_view();
v.as_integer();
v.as_double();
v.as_boolean();
v.as_array();
v.as_object();
v.as<T>();
```
`as_*()` / `as<T>()` 类型不匹配时可能抛异常，只在确定数据合法时使用。
### 安全访问
```cpp
auto name = v.find<std::string>("name");
if (name) {
// use *name
}
std::string label = v.get("label", "default");
int count = v.get("config", "count", 0);
if (v.exists("key")) {
// ...
}
```
## 序列化
```cpp
v.dumps(); // 紧凑字符串
v.dumps(4); // 4 空格缩进
v.format(); // pretty print
```
写回 MaaFramework detail 的常见模式：
```cpp
template <typename T>
void WriteJsonDetail(MaaStringBuffer* out_detail, const T& payload)
{
if (out_detail == nullptr) {
return;
}
const std::string json_text = json::value(payload).dumps();
MaaStringBufferSet(out_detail, json_text.c_str());
}
```
## Object 合并
```cpp
json::value merged = obj1 | obj2; // 右侧覆盖同名键
obj1 |= obj2;
```
## MEO_JSONIZATION
`MEO_JSONIZATION(fields...)` 生成 `to_json()`、`check_json()`、`from_json()`。
```cpp
struct LocateOutput {
int status = 0;
std::string message;
std::string map_name;
int x = 0;
int y = 0;
MEO_JSONIZATION(status, message, MEO_OPT map_name, MEO_OPT x, MEO_OPT y)
};
```
序列化：
```cpp
json::value j = data;
```
反序列化推荐：
```cpp
LocateOutput data {};
if (!data.from_json(j)) {
LogError << "failed to deserialize" << VAR(j);
}
```
## MEO_OPT
默认字段都是 required。用 `MEO_OPT` 标记可选字段，缺失时保留默认值：
```cpp
struct Options {
double threshold = 0.7;
bool enabled = true;
MEO_JSONIZATION(MEO_OPT threshold, MEO_OPT enabled)
};
```
每个可选字段都需要自己的 `MEO_OPT`。
## MEO_KEY
当 JSON key 与 C++ 字段名不同，使用 `MEO_KEY`：
```cpp
struct TemplateParam {
std::vector<std::string> template_;
MEO_JSONIZATION(MEO_KEY("template") template_)
};
```
与 `MEO_OPT` 组合时顺序通常为：
```cpp
MEO_OPT MEO_KEY("default") default_
```
## 子宏
| 宏 | 生成内容 |
| ---------------------- | -------------- |
| `MEO_TOJSON(...)` | `to_json()` |
| `MEO_FROMJSON(...)` | `from_json()` |
| `MEO_CHECKJSON(...)` | `check_json()` |
| `MEO_JSONIZATION(...)` | 全部三个 |
## ext::jsonization
对不拥有源码的类型，特化 `json::ext::jsonization<T>`：
```cpp
namespace json::ext {
template <>
class jsonization<MyRect> {
public:
json::value to_json(const MyRect& rect) const
{
return json::array { rect.x, rect.y, rect.width, rect.height };
}
bool check_json(const json::value& value) const
{
return value.is<std::vector<int>>() && value.as_array().size() == 4;
}
bool from_json(const json::value& value, MyRect& rect) const
{
auto arr = value.as<std::vector<int>>();
rect = MyRect { arr[0], arr[1], arr[2], arr[3] };
return true;
}
};
}
```
## Enum 反射
```cpp
enum class MyEnum {
A,
B,
C,
MEOJSON_ENUM_RANGE(A, C)
};
json::value j = MyEnum::B;
MyEnum e = j.as<MyEnum>();
```
## 常见坑
1. `json::parse` 返回 `std::optional`，必须检查。
2. `as_*()` / `as<T>()` 类型不匹配时可能抛异常。
3. 禁止 `.value_or(...).as<T>()` 静默吞解析错误。
4. `char` / `wchar_t` 构造被禁用，使用 `std::string` 或整数。
5. `ext::jsonization` 位于 `json::ext` 命名空间。
6. 每个可选字段都需要自己的 `MEO_OPT`。
7. `MEO_KEY` 与 `MEO_OPT` 组合时注意顺序。
## 参考
详细 API 见 [reference.md](reference.md)。
GitHubで見る