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

يتيح "استوديو 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:ignore

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

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

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

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

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

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 من مكتبة الدعم بدلاً من ذلك).

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 لتحديد بعض النصوص لمعاينة التنسيق فقط.

تضبط سمة tool: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 إلا في حال ضبط الأدوات: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

ثابتالقيمةالوصف
end800005دفع الكائن إلى نهاية حاويته، بدون تغيير حجمه.
left3اضغط على العنصر إلى يسار حاويته، بدون تغيير حجمه.
right5دفع الكائن إلى يمين حاويته، بدون تغيير حجمه.
start800003دفع الكائن إلى بداية حاويته، بدون تغيير حجمه.

مثلاً:

<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 لتقليص الرموز.

مثلاً:

Groovy

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" />

لمزيد من المعلومات، يُرجى مراجعة تقليل الموارد: