Object3d: Add optional target to `getObjectsByProperty()`. (#27225)

* getObjectsByProperty improved

* Update doc

* Update doc pages

* Removed empty space

docs/api/ar/core/Object3D.html

@@ -322,11 +322,14 @@
 			معطى.
 		</p>
 			 
-		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
 		<p>
 			name -- اسم الخاصية التي يتم البحث عنها. <br />
-			value -- قيمة الخاصية المعطاة. <br /><br />
-			 
+			value -- قيمة الخاصية المعطاة. <br />
+			optionalTarget -- (optional) target to set the result.
+			Otherwise a new Array is instantiated. If set, you must clear this
+			array prior to each call (i.e., array.length = 0;). <br /><br />
+
 			يبحث في كائن وأطفاله، بدءًا من الكائن
 			نفسه، ويرجع جميع الكائنات مع خاصية تطابق القيمة
 			معطى.

docs/api/en/core/Object3D.html

@@ -334,10 +334,13 @@
 			given.
 		</p>
 
-		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
 		<p>
 			name -- the property name to search for. <br />
-			value -- value of the given property. <br /><br />
+			value -- value of the given property. <br />
+			optionalTarget -- (optional) target to set the result.
+			Otherwise a new Array is instantiated. If set, you must clear this
+			array prior to each call (i.e., array.length = 0;). <br /><br />
 
 			Searches through an object and its children, starting with the object
 			itself, and returns all the objects with a property that matches the value

docs/api/it/core/Object3D.html

@@ -285,10 +285,13 @@
       Cerca in un oggetto e nei suoi figli, partendo dall'oggetto stesso, e restituisce il primo con la proprietà che corrisponde al valore passato.
 		</p>
 
-		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
 		<p>
 		  name -- il nome della proprietà da cercare. <br />
-		  value -- il valore della proprietà data. <br /><br />
+		  value -- il valore della proprietà data. <br />
+		  optionalTarget -- (opzionale) array dove impostare il risultato.
+		  Altrimenti viene istanziato un nuovo Array. 
+		  Se impostato, è necessario cancellare questo array prima di ogni chiamata (ad esempio, array.length = 0;). <br /><br />
 
       Cerca in un oggetto e nei suoi figli, partendo dall'oggetto stesso, e restituisce tutti gli oggetti con la proprietà che corrisponde al valore passato.
 		</p>

docs/api/ko/core/Object3D.html

@@ -271,10 +271,13 @@
 		객체 자신부터 시작하여 객체와 객체 자식 항목을 검색하고 일치하는 값의 첫 번째 항목을 리턴합니다.
 		</p>
 
-		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
 		<p>
 		name -- 검색하고자하는 이름 프로퍼티. <br />
-		value -- 프로퍼티의 값. <br /><br />
+		value -- 프로퍼티의 값. <br />
+		optionalTarget -- (optional) target to set the result.
+		Otherwise a new Array is instantiated. If set, you must clear this
+		array prior to each call (i.e., array.length = 0;). <br /><br />
 
 		개체 자체부터 시작하여 개체와 해당 자식을 검색하고 일치하는 값의 모든 개체를 반환합니다.
 		</p>

docs/api/zh/core/Object3D.html

@@ -264,10 +264,13 @@
 		从该对象开始，搜索一个对象及其子级，返回第一个给定的属性中包含有匹配的值的子对象。
 	</p>
 
-	<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+	<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value], [param:Array optionalTarget] )</h3>
 	<p>
 		name —— 将要用于查找的属性的名称。<br />
-		value —— 给定的属性的值。 <br /><br />
+		value —— 给定的属性的值。 <br />
+		optionalTarget -- (optional) target to set the result.
+		Otherwise a new Array is instantiated. If set, you must clear this
+		array prior to each call (i.e., array.length = 0;). <br /><br />
 		从此对象开始，搜索一个对象及其子对象，返回包含给定属性的匹配值的所有子对象。
 	</p>
 

src/core/Object3D.js

@@ -457,21 +457,15 @@ class Object3D extends EventDispatcher {
 
 	}
 
-	getObjectsByProperty( name, value ) {
-
-		let result = [];
+	getObjectsByProperty( name, value, result = [] ) {
 
 		if ( this[ name ] === value ) result.push( this );
 
-		for ( let i = 0, l = this.children.length; i < l; i ++ ) {
-
-			const childResult = this.children[ i ].getObjectsByProperty( name, value );
-
-			if ( childResult.length > 0 ) {
+		const children = this.children;
 
-				result = result.concat( childResult );
+		for ( let i = 0, l = children.length; i < l; i ++ ) {
 
-			}
+			children[ i ].getObjectsByProperty( name, value, result );
 
 		}