عرض مصدر Kotlin/properties

الخاصّيّات (Properties) وحقول البيانات (Fields) في لغة Kotlin
<noinclude>{{DISPLAYTITLE:الخاصّيّات (Properties) وحقول البيانات (Fields) في لغة Kotlin}}</noinclude>
== التصريح عن الخاصّيّات (Declaring Properties) ==
قد تحتوي الأصناف في لغة Kotlin على الخاصّيّات المعرَّفة إما كقيمٍ متغيّرةٍ عبر الكلمة المفتاحيّة <code>var</code> أو كقيمٍ ثابتةٍ للقراءة فقط (read-only) عبر الكلمة المفتاحيّة <code>val</code>، مثل:<syntaxhighlight lang="kotlin">
class Address {
    var name: String = ...
    var street: String = ...
    var city: String = ...
    var state: String? = ...
    var zip: String = ...
}
</syntaxhighlight>إذ يُمكن الوصول للخصائص عبر اسمها (كما لو كانت حقلًا [field] في لغة Java)، مثل:<syntaxhighlight lang="kotlin">
fun copyAddress(address: Address): Address {
    val result = Address() // لا وجود هنا للكلمة المفتاحيّة new
    result.name = address.name // تُستدعى دوال الوصول (accessors)
    result.street = address.street
    // ...
    return result
}
</syntaxhighlight>

== الوصول للخاصّيات باستخدام Getter و Setter ==
إنّ الصيغة الكاملة للتصريح عن الخاصيّات هي:<syntaxhighlight lang="kotlin">
var <propertyName>[: <PropertyType>] [= <property_initializer>]
    [<getter>]
    [<setter>]
</syntaxhighlight>إذ يُعدُّ وجودُ كلّ من التهيئة وعمليات الوصول (getter و setter) أمرًا اختياريًا، ويصبح وجود النوع اختياريًا أيضًا إذا أمكن تحديده من خلال التهيئة (أو من النوع المُعاد في دالة getter) كما في الأمثلة الآتية:<syntaxhighlight lang="kotlin">
var allByDefault: Int? // تحدث مشكلة: يجب وجود التهيئة بشكل واضح، ودوال الوصول 
 الافتراضيّة ضمنيّة 
var initialized = 1 // النوع هو نوع الأعداد الصحيحة ودوال الوصول افتراضيّة

</syntaxhighlight>أمّا الصيغة الكاملة للتصريح عن خاصّيّات القراءة فقط فهي مختلفةٌ عن سابقتها من ناحيتين: الأولى أنّها تبدأ بالكلمة المفتاحيّة <code>val</code> بدلًا من <code>var</code>، والثانية أنه لا وجود لدالة الوصول setter، وهي بالصيغة:<syntaxhighlight lang="kotlin">
val simple: Int? // للخاصية نوع الأعداد الصحيحة ويجب القيام بعملية التهيئة في الباني ودالة الوصول الافتراضية getter

val inferredType = 1 // لها نوع الأعداد الصحيحة ودالة وصول افتراضية getter

</syntaxhighlight>ويُمكن تخصيص دوال الوصول (accessors) مثل عملية تعديل أيّ دالة أخرى وذلك في تعريف الخاصّيّة، مثل تخصيص getter في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
val isEmpty: Boolean
    get() = this.size == 0
</syntaxhighlight>أمّا تخصيص الدالة setter فهو كما في الشيفرة:<syntaxhighlight lang="kotlin">
var stringRepresentation: String
    get() = this.toString()
    set(value) {
        setDataFromString(value) // تحويل السلسلة النصية وإسناد القيمة إلى خاصّيّة أخرى
    }
</syntaxhighlight>إذ تعبِّر <code>value</code> -اصطلاحًا- عن اسم المتحول في setter ويمكن تعديله.

