مرجع سمات الأدوات (طرق العرض)

المفاهيم والتنفيذ في Jetpack Composearrow_forward

يتيح استوديو Android مجموعة متنوعة من سمات تنسيق XML في مساحة الاسم tools التي تتيح ميزات وقت التصميم، مثل التنسيق الذي سيتم عرضه في جزء، أو سلوكيات وقت التجميع، مثل وضع التصغير الذي سيتم تطبيقه على موارد تنسيق XML. عند إنشاء تطبيقك، تزيل أدوات الإنشاء هذه السمات حتى لا يكون لها أي تأثير على حجم حزمة APK أو سلوك وقت التشغيل.

لاستخدام هذه السمات، أضِف مساحة الاسم tools إلى العنصر الجذر لكل ملف XML تريد استخدامها فيه، كما هو موضّح هنا:

<RootTag xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" >

سمات معالجة الأخطاء

تساعد السمة التالية في إيقاف رسائل التحذير من أداة Lint:

tools:targetApi

مخصّصة لـ: أي عنصر

المستخدم: Lint

تعمل هذه السمة بالطريقة نفسها التي تعمل بها التعليق التوضيحي @TargetApi في رمز Java. تتيح لك هذه السمة تحديد مستوى واجهة برمجة التطبيقات (إما كعدد صحيح أو كاسم رمزي) الذي يتوافق مع هذا العنصر.

يُعلم ذلك الأدوات بأنّك تعتقد أنّ هذا العنصر وأي عناصر فرعية تُستخدم فقط في مستوى واجهة برمجة التطبيقات المحدّد أو أعلى. يمنع ذلك أداة Lint من عرض تحذير إذا لم يكن العنصر أو سماته متوفّرة في مستوى واجهة برمجة التطبيقات الذي تحدّده minSdkVersion.

على سبيل المثال، يمكنك استخدام هذه السمة لأنّ GridLayout لا يتوفّر إلا في مستوى واجهة برمجة التطبيقات 14 والإصدارات الأحدث، ولكنك تعلم أنّ هذا التصميم لا يُستخدَم في الرمز البرمجي لأي إصدارات أقدم:

<GridLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:targetApi="14" >

(ومع ذلك، يُرجى العِلم أنّنا ننصحك باستخدام GridLayout من مكتبة الدعم بدلاً من ذلك).

سمات العرض في وقت التصميم

تحدّد السمات التالية خصائص التنسيق التي تظهر فقط في معاينة التنسيق في "استوديو Android".

‫tools: بدلاً من android:

مخصّص لما يلي: <View>

مستخدَمة من قِبل: أداة تعديل التصميم في "استوديو Android"

يمكنك إدراج بيانات نموذجية في معاينة التصميم باستخدام البادئة tools: بدلاً من android: مع أي سمة <View> من إطار عمل Android. يكون ذلك مفيدًا عندما لا تتم تعبئة قيمة السمة إلا في وقت التشغيل، وتريد الاطّلاع على التأثير في معاينة التنسيق.

على سبيل المثال، إذا تم ضبط قيمة السمة android:text في وقت التشغيل، أو إذا أردت الاطّلاع على التصميم بقيمة مختلفة عن القيمة التلقائية، يمكنك إضافة tools:text لتحديد بعض النصوص لمعاينة التصميم فقط.

يمكنك إضافة سمة مساحة الاسم android:، التي يتم استخدامها في وقت التشغيل، وسمة tools: المطابقة، التي تحل محل سمة وقت التشغيل في معاينة التصميم فقط.

يمكنك أيضًا استخدام السمة tools: للتراجع عن إعداد سمة لمعاينة التنسيق فقط. على سبيل المثال، إذا كان لديك FrameLayout يتضمّن عنصرَين فرعيَين ولكنك تريد عرض عنصر فرعي واحد فقط في معاينة التصميم، يمكنك ضبط أحد العنصرَين ليكون غير مرئي في معاينة التصميم، كما هو موضّح هنا:

<Button
    android:id="@+id/button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="First" />

<Button
    android:id="@+id/button2"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Second"
    tools:visibility="invisible"  />

عند استخدام أداة تعديل التنسيق في عرض التصميم، تتيح لك نافذة الخصائص تعديل بعض سمات طريقة العرض في وقت التصميم. يتم الإشارة إلى كل سمة من سمات وقت التصميم باستخدام رمز مفتاح ربط بجانب اسم السمة للتمييز بينها وبين السمة الحقيقية التي تحمل الاسم نفسه.

tools:context

مخصّص لما يلي: أي جذر <View>

يستخدمه: Lint وأداة تعديل التصميم في "استوديو Android"

