عرض مصدر JavaScript/Object/valueOf

<noinclude>{{DISPLAYTITLE:<code>Object.prototype.valueOf()‎</code>}}</noinclude>
الدالة <code>Object.prototype.valueOf()‎</code> تُعيد قيمةً أوليّةً للكائن المعطي.

== البنية العامة ==
<syntaxhighlight lang="javascript">
object.valueOf()

</syntaxhighlight>

=== القيمة المعادة ===
قيمة أوليّة للكائن المعطي.

== الوصف ==
تستدعي JavaScript الدالة <code>valueOf</code> لتحويل كائن ما إلى قيمة أوليّة، ومن النادر أن تحتاج إلى استدعاء الدالة <code>valueOf</code> يدويًا، إذ تستدعيها JavaScript تلقائيًا عندما تصادف كائنًا في مكانٍ تتوقع فيه قيمةً أوليةً.

جميع الكائنات التي تنحدر من الكائن <code>[[JavaScript/Object|Object]]</code> ترث الدالة <code>valueOf</code>، وتُعيد جميع الكائنات المُضمَّنة في اللغة تعريف هذه الدالة لتعيد القيمة المناسبة؛ وإذا لم يكن من الممكن تمثيل الكائن بقيمة أوليّة، فستُعيد الدالة <code>valueOf</code> الكائن نفسه.

يمكنك استخدام الدالة <code>valueOf</code> في الشيفرات التي تكتبها لتحويل كائن مضمَّن في اللغة إلى قيمةٍ أوليّة، وعندما تُنشِئ كائنًا خاصًا بك فيمكنك إعادة تعريف الدالة <code>Object.prototype.valueOf()‎</code> لاستدعاء دالة خاصة بدلًا من الدالة الافتراضية.

=== إعادة تعريف الدالة <code>valueOf</code> في الكائنات المخصصة ===
يمكنك إنشاء دالة لتستدعى بدلًا من الدالة <code>valueOf</code> الافتراضية، ويجب ألّا تأخذ هذه الدالة أيّة وسائط.

لنفترض أنَّ لدينا نوع الكائنات <code>MyNumberType</code> وأردنا إنشاء دالة <code>valueOf</code> خاصة به؛ فالشيفرة الآتية تُعيد إسناد دالة مُعرَّفة من قبل المستخدم إلى خاصية <code>valueOf</code> التابعة للكائن:<syntaxhighlight lang="javascript">
MyNumberType.prototype.valueOf = function() { return customPrimitiveValue; };

</syntaxhighlight>بعد تنفيذ الشيفرة السابقة، ستستدعي JavaScript الدالة السابقة في كل مرة نستخدم فيها الكائن <code>MyNumberType</code> في مكانٍ يتطلب قيمةً أوليةً.

صحيحٌ أنَّ الدالة <code>valueOf</code> تستدعى تلقائيًا من JavaScript عادةً، لكن يمكننا استدعاؤها يدويًا كما يلي:<syntaxhighlight lang="javascript">
myNumberType.valueOf()

</syntaxhighlight>ملاحظة: تحوّل الكائنات التي تُستخدَم في سياقٍ يتطلب سلسلةً نصيةً باستخدام الدالة <code>[[JavaScript/Object/toString|toString()]]</code>‎ وهي تختلف عن تحويل كائنات <code>[[JavaScript/String|String]]</code> إلى سلاسل نصية أوليّة باستخدام الدالة <code>valueOf</code>.

== أمثلة ==
يبيّن المثال الآتي كيفية إعادة تعريف الدالة <code>valueOf</code> في كائن مخصص، ثم كيف تستدعي JavaScript الدالة <code>valueOf</code> في حال استخدمنا الكائن في سياقٍ تتوقع اللغةُ فيه قيمةً أوليةً:<syntaxhighlight lang="javascript">
function MyNumberType(n) {
    this.number = n;
}

MyNumberType.prototype.valueOf = function() {
    return this.number;
};

var myObj = new MyNumberType(4);
myObj + 3; // 7

</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|نعم
|نعم
|نعم
|نعم
|نعم
|}
== مصادر ومواصفات ==
*مسودة المعيار [https://tc39.github.io/ecma262/#sec-object.prototype.valueof ECMAScript Latest Draft].
*معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-object.prototype.valueof ECMAScript 2015 (6th Edition)]‎.
*معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.2.4.4 ECMAScript 5.1].
*معيار [http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%201st%20edition,%20June%201997.pdf ECMAScript 1st Edition].
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Object|{{SUBPAGENAME}}]]