وبدءًا من الإصدار 1.1 يمكن حذف نوع الخاصّيّة إذا أمكن تحديده من خلال getter مثل:<syntaxhighlight lang="kotlin">
val isEmpty get() = this.size == 0  // لها النوع Boolean
</syntaxhighlight>ويمكن في بعض الأحيان تعريفُ (define) أيّ من دوال الوصول (accessors) بدون تعريف بُنيتها (body) وذلك عند الحاجة لتغيير مرئيّة الوصول لها (visibility) أو إضافة الحاشية (annotation) دون تغيير تعريف الاستخدام (implementation) الافتراضيّ، كما هو الحال في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
var setterVisibility: String = "abc"
    private set // محدد الوصول هو من النوع الخاص وله تعريف الاستخدام الافتراضيّ

var setterWithAnnotation: Any? = null
    @Inject set // إضافة الحاشية إليه باسم Inject

</syntaxhighlight>

== الحقول المُساعدة (Backing Fields) ==
لا تُعرَّف الحقول مباشرةً في الأصناف (classes) في لغة Kotlin لذلك فإنه عند الحاجة لحقلٍ مساعدٍ فإن Kotlin تزوِّد به تلقائيًا، ويُشار إليه في دوال الوصول عبر المُحدِّد <code>field</code>، مثل:<syntaxhighlight lang="kotlin">
var counter = 0 // تُسند القيمة أيضًا للحقل المساعد مباشرة
    set(value) {
        if (value >= 0) field = value
    }
</syntaxhighlight>إذ إن استخدام المُحدِّد <code>field</code> متاحٌ فقط في دوال الوصول (accessors) لتلك الخاصية.

ويُولَّد الحقل المُساعد للخاصية إذا ما استخدَمت تعريف الاستخدام (implementation) الافتراضيّ لدوال الوصول ولو لمرةٍ واحدةٍ أو في حالة الإشارة لها عبر المُحدِّد <code>field</code> عند تخصيص أيّ من دوال الوصول، فلن يكون هناك مثلًا حقلٌ مساعدٌ في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
val isEmpty: Boolean
    get() = this.size == 0
</syntaxhighlight>

== الخاصّيّات المُساعدِة (Backing Properties) ==
عند القيام بما يتعارض مع آليّة الحقول المُساعدة الضمنيّة (المشروحة في الفقرة السابقة) فيُعمَد لاستخدام الخاصيّات المُساعدِة كما هو الحال في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
private var _table: Map<String, Int>? = null
public val table: Map<String, Int>
    get() {
        if (_table == null) {
            _table = HashMap() // تُحدد متحولات النوع تلقائيًا
        }
        return _table ?: throw AssertionError("Set to null by another thread")
    }
</syntaxhighlight>وهذا يماثل -من كافّة النواحي- ما هو مُعتمدٌ في لغة Java، لأن الوصول إلى الخاصيات من النوع الخاصّ (private) باستخدام الدوال الافتراضيّة للوصول (accessor) مُصمَّمٌ بحيث لا يمكن تجاوزه من قِبل أيّ استدعاءٍ للدوال.

== ثوابت الترجمة (Compile-Time Constants) ==
تٌحدَّد الخاصّيّات التي تُعرَف قيمتها (known) أثناء عملية الترجمة باعتبارها "ثوابت الترجمة" وذلك باستخدام المُحدِّد <code>const</code>، ولها المتطلَّبات الآتية:
* أن تكون أحدَ العناصر (members) في <code>object</code> أو واقعة بمستوى أعلى (top-level)
* مُهيَّئةٌ بالقيمة من النوع <code>String</code>  أو أيّ نوع أساسي (primitive) آخر
* لا يوجد لها getter مُخصَّص
وتستخدم مثل هذه الخاصّيّات في الحاشيات (annotations) مثل:<syntaxhighlight lang="kotlin">
const val SUBSYSTEM_DEPRECATED: String = "This subsystem is deprecated"

@Deprecated(SUBSYSTEM_DEPRECATED) fun foo() { ... }
</syntaxhighlight>

