تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مرجع سمات الأدوات

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

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

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

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

تساعد السمات التالية في منع رسائل التحذير من الوبر:

`tools:ignore`

الغرض منه: أي عنصر

قيد الاستخدام بواسطة: Lint

تقبل هذه السمة قائمة مفصولة بفواصل من معرّفات مشاكل الوبر التي تريد أن تتجاهلها الأدوات على هذا العنصر أو أي عناصر تابعة له.

على سبيل المثال، يمكنك الطلب من الأدوات تجاهل الخطأ MissingTranslation:

<string name="show_all_apps" tools:ignore="MissingTranslation">All</string>

`tools:targetApi`

الغرض من ذلك: أي عنصر

قيد الاستخدام بواسطة: Lint

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

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

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

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

(مع ذلك، نقترح استخدام GridLayout من مكتبة الدعم بدلاً من ذلك.)

`tools:locale`

مخصّص لـ: <resources>

قيد الاستخدام من قِبل: Lint، محرِّر "استوديو Android"

يتيح هذا الإجراء للأدوات التعرّف على اللغة أو اللغة التلقائية للموارد في عنصر <resources> المحدّد لتجنُّب تلقّي تحذيرات من المدقق الإملائي. وتفترض الأداة أن اللغة هي الإنجليزية.

يجب أن تكون القيمة مؤهِّل لغة صالحًا.

على سبيل المثال، يمكنك إضافة هذا إلى ملف values/strings.xml التلقائي للإشارة إلى أنّ اللغة المستخدمة للسلاسل التلقائية هي الإسبانية بدلاً من الإنجليزية:

<resources xmlns:tools="http://schemas.android.com/tools"
    tools:locale="es">

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

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

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

مخصّص لـ: <View>

المستخدم: محرِّر تنسيق "استوديو Android"

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

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

تحدّد السمة Tools:text خدمة Google Voice كقيمة لمعاينة التنسيق. — **الشكل 1.** وتضبط السمة `tools:text` "Google Voice" كقيمة لمعاينة التنسيق.

يمكنك إضافة كلّ من سمة مساحة الاسم 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.

لا يعمل الأمر السريع
لسمة onClick إلا في حال ضبط Tools:context. — **الشكل 2.** لا يعمل الإصلاح السريع للسمة `onClick` إلا في حال ضبط السمة `tools:context`.

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

مثلاً:

<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

ثابت	القيمة	الوصف
`end`	800005	دفع الكائن إلى نهاية حاويته، بدون تغيير حجمه.
`left`	3	دفع الكائن إلى يسار حاويته، بدون تغيير حجمه.
`right`	5	دفع الكائن إلى يمين الحاوية، بدون تغيير حجمه.
`start`	800003	دفع الكائن إلى بداية حاويته، بدون تغيير حجمه.

مثلاً:

<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. البيانات النائبة للتخطيطات

قيمة السمة	وصف بيانات العنصر النائب
`@tools:sample/full_names`	تم إنشاء الأسماء الكاملة بشكل عشوائي من خلال الجمع بين `@tools:sample/first_names` و`@tools:sample/last_names`.
`@tools:sample/first_names`	الأسماء الأولى الشائعة
`@tools:sample/last_names`	أسماء العائلة الشائعة
`@tools:sample/cities`	أسماء المدن حول العالم
`@tools:sample/us_zipcodes`	الرموز البريدية في الولايات المتحدة التي يتم إنشاؤها عشوائيًا
`@tools:sample/us_phones`	أرقام هواتف تم إنشاؤها عشوائيًا بالتنسيق التالي: `(800) 555-xxxx`
`@tools:sample/lorem`	نص العنصر النائب باللغة اللاتينية
`@tools:sample/date/day_of_week`	ترتيب عشوائي للتواريخ والأوقات للتنسيق المحدد
`@tools:sample/date/ddmmyy`
`@tools:sample/date/mmddyy`
`@tools:sample/date/hhmm`
`@tools:sample/date/hhmmss`
`@tools:sample/avatars`	رسومات متّجهة يمكنك استخدامها كصور رمزية لملفك الشخصي
`@tools:sample/backgrounds/scenic`	الصور التي يمكنك استخدامها كخلفيات

