问题解析：MediaWiki API中列表项换行失效的原因
在使用mediawiki api通过编程方式编辑维基页面时，开发者常会遇到一个普遍的问题：尝试使用标准换行符（如\n、\r\n）或html换行标签（<br/>）来创建列表项时，所有内容却显示在同一行，无法正确生成分行显示的列表。例如，期望得到：
* 项目一 * 项目二
但实际输出却是：
* 项目一* 项目二
这通常是由于API在接收和解析POST请求中的内容时，对这些传统换行符的处理方式与预期不符。当使用http_build_query等函数构建请求体时，\n或\r\n可能会被URL编码为%0A或%0D%0A。虽然%0D%0A理论上代表回车换行，但MediaWiki的解析器在处理通过API提交的wiki文本时，对这种编码后的换行符可能需要特定的格式才能正确识别为列表项分隔符。
解决方案：利用URL编码的CRLF
解决此问题的关键在于，使用MediaWiki API能够正确识别的URL编码回车换行符序列：%0D%0A。这个序列代表了回车符（CR，\r）和换行符（LF，\n）的组合，即\r\n的URL编码形式。当它被作为wiki文本的一部分提交给API时，MediaWiki的解析器能够将其正确地解释为一次硬换行，从而使得后续的列表标记（如*）能够被识别为新的列表项。
实践示例：PHP中构建MediaWiki API列表内容
以下是一个PHP示例，展示了如何构造包含列表项的wiki文本，并使用cURL通过MediaWiki API进行提交。
-
构建列表内容
在构建列表内容时，每个列表项后都应附加%0D%0A。同时，为了生成标准的维基列表，每个项目前应加上星号*。如果需要创建内部链接，可以使用双层方括号[[...]]。
<?php // 假设您已经获取了CSRF Token和API EndPoint $csrf_Token = "YOUR_CSRF_TOKEN"; // 替换为实际获取的CSRF Token $endPoint = "YOUR_MEDIAWIKI_API_URL"; // 替换为您的MediaWiki API地址，例如：http://yourwiki.com/api.php $title = "API测试页面 - 列表"; // 要编辑的页面标题 $maps = []; $mapNames = ["地图A", "地图B", "地图C"]; foreach ($mapNames as $mapName) { // 使用 * 作为列表标记，[[...]] 创建内部链接，并以 %0D%0A 结尾以确保换行 $maps[] = "* [[" . $mapName . "]]%0D%0A"; } // 将所有列表项连接成一个字符串 $content = implode("", $maps); // 完整的wiki文本内容，可以包含其他文本 $fullContent = "这是一个通过API创建的列表：\n\n" . $content . "\n\n更多信息。"; // 准备API请求参数 $params4 = [ "action" => "edit", "title" => $title, "text" => $fullContent, // 提交包含列表的完整内容 "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 ) ); // 构建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 ); // 检查是否有错误 if (curl_errno($ch)) { echo 'cURL Error: ' . curl_error($ch); } else { // 输出API响应 echo "API Response:\n"; echo json_encode(json_decode($output), JSON_PRETTY_PRINT); // 格式化输出JSON } // 关闭cURL会话 curl_close( $ch ); ?> -
获取CSRF Token
在执行编辑操作前，通常需要获取一个CSRF（跨站请求伪造）令牌。这可以通过MediaWiki API的action=query&meta=tokens&type=csrf来获取。
// 示例：获取CSRF Token的代码片段 // 假设您已经登录并保存了session cookie $tokenParams = [ "action" => "query", "meta" => "tokens", "type" => "csrf", "format" => "json" ]; $ch_token = curl_init(); curl_setopt($ch_token, CURLOPT_URL, $endPoint . "?" . http_build_query($tokenParams)); curl_setopt($ch_token, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch_token, CURLOPT_COOKIEJAR, "cookie.txt"); curl_setopt($ch_token, CURLOPT_COOKIEFILE, "cookie.txt"); $tokenOutput = curl_exec($ch_token); curl_close($ch_token); $tokenData = json_decode($tokenOutput, true); $csrf_Token = $tokenData['query']['tokens']['csrftoken']; // ... 然后将 $csrf_Token 用于上面的编辑请求
注意事项
- URL编码的重要性： 确保%0D%0A作为字面量字符串被包含在$content中，而不是在http_build_query之后才被编码。http_build_query会自动对参数值进行URL编码，但在这里，我们希望%0D%0A本身就是我们想要传递给MediaWiki解析器的“字符序列”，而不是让\r\n被http_build_query再次编码。幸运的是，%本身会被http_build_query编码为%25，但%0D%0A作为整体是MediaWiki期望的特殊序列，因此直接使用它通常是有效的。
- MediaWiki Markup： 除了*用于无序列表，您还可以使用#创建有序列表。例如，# [[项目]]%0D%0A。
- API权限： 确保用于API请求的用户账户具有编辑页面的权限。
- 错误处理： 在实际应用中，务必对cURL的执行结果和API的响应进行详细的错误检查，例如检查curl_exec的返回值、HTTP状态码以及API响应中的error字段。
- 会话管理： 保持cURL会话的cookie文件（cookie.txt）的正确读取和写入，这对于维持登录状态和获取CSRF令牌至关重要。
总结
通过在MediaWiki API编辑请求中，利用URL编码的%0D%0A作为列表项之间的换行符，可以有效地解决列表内容显示在同一行的问题。这种方法确保了MediaWiki解析器能够正确识别并渲染出结构清晰、分行显示的列表。掌握这一技巧对于自动化维基内容管理和程序化生成页面具有重要意义。