تحدّد هذه السمة النشاط الذي يرتبط به هذا التصميم تلقائيًا. يتيح ذلك ميزات في المحرّر أو معاينة التصميم تتطلّب معرفة النشاط، مثل موضوع التصميم في المعاينة ومكان إدراج معالجات onClick التي تم إنشاؤها من إصلاح سريع، كما هو موضّح في الشكل 2.

يمكنك تحديد اسم فئة النشاط باستخدام بادئة النقطة نفسها كما في ملف البيان (باستثناء اسم الحزمة الكامل).

على سبيل المثال:

<android.support.constraint.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:context=".MainActivity" >

tools:itemCount

مخصّص لما يلي: <RecyclerView>

يُستخدم من قِبل: أداة تعديل التصميم في "استوديو Android"

بالنسبة إلى RecyclerView معيّن، تحدّد هذه السمة عدد العناصر التي يجب أن تعرضها أداة تعديل التنسيق في نافذة المعاينة.

على سبيل المثال:

<androidx.recyclerview.widget.RecyclerView
    android:id="@+id/recyclerView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:itemCount="3"/>

tools:layout

مخصّص لما يلي: <fragment>

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تحدّد هذه السمة التصميم الذي تريد أن ترسمه معاينة التصميم داخل الجزء، لأنّ معاينة التصميم لا يمكنها تنفيذ رمز النشاط الذي يطبّق التصميم عادةً.

على سبيل المثال:

<fragment android:name="com.example.main.ItemListFragment"
    tools:layout="@layout/list_content" />

tools:listitem وtools:listheader وtools:listfooter

مخصّص لـ: <AdapterView> (والفئات الفرعية مثل <ListView>)

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تحدّد هذه السمات التصميم الذي سيتم عرضه في معاينة التصميم الخاصة بعناصر القائمة ورأسها وتذييلها. يتم ملء أي حقول بيانات في التصميم بمحتوى رقمي، مثل "العنصر 1"، حتى لا تكون عناصر القائمة متكررة.

على سبيل المثال:

<ListView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@android:id/list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:listitem="@layout/sample_list_item"
    tools:listheader="@layout/sample_list_header"
    tools:listfooter="@layout/sample_list_footer" />

tools:showIn

مخصّص لـ: أي عنصر جذر <View> في تصميم يشار إليه بواسطة <include>

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تتيح لك هذه السمة الإشارة إلى تصميم يستخدم هذا التصميم باستخدام <include>، ما يتيح لك معاينة هذا الملف وتعديله كما يظهر عند تضمينه في تصميم العنصر الرئيسي.

على سبيل المثال:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:text="@string/hello_world"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    tools:showIn="@layout/activity_main" />

تعرض معاينة التنسيق الآن تنسيق TextView كما يظهر داخل التنسيق activity_main.

tools:menu

مخصّص لما يلي: أي جذر <View>

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تحدّد هذه السمة القائمة التي تعرضها معاينة التصميم في شريط التطبيق. القيمة هي معرّف واحد أو أكثر من معرّفات القوائم، مفصولة بفواصل، بدون @menu/ أو أي بادئة معرّف من هذا النوع وبدون الإضافة .xml.

على سبيل المثال:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:menu="menu1,menu2" />

tools:minValue، tools:maxValue

مخصّص لما يلي: <NumberPicker>

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تحدّد هاتان السمتان الحدّين الأدنى والأقصى NumberPicker.

على سبيل المثال:

<NumberPicker xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/numberPicker"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    tools:minValue="0"
    tools:maxValue="10" />

tools:openDrawer

مخصّص لما يلي: <DrawerLayout>

مستخدَمة من قِبل: "أداة تعديل التنسيق" في "استوديو Android"

تتيح لك هذه السمة فتح DrawerLayout في المعاينة.

يمكنك أيضًا تعديل طريقة عرض "أداة تعديل التصميم" للتصميم من خلال تمرير إحدى القيم التالية:

الجدول 1. قيم لتعديل طريقة عرض DrawerLayout في "أداة تعديل التنسيق"

على سبيل المثال:

<androidx.drawerlayout.widget.DrawerLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/drawer_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:openDrawer="start" />

"@tools:sample/*" مورد

مخصّص لما يلي: أي طريقة عرض تتوافق مع نصوص أو صور واجهة المستخدم

يُستخدم من قِبل: أداة تعديل التصميم في "استوديو Android"

تتيح لك هذه السمة إدخال بيانات أو صور عنصر نائب في طريقة العرض. على سبيل المثال، لاختبار طريقة عمل التصميم مع النص قبل الانتهاء من نص واجهة المستخدم لتطبيقك، يمكنك استخدام نص العنصر النائب على النحو التالي:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    tools:text="@tools:sample/lorem" />

يوضّح الجدول التالي أنواع بيانات العناصر النائبة التي يمكنك إدراجها في التصميمات:

الجدول 2. بيانات العناصر النائبة للتنسيقات