帮助:解析函数/arrayindex

arrayindex 🟢稳定可用

输出数组中指定位置的元素值

{{#arrayindex: 数组名 | 序号 | 默认值 }}

扩展：Arrays

数组

变量

arrayindex

输出数组中指定位置的元素值。出自扩展 Arrays BWIKI和各大Wiki平台广泛使用此扩展。<br>在遥远的未来，它可能与Mediawiki新的并行解析器不兼容，请参阅扩展主页了解更多信息。。

从已定义的数组中，根据指定序号返回对应的元素值。比如数组 {{#arraydefine:fruits|apple,banana,cherry}} 定义后，用 {{#arrayindex:fruits|1}} 可以获取第2个元素 banana。

通常用于从批量数据中提取特定位置的值，如获取查询结果的首尾元素、根据条件动态选择数组中的某项、在模板中按索引访问参数列表等场景。

语法

{{#arrayindex: 数组名 | 序号 | 默认值 }}

参数

数组名: 已通过 #arraydefine 定义的数组名称（区分大小写）

序号: 从 0 开始计数的整数索引; 支持负数索引：

-1 表示最后一个元素
-2 表示倒数第二个元素，以此类推

默认值（可选）: 当数组或索引无效时返回的值，默认为空字符串; 无效情况包括：

数组名不存在（未定义或拼写错误）
序号非数字
序号越界（超出数组实际范围）

效果

输出：返回数组中指定位置的元素值；若无效则返回默认值
效果：仅读取数组内容，不修改数组状态

示例

定义数组：{{#arraydefine:weapons|apple,banana,cherry}}

代码	效果
`{{#arrayindex:weapons\|0}}`	第1个元素：apple
`{{#arrayindex:weapons\|1}}`	第2个元素：banana
`{{#arrayindex:weapons\|-1}}`	最后一个元素：cherry
`{{#arrayindex:weapons\|5\|未找到}}`	越界返回默认值：未找到
`{{#arrayindex:noexist\|0\|数组不存在}}`	数组不存在：数组不存在

使用场景

适用于需要精确访问数组特定位置的场景：

提取首尾元素：获取查询结果的第一条或最后一条记录，如最新文章、最早创建的页面。

条件选择：根据某个变量的值（如模板参数、计数器）动态选择数组中对应位置的内容，实现类似 switch-case 的效果。

遍历辅助：配合循环结构（如 #while）通过递增索引逐个访问数组元素，处理复杂的数据转换逻辑。

安全取值：通过设置默认值，避免因索引越界导致的空白输出，提高模板的健壮性。

相比直接硬编码位置值，使用 arrayindex 可以：

动态处理不确定长度的数据源
灵活应对负数索引需求
统一处理边界情况

边缘示例

代码	效果	说明
`{{#arraydefine:empty}}` `{{#arrayindex:empty\|0\|空}}`	空	空数组访问返回默认值
`{{#arrayindex:weapons\|abc\|错误}}`	错误	非数字索引返回默认值
`{{#arrayindex:weapons\|-10\|越界}}`	越界	负数越界返回默认值

底层代码

来自MediaWiki及其扩展的源代码，运行在服务端。此处仅供快速查阅，便于更充分的挖掘其"特性"。

/** mediawiki-extensions-Arrays-REL1_37 ExtArrays.php
 * print the value of an array (identified by arrayid)  by the index, invalid index results in the default value  being printed. note the index is 0-based.
 * usage:
 *   {{#arrayindex:arrayid|index}}
**/
public static function pfObj_arrayindex( Parser &$parser, PPFrame $frame, $args ) {
	global $egArraysCompatibilityMode;

	// Get Parameters
	$arrayId    = isset( $args[0] ) ? trim( $frame->expand( $args[0] ) ) : '';
	$rawOptions = isset( $args[2] ) ? $args[2] : '';

	if ( !isset( $args[1] ) ) {
		return '';
	}
	$index = trim( $frame->expand( $args[1] ) );

	// get value or null if it doesn't exist. Takes care of negative index as well
	$val = self::get( $parser )->getArrayValue( $arrayId, $index );

	if ( $val === null || ( $val === '' && !$egArraysCompatibilityMode ) ) {
		// index doesn't exist, return default (parameter 3)!
		// without compatibility, also return default in case of empty string ''

		// only expand default when needed
		$defaultOrOptions = trim( $frame->expand( $rawOptions ) );

		if ( $egArraysCompatibilityMode ) {
			// COMPATIBILITY-MODE
			// now parse the options, and do posterior process on the created array
			$options = self::parse_options( $defaultOrOptions );
			$default = self::array_value( $options, 'default' );
		} else {
			$default = $defaultOrOptions;
		}

		return $default;
	}

	return $val;
}

/**
 * Returns a value within an array. If key or array do not exist, this will return null
 * or another predefined default. $index can also be a negative value, in this case the
 * value that far from the end of the array will be returned.
 *
 * @since 2.0
 *
 * @param string $arrayId
 * @param string $index
 * @param mixed|null $default value to return in case the value doesn't exist. null by default.
 *
 * @return string|null
 */
private function getArrayValue( $arrayId, $index, $default = null ) {
	$arrayId = trim( $arrayId );
	if ( $this->arrayExists( $arrayId )
		&& $this->validate_array_index( $arrayId, $index, true )
		&& array_key_exists( $index, $this->mArrays[ $arrayId ] )
	) {
		return $this->mArrays[ $arrayId ][ $index ];
	} else {
		return $default;
	}
}

处理流程：

参数展开和验证
数组查询：调用 getArrayValue 方法尝试获取指定位置的值
索引处理：支持负数索引，自动转换为从数组末尾计数的正数索引
边界检查：验证数组是否存在、索引是否有效、键是否在数组中
返回结果：若查询成功返回元素值，否则返回默认值

其中$egArraysCompatibilityMode始终为 False；

实际用例

一些Wiki使用了相关特性，如下所示这个静态列表可能在下列页面更改后过时，仅供批判性参考。