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

في حين أنّ Jetpack Compose يعالج أدوات وقت تصميم واجهة المستخدم مباشرةً في Kotlin، تظلّ مساحة الاسم tools: ضرورية للإعدادات على مستوى المشروع. تستخدم ملفات XML العادية في Android، مثل AndroidManifest.xml وres/raw/keep.xml، سمات tools: لإدارة تحذيرات lint وضبط أداة تقليص الموارد.

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

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

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

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

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

tools:ignore

الهدف: أي عنصر

الاستخدام: Lint

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

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

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

tools:targetApi

الهدف: أي عنصر

الاستخدام: Lint

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

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

على سبيل المثال، قد تستخدم هذه السمة لأنّك تعرّف <service> في AndroidManifest.xml يستخدم نوع خدمة تعمل في المقدّمة لا يتوفّر إلا على مستوى واجهة برمجة التطبيقات 34 والإصدارات الأحدث، ولكن minSdkVersion في مشروعك أقل من ذلك:

<service
    android:name=".playback.MediaPlaybackService"
    android:foregroundServiceType="mediaPlayback"
    xmlns:tools="http://schemas.android.com/tools"
    tools:targetApi="34" />

tools:locale

الهدف: <resources>

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

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

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

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

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

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

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

لتفعيل تقليص الموارد، اضبط السمة 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" />

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تقليص الموارد.

مراجع إضافية

عرض المحتوى