== التهيئة اللاحقة (Late-Initializing) للخاصيات (Properties) والمتحوِّلات (Variables) ==
تُهيَّأ الخاصّيّات المُعرَّفة بالحالة الطبيعيّة من النوع بدون قيم فارغة (non-null) في الباني (constructor) ولكنّ ذلك لا يكون مناسبًا دائمًا، إذ يُمكن مثلًا أن تُهيَّأ خلال إضافة الاستقلاليّة (dependency injection) أو بتابع الإعداد (setup method) لاختبار البُنية (unit test)، ولا يُمكن حينئذٍ الاعتماد على تهيئةٍ non-null في الباني على الرغم من الرغبة بتجنُّب عمليات التحقُّق من القيم الفارغة عند الإشارة (reference) إلى الخاصّيّات داخل بنية الصنف (class body).

ولمعالجة هذه الحالة تُعتمَد التهيئة اللاحقة عبر المُحدِّد <code>lateinit</code> مثل:<syntaxhighlight lang="kotlin">
public class MyTest {
    lateinit var subject: TestSubject

    @SetUp fun setup() {
        subject = TestSubject()
    }

    @Test fun test() {
        subject.method()  // ٌإسنادٌ مؤشريّ مباشر
    }
}
</syntaxhighlight>ويُستخدَم هذا المُحدِّد مع الخاصّيّات من النوع <code>var</code> المُعرَّفة داخل بُنية الصنف (وليس في الباني الأساسي [primary constructor] وفقط عندما لا يكون هناك تخصيص في دوال الوصول [accessors])، واعتبارًا من الإصدار Kotlin 1.2 يُستخدَم أيضًا للخاصيّات بمستوى أعلى (top-level) وللمتحوِّلات المحلية (local variables)، إذ يجب أن يكون النوع فيها نوعًا أساسيًا (primitive) ولا يقبل القيم الفارغة (non-null).

و ينتُج عن محاولة الوصول إلى الخاصّيّة قبل تهيئتها اللاحقة استثناءٌ (exception) خاصّ يُفيد بأنّه قد تمّ الوصول إلى الخاصّيّة قبل تهيئتها.

== التأكد من التهيئة اللاحقة للمتحول <code>var</code> (بدءًا من الإصدار 1.2) ==
تُستخدَم <code>‎.‎isInitialized</code>‎ مع [[Kotlin/reflection|مرجعيّة (reference) الخاصّيّة]] المُحدَّدة بالمُعرِّفين <code>lateinit var</code> للتحقُّق من إتمام عملية التهيئة اللاحقة لها، مثل:<syntaxhighlight lang="kotlin">
if (foo::bar.isInitialized) {
    println(foo.bar)
}
</syntaxhighlight>ويُسمَح بهذا التحقق  فقط عندما يكون الوصول لهذه الخاصيّة مُتاحًا (accessible)، أي أنها مُعرَّفةٌ من نفس النوع أو أحد الأنواع الخارجية (outer) أو بمستوى أعلى (top-level) في نفس الملف (file).

== إعادة تعريف الخاصّيّات (Overriding Properties) ==
راجع [[Kotlin/classes|إعادة تعريف الخاصّيّات (Overriding Properties)]]

== الخاصّيّات المُعمَّمة (Delegated Properties) ==
إنّ النوع الأكثر شيوعًا للخاصّيّات مُعدٌّ للقراءة من (وربما الكتابة في) الحقل المُساعِد، أمّا في حالة تخصيص دوال الوصول (getter أو setter) فيُمكن تعريف استخدام (implement) أيّ سلوكٍ للخاصّيّة، وهناك أنماطٌ مُحدَّدةٌ لكيفية عمل الخاصّيّة، مثل: القيم الكسولة (lazy value) أو القراءة من map من خلال المفتاح (key)، أو الوصول إلى قاعدة البيانات أو الإعلام عند محاولة الوصول أو... إلخ، ومثلُ هذه الحالات يُمكن تعريف استخدامها كمكتباتٍ (libraries) باستخدام [[Kotlin/delegated properties|الخاصّيّات المُعمَّمة (delegated properties)]].

== مصادر ==
* [https://kotlinlang.org/docs/reference/properties.html صفحة الخاصيّات في التوثيق الرسمي للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Properties]]
[[تصنيف:Kotlin Accessors]]