帮助:解析函数/arraysearch

arraysearch 🟢稳定可用

搜索数组，返回索引或自定义值

{{#arraysearch: 数组名 | 搜索值 | 开始位置 | 成功值 | 失败值 }}

扩展：Arrays

数组

搜索

查找

arraysearch

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

在数组中查找指定值首次出现的位置，并返回其索引或自定义值。

比如在颜色数组 blue,white,red,white 中查找 white,返回其首次出现的索引 1(索引从 0 开始)。支持正则表达式匹配和指定搜索起点。

通常用于条件判断场景,如检查某元素是否存在于列表中、查找特定模式的元素位置、根据搜索结果执行不同逻辑等。

语法

{{#arraysearch: 数组名 | 搜索值 | 开始位置 | 成功值 | 失败值 }}

参数

数组名: 已定义的数组变量名

搜索值: 要查找的内容,支持两种模式:

普通字符串:完全匹配（自动忽略前后空白）
正则表达式:以 /pattern/ 格式书写,如 /^red/

开始位置（可选）: 搜索起点的索引,默认为 0。若超出数组范围则直接返回失败值

成功值（可选）: 找到时返回的内容。省略时返回匹配元素的索引(数字)

失败值（可选）: 未找到时返回的内容。省略时返回空字符串

效果

输出：根据搜索结果返回索引、自定义成功值或失败值
效果：查找指定值在数组中首次出现的位置,从指定索引开始搜索

示例

定义数组 b： {{#arraydefine: colors | blue,white,red,white }}

代码	效果	说明
`{{#arraysearch:colors\|white}}`	1	返回首次出现的索引
`{{#arraysearch:colors\|white\|2}}`	3	从索引 2 开始搜索
`{{#arraysearch:colors\|/r.*/}}`	2	正则匹配(匹配到 red)
`{{#arraysearch:colors\|green}}`		未找到返回空
`{{#arraysearch:colors\|white\|0\|找到了\|没找到}}`	找到了	自定义成功返回值
`{{#arraysearch:colors\|green\|0\|找到了\|没找到}}`	没找到	自定义失败返回值

底层代码

/** mediawiki-extensions-Arrays-REL1_37 ExtArrays.php
 * locate the index of the first occurrence of an element starting from the 'index'
 *    - print "-1" (not found) or index (found) to show the index of the first occurrence of 'value' in the array identified by arrayid
 *    - if 'yes' and 'no' are set, print value of them when found or not-found
 *    - index is 0-based , it must be non-negative and less than lenth
 * usage:
 *   {{#arraysearch:arrayid|value|index|yes|no}}
 *
 *   See: http://www.php.net/manual/en/function.array-search.php
 *   note it is extended to support regular expression match and index
 */
public static function pfObj_arraysearch( Parser &$parser, PPFrame $frame, $args ) {
	// Get Parameters
	$arrayId = trim( $frame->expand( $args[0] ) );
	$index = isset( $args[2] ) ? trim( $frame->expand( $args[2] ) ) : 0;

	$store = self::get( $parser );

	if ( $store->arrayExists( $arrayId )
		&& $store->validate_array_index( $arrayId, $index, false )
	) {
		$array = $store->getArray( $arrayId );

		// validate/build search regex:
		if ( isset( $args[1] ) ) {

			$needle = trim( $frame->expand( $args[1] ) );

			if ( !self::isValidRegEx( $needle ) ) {
				$needle = '/^\s*' . preg_quote( trim( $needle ), '/' ) . '\s*$/';
			}
		} else {
			$needle = '/^\s*$/';
		}

		// search for a match inside the array:
		$total = count( $array );
		for ( $i = $index; $i < $total; $i++ ) {
			$value = $array[ $i ];

			if ( preg_match( $needle, $value ) ) {
				// found!
				if ( isset( $args[3] ) ) {
					// Expand only when needed!
					return trim( $frame->expand( $args[3] ) );
				} else {
					// return index of first found item
					return $i;
				}
			}
		}
	}

	// no match! (Expand only when needed!)
	if ( isset( $args[4] ) ) {
		$no = trim( $frame->expand( $args[4] ) );
	} else {
		global $egArraysCompatibilityMode;
		$no = $egArraysCompatibilityMode
			? '-1' // COMPATIBILITY-MODE
			: '';
	}
	return $no;
}

代码逻辑：

函数接受数组名、搜索值、开始位置、成功值和失败值等参数。
通过循环遍历数组，查找匹配搜索值的元素，支持正则表达式匹配。
当找到匹配的元素时，根据参数返回成功值或者元素的索引；未找到时返回失败值或者默认值（空字符串）。
函数通过对数组和参数进行处理，实现了灵活的搜索功能。
（其中的 $egArraysCompatibilityMode 始终为 False）

处理流程:

参数解析：提取数组名、搜索值、起始索引等参数；检查数组是否存在且起始索引有效；若搜索值非正则表达式，自动转换为精确匹配的正则(忽略首尾空白)
循环搜索：从起始索引遍历数组,使用 preg_match 匹配每个元素
匹配成功：返回自定义成功值（若提供），否则返回当前元素索引
匹配失败：返回自定义失败值（若提供），否则返回空字符串

实际用例

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

碧蓝航线 - blhx

明日方舟 - arknights

恋与深空 - lysk

切换标签2

崩坏：星穹铁道 - sr

坎特伯雷公主与骑士唤醒冠军之剑的奇幻冒险 - gt

角色切换ui

三国杀 - sgs

白荆回廊 - bjhl

技能来源/行

雷索纳斯 - resonance

公主连结 - pcr

无期迷途 - wqmt

戴森球计划 - dsp

三国杀OL - sgsol

克鲁赛德战记 - cq

铃兰之剑 - llzj

三国杀移动版 - msgs

忘却前夜 - morimens

食物语-档案馆 - swy

音乐世界Cytus II - cytus2