سمات تقليص الموارد

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

لتفعيل تقليص الموارد، اضبط السمة shrinkResources على true في ملف build.gradle إلى جانب السمة minifyEnabled لتقليص الرموز.

مثلاً:

رائع

android {
    ...
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                    'proguard-rules.pro'
        }
    }
}

Kotlin

android {
    ...
    buildTypes {
        getByName("release") {
            isShrinkResources = true
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

`tools:shrinkMode`

مخصّص لـ: <resources>

قيد الاستخدام من قِبل: إنشاء أدوات تتيح تقليص الموارد

تتيح لك هذه السمة تحديد ما إذا كان يجب أن تستخدم أدوات الإصدار ما يلي:

الوضع الآمن: احتفظ بجميع الموارد التي يتم الاستشهاد بها صراحةً والتي قد تتم الإشارة إليها ديناميكيًا من خلال توجيه طلب إلى Resources.getIdentifier().
الوضع المتشدد: احتفِظ بالموارد المذكورة بشكل صريح في الرمز أو في موارد أخرى فقط.

الإعداد التلقائي هو استخدام الوضع الآمن (shrinkMode="safe"). ولاستخدامه بدلاً منه، أضِف shrinkMode="strict" إلى العلامة <resources> كما هو موضّح هنا:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:shrinkMode="strict" />

عند تفعيل الوضع الصارم، قد تحتاج إلى استخدام tools:keep للاحتفاظ بالموارد التي تمت إزالتها ولكنك تريدها، واستخدام tools:discard لإزالة المزيد من الموارد بشكل صريح.

لمزيد من المعلومات، راجع تقليص الموارد.

`tools:keep`

مخصّص لـ: <resources>

قيد الاستخدام من قِبل: إنشاء أدوات تتيح تقليص الموارد

عند استخدام ميزة تقليص الموارد لإزالة الموارد غير المستخدَمة، تتيح لك هذه السمة تحديد الموارد المطلوب الاحتفاظ بها، وعادةً ما تتم الإشارة إليها بطريقة غير مباشرة في وقت التشغيل، مثلاً من خلال تمرير اسم مورد تم إنشاؤه ديناميكيًا إلى Resources.getIdentifier().

لاستخدام هذه الميزة، أنشئ ملف XML في دليل الموارد (مثلاً res/raw/keep.xml) مع علامة <resources> وحدِّد كل مورد للاحتفاظ به في السمة tools:keep على شكل قائمة مفصولة بفواصل. يمكنك استخدام علامة النجمة كحرف بدل.

مثلاً:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/used_1,@layout/used_2,@layout/*_3" />

لمزيد من المعلومات، راجع تقليص الموارد.

`tools:discard`

مخصّص لـ: <resources>

قيد الاستخدام من قِبل: إنشاء أدوات تتيح تقليص الموارد

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

لاستخدام هذه الميزة، أنشئ ملف XML في دليل الموارد (على سبيل المثال، res/raw/keep.xml) مع علامة <resources> وحدِّد كل مورد تريد تجاهله في السمة tools:discard على شكل قائمة مفصولة بفواصل. يمكنك استخدام علامة النجمة كحرف بدل.

مثلاً:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:discard="@layout/unused_1" />

لمزيد من المعلومات، راجع تقليص الموارد.

مرجع سمات الأدوات

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

tools:ignore

tools:targetApi

tools:locale

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

tools: بدلاً من android:

tools:context

tools:itemCount

tools:layout

tools:listitem وtools:listheader وtools:listfooter

tools:showIn

tools:menu

tools:minValue، tools:maxValue

tools:openDrawer

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

سمات تقليص الموارد

رائع

Kotlin

tools:shrinkMode

tools:keep

tools:discard

`tools:ignore`

`tools:targetApi`

`tools:locale`

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

`tools:context`

`tools:itemCount`

`tools:layout`

`tools:listitem` و`tools:listheader` و`tools:listfooter`

`tools:showIn`

`tools:menu`

`tools:minValue`، `tools:maxValue`

`tools:openDrawer`

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

`tools:shrinkMode`

`tools:keep`

`tools:discard`