مرجع مشخصه‌های ابزارها (نماها)

مفاهیم و پیاده‌سازی Jetpack Composearrow_forward

Android Studio از انواع مشخصه‌های 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 عمل می‌کند. این ویژگی به شما امکان می‌دهد سطح میانای برنامه‌سازی کاربردی (به‌صورت عدد صحیح یا نام رمزی) را که از این عنصر پشتیبانی می‌کند مشخص کنید.

این به ابزارها می‌گوید که شما معتقدید این عنصر و هر فرزند فقط در سطح API مشخص‌شده یا بالاتر استفاده می‌شود. این کار باعث می‌شود که اگر آن عنصر یا ویژگی‌های آن در سطح میانای برنامه‌سازی کاربردی که به‌عنوان minSdkVersion مشخص کرده‌اید دردسترس نباشد، lint به شما هشدار ندهد.

برای مثال، ممکن است از این مشخصه استفاده کنید چون GridLayout فقط در سطح میانای برنامه‌سازی کاربردی ۱۴ و بالاتر دردسترس است، اما می‌دانید که این چیدمان در کد شما برای نسخه‌های پایین‌تر استفاده نمی‌شود:

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

(بااین‌حال، توجه داشته باشید که توصیه می‌کنیم درعوض از GridLayout از کتابخانه پشتیبانی استفاده کنید.)

مشخصه‌های نمای زمان طراحی

مشخصه‌های زیر ویژگی‌های طرح‌بندی را تعریف می‌کنند که فقط در پیش‌نمای طرح‌بندی Android Studio قابل‌مشاهده هستند.

tools: به‌جای android:

مخاطب: <View>

استفاده‌شده توسط: ویرایشگر چیدمان Android Studio

می‌توانید بااستفاده از پیشوند 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 تولیدشده از اصلاح سریع را درج کرد، همان‌طور که در شکل ۲ نشان داده شده است.

می‌توانید نام کلاس فعالیت را بااستفاده از همان پیشوند نقطه که در فایل مانیفست استفاده شده است (بدون نام کامل بسته) مشخص کنید.

برای مثال:

<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 Studio

برای 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»

این مشخصه‌ها تعیین می‌کنند کدام چیدمان در پیش‌نمایش چیدمان برای موارد، سرصفحه، و پاصفحه فهرست نشان داده شود. هر فیلد داده در چیدمان با محتوای عددی، مثل «مورد ۱»، پر شده است تا موارد فهرست تکراری نباشند.

برای مثال:

<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 را در پیش‌نمایش باز کنید.

همچنین می‌توانید با ارسال یکی از مقادیر زیر، نحوه ارائه چیدمان توسط «ویرایشگر چیدمان» را تغییر دهید:

جدول ۱. مقادیری برای اصلاح نحوه پرداخت 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 Studio

این مشخصه به شما امکان می‌دهد داده‌ها یا تصاویر جای‌بان را به نمای خود تزریق کنید. برای مثال، برای آزمایش نحوه رفتار چیدمان با نوشتار قبل‌از اینکه نوشتار واسط کاربر را برای برنامه‌تان نهایی کنید، می‌توانید از نوشتار جای‌بان به‌صورت زیر استفاده کنید:

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

جدول زیر انواع داده‌های مکان‌نما را که می‌توانید به چیدمان‌هایتان تزریق کنید شرح می‌دهد:

جدول ۲. داده‌های جای‌بان برای چیدمان‌ها