====== 为词条添加图集的使用指南 ======

===== 基本语法 =====

==== 显示命名空间中的所有图片 ====

最常用的方式是指定一个媒体命名空间，显示该命名空间下的所有图片：

<code>
{{gallery>:wiki:页面名?150x150&lightbox&showtitle}}
</code>

**语法说明：**
  * `:wiki:页面名` - 指定媒体命名空间（注意命名空间前必须有冒号 `:`）
  * `150x150` - 缩略图尺寸（宽x高，单位：像素）
  * `lightbox` - 启用灯箱效果（点击缩略图可查看大图）
  * `showtitle` - 显示图片标题（如果有 EXIF 数据）

==== 显示单个图片 ====

也可以指定单个图片文件：

<code>
{{gallery>:wiki:页面名:图片名.jpg?150x150&lightbox}}
</code>

==== 手动指定图片列表 ====

如果需要手动指定图片列表，可以使用以下语法：

<code>
<gallery 150x150&lightbox>
:wiki:页面名:图片1.jpg
:wiki:页面名:图片2.jpg
https://example.com/外部图片.jpg
</gallery>
</code>

===== 如何上传图片 =====

==== 步骤说明 ====

  * **重要提示**：媒体文件是共享的，不需要为每个语言版本创建单独的文件夹。所有语言版本共享同一个图片文件夹。
  * 点击导航栏的"媒体管理器"
  * 在左侧树形结构中，点击根目录 `[根目录]` 展开
  * 找到并展开 `wiki` 文件夹（注意：不是 `zh:wiki` 或 `en:wiki`，而是根目录下的 `wiki`）
  * 在 `wiki` 文件夹下找到或创建名为 `页面名` 的文件夹（例如：`新车间_xinchejian`）
  * 点击进入该文件夹
  * 上传图片文件
  * 上传的图片将自动显示在画廊中（中文版和英文版都会显示）

==== 命名规范 ====

  * 文件夹名称应与页面名称保持一致
  * 例如：页面是 `zh:wiki:新车间_xinchejian`，则媒体文件夹应为 `wiki:新车间_xinchejian`
  * 图片文件名建议使用小写字母、数字和下划线，避免使用空格和特殊字符

===== 常用选项 =====

==== 尺寸设置 ====

  * `150x150` - 缩略图尺寸（默认）
  * `200x200` - 更大的缩略图
  * `100x100` - 更小的缩略图
  * 注意：使用小写 `x`，例如 `150x150`

==== 布局选项 ====

  * `full` - 全宽响应式布局（默认推荐）
  * `center` - 居中显示
  * `left` - 左对齐
  * `right` - 右对齐

==== 其他常用选项 ====

  * `lightbox` - 启用灯箱效果（默认开启）
  * `nocrop` - 不裁剪，保持图片原始比例
  * `crop` - 裁剪缩略图以匹配指定尺寸
  * `showtitle` - 显示图片标题
  * `showname` - 显示文件名
  * `nocache` - 禁用缓存（不推荐，仅在调试时使用）

===== 完整示例 =====

==== 示例 1：基本画廊 ====

<code>
{{gallery>:wiki:新车间_xinchejian?150x150&lightbox&showtitle}}
</code>

显示 `wiki:新车间_xinchejian` 命名空间下的所有图片，缩略图 150x150，启用灯箱和标题显示。

==== 示例 2：自定义尺寸和布局 ====

<code>
{{gallery>:wiki:页面名?200x200&center&nocrop&lightbox}}
</code>

显示 200x200 的缩略图，居中显示，不裁剪，启用灯箱。

==== 示例 3：限制图片数量 ====

<code>
{{gallery>:wiki:页面名?150x150&=5&lightbox}}
</code>

只显示前 5 张图片。

===== 注意事项 =====

  * 画廊输出默认会被缓存。如果上传了新图片但没有显示，需要清除页面缓存或等待缓存过期
  * 图片文件应上传到媒体管理器，而不是页面目录
  * 媒体文件是共享的，所有语言版本共享同一个图片文件夹
  * 建议使用 JPEG、PNG 或 GIF 格式的图片
  * 图片文件名应使用有效的 DokuWiki 页面名称格式（小写字母、数字、下划线）

===== 故障排除 =====

==== 图片不显示 ====

  * 检查图片是否已上传到正确的媒体命名空间
  * 检查命名空间路径是否正确（注意命名空间前必须有冒号 `:`）
  * 清除页面缓存：在页面 URL 后添加 `&purge=true`

==== 画廊显示为空 ====

  * 确认媒体命名空间中有图片文件
  * 检查图片文件格式是否支持（JPEG、PNG、GIF）
  * 检查文件权限是否正确

==== 灯箱效果不工作 ====

  * 检查是否启用了 `lightbox` 选项
  * 清除浏览器缓存
  * 检查是否有 JavaScript 错误