往往无法生效，导致所有列表内容堆积在一行。文章将揭示其根本原因，并提供一个有效的解决方案：通过 URL 编码的换行符 %0D%0A 确保 MediaWiki API 能够正确解析并渲染出结构化的列表内容。
MediaWiki API 中列表项换行的问题解析
在使用 mediawiki api 通过 action=edit 接口更新页面内容时，开发者常会遇到一个普遍问题：当尝试创建项目符号列表（如使用 * 标记）并期望每个列表项在新行显示时，无论使用常见的换行符如 \n、\r\n 还是 html 换行标签
，最终页面上的所有列表项都可能挤在同一行上。
这背后的主要原因在于数据提交方式和 MediaWiki 解析机制的交互。当通过 HTTP POST 请求发送数据，尤其是使用 http_build_query 函数构建请求体时，字符串中的特殊字符会被进行 URL 编码。例如，\n（换行符）在 URL 编码后通常变为 %0A，\r（回车符）变为 %0D。然而，MediaWiki API 在接收到这些编码后的文本内容时，并不会自动将 %0A 或 %0D%0A 识别为维基文本中的“新行”标记，除非它们是作为原始的、未被编码的换行符被解析。同时，
作为 HTML 标签，在维基文本中通常会被直接渲染而非作为换行符来分隔维基语法元素。因此，简单地将这些字符插入字符串并不能达到预期效果。
解决方案：URL 编码的换行符 %0D%0A
解决此问题的关键在于使用 MediaWiki API 能够正确识别的、且能通过 http_build_query 传递的“新行”表示。经验证，将回车符和换行符的组合（CRLF，即 \r\n）进行 URL 编码，生成 %0D%0A，是 MediaWiki API 能够正确解析为维基文本中新行的有效方式。
当 text 参数中包含 %0D%0A 时，MediaWiki API 会将其解释为一个真实的换行符，从而使得后续的维基语法（例如下一个 * 开头的列表项）能够在新的一行开始渲染。
实战示例：构建并发送包含列表项的 API 请求
以下 PHP 代码示例展示了如何构建包含项目符号列表的字符串，并使用 cURL 将其通过 MediaWiki API 提交到维基页面。
"edit",
"title" => $title,
"text" => $content,
"token" => $csrf_Token,
"format" => "json"
];
// 初始化 cURL 会话
$ch = curl_init();
// 设置 cURL 选项
curl_setopt($ch, CURLOPT_URL, $endPoint);
curl_setopt($ch, CURLOPT_POST, true); // 设置为POST请求
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params4)); // 使用http_build_query构建POST数据
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回响应内容而不是直接输出
curl_setopt($ch, CURLOPT_COOKIEJAR, "cookie.txt"); // 保存会话cookie
curl_setopt($ch, CURLOPT_COOKIEFILE, "cookie.txt"); // 使用会话cookie
// 执行 cURL 请求
$output = curl_exec($ch);
// 检查 cURL 错误
if (curl_errno($ch)) {
echo 'cURL Error: ' . curl_error($ch);
} else {
// 输出 API 响应
echo "API Response:\n";
echo $output;
}
// 关闭 cURL 会话
curl_close($ch);
?>在上述代码中，$maps[] = "* [[" . $mapName . "]]%0D%0A"; 是实现列表项换行的核心。%0D%0A 确保了每个 * 开头的列表项都能在 MediaWiki 页面上独立成行。
核心原理与注意事项
- URL 编码的重要性：当通过 http_build_query 构建 POST 请求体时，所有的参数值都会被 URL 编码。因此，直接在 PHP 字符串中使用 \n 或 \r\n，它们会被编码为 %0A 或 %0D%0A。问题在于，MediaWiki API 接收到这些编码后的字符串时，需要特定的编码序列才能正确识别为维基文本的换行符。%0D%0A 正是这个有效的序列。
- MediaWiki 语法解析：MediaWiki 页面内容是基于维基文本（Wikitext）语法的。API 接收到的 text 参数内容会被 MediaWiki 的解析器处理。因此，确保提交的内容符合 MediaWiki 的语法规则至关重要。例如，列表项必须以 * 开头。
- 安全性：在进行 MediaWiki API 编辑操作时，CSRF（跨站请求伪造）令牌是必不可少的安全措施。确保在 params 中包含有效的 token 参数，并且在每次会话中正确管理 Cookie。
- 错误处理与调试：在实际开发中，务必对 API 响应进行解析和错误检查。MediaWiki API 会在响应中返回操作结果，包括成功或失败信息。通过解析 JSON 响应，可以及时发现并解决问题。
总结
通过 MediaWiki API 创建结构化的列表项，尤其是实现正确的换行，需要理解 URL 编码机制和 MediaWiki 维基文本解析规则。核心在于使用 URL 编码的换行符 %0D%0A 来确保每个列表项能够独立成行。遵循本文提供的解决方案和注意事项，开发者可以更有效地通过编程方式管理和更新 MediaWiki 页面内容。
