نظرة عامة على واجهة سطر الأوامر في Android

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

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

تثبيت واجهة سطر الأوامر لنظام التشغيل Android

لتثبيت واجهة سطر الأوامر لنظام التشغيل Android، اتّبِع الخطوات التالية:

  1. نزِّل واجهة سطر الأوامر لنظام التشغيل Android.

  2. للتأكّد من استخدام أحدث إصدار، عليك تعديل واجهة سطر الأوامر لنظام التشغيل Android باتّباع الخطوات التالية:

    android update

للتحقّق مما إذا كانت واجهة سطر الأوامر لنظام التشغيل Android مثبّتة على جهازك، شغِّل الأمر which android أو command -v android. إذا عرضت الواجهة مسارًا، يعني ذلك أنّها مثبّتة.

إعداد الوكلاء

لمساعدة الوكلاء في فهم واجهة سطر الأوامر لنظام التشغيل Android واستخدامها، شغِّل init لتثبيت مهارة android-cli:

android init

المشاكل المعروفة

  • الأمر android emulator لنظام التشغيل Windows غير مفعَّل حاليًا.

إذا واجهت أي مشاكل أو أردت تقديم ملاحظات، يُرجى الإبلاغ عن خطأ.

الخيارات العامة

هذه علامات اختيارية يمكنك استخدامها مع أوامر أخرى في واجهة سطر الأوامر لنظام التشغيل Android.

-h, --help

الاستخدام: android <command> -h

الوصف: لعرض دليل المساعدة الخاص بالأداة أو الأمر المحدّد المعنيّ.

أمثلة:

  • android -h
  • android create -h

--sdk

الاستخدام: android --sdk=<path-to-sdk> <command>

الوصف: مسار حزمة تطوير البرامج (SDK) لنظام التشغيل Android التي تريد استخدامها للأمر التالي. يمكنك استخدام الإعداد --sdk لتجاوز حزمة تطوير البرامج (SDK) التلقائية لنظام التشغيل Android مؤقتًا بدلاً من تغيير متغيّرات البيئة العامة في كل مرة تريد التبديل فيها. لمعرفة حزمة تطوير البرامج (SDK) لنظام التشغيل Android التي تستخدمها تلقائيًا، شغِّل android info.

مثال: android --sdk=<path/to/sdk> sdk list

الطلبات الصوتية

يسرد هذا القسم جميع أوامر Android CLI ويشرح وظائفها. يجب أن يسبق كل هذه الأوامر android، على سبيل المثال android create وandroid run وما إلى ذلك. يتم تضمين المعدِّلات الاختيارية بين قوسين []، بينما لا يتم تضمين الوسيطات الإلزامية.

create

الاستخدام: android create [--dry-run] [--verbose] [--name=<application-name>] [--output=<dest-path>] [<template-name>]

الوصف: يمكنك بدء مشروع جديد من نموذج. للاطّلاع على خيارات النموذج، شغِّل android create -h.

الوسيطات (إلزامية):

  • ‫-o, --output: مسار دليل المشروع الوجهة

الخيارات:

  • --dry-run - يحاكي عملية إنشاء المشروع بأكملها بدون حفظ أي ملفات. على سبيل المثال، يمكنك إجراء تشغيل تجريبي لمعرفة وظيفة النماذج المختلفة قبل اختيار أحدها.
  • --verbose: يتيح إخراجًا مفصّلاً، بما في ذلك معلومات مثل الملفات التي يتم نسخها من النموذج.
  • استبدِل --name=<application-name> باسم دليل المشروع. في حال عدم تحديدها، يتم استخدام دليل الإخراج.
  • <template-name> - اسم النموذج الذي سيتم إنشاء مشروع جديد منه. في حال عدم إدخال قيمة، يتم استخدام empty-activity-agp-9.

مثال: android create --dry-run --verbose empty-activity-agp-9

create list

الاستخدام: android create list

الوصف: تعرض هذه السمة جميع النماذج المتاحة لإنشاء مشروع جديد.

describe

الاستخدام: android describe [--project_dir=<project-directory>]

الوصف: يحلّل مشروع Android لإنشاء بيانات وصفية. يحدّد هذا الأمر مسارات ملفات JSON التي توفّر تفاصيل حول بنية المشروع، بما في ذلك أهداف الإنشاء ومواقع عناصر الإخراج ذات الصلة (مثل ملفات APK)، ويعرضها. تتيح هذه المعلومات للأدوات والأوامر الأخرى تحديد موقع عناصر البناء بكفاءة.

الخيارات:

  • --project_dir: دليل المشروع الذي تريد وصفه. في حال عدم إدخال قيمة، يتم استخدام الدليل الحالي.

مثال: android describe --project_dir=/path/to/your/project

docs

الاستخدام:

  • android docs search <query>
  • android docs fetch <kb-url>

الوصف: الأمر android docs هو عملية تتألف من خطوتَين للوصول إلى قاعدة معارف Android مباشرةً من واجهة سطر الأوامر. أولاً، ابحث عن المستندات ذات الصلة بطلب البحث باستخدام الأمر search. ستتضمّن نتائج البحث عناوين URL خاصة تبدأ بـ kb://، يمكنك بعد ذلك استخدامها مع الأمر fetch لعرض أوامر المستندات في الجهاز.

أمثلة:

  • android docs search 'How do I improve my app performance?'
  • android docs fetch kb://android/topic/performance/overview

emulator create

الاستخدام: android emulator create [--list-profiles] [--profile=<profile-name>]

الوصف: إنشاء جهاز افتراضي

الخيارات:

  • --list-profiles - تعرض هذه السمة قائمة بملفات تعريف الأجهزة التي يمكن استخدامها لإنشاء جهاز.
  • --profile=<profile-name>: لإنشاء جهاز باستخدام الملف الشخصي المحدّد. في حال حذف هذا الخيار، سيتم إنشاء ملف شخصي في medium_phone.

emulator list

الاستخدام: android emulator list

الوصف: أدرِج الأجهزة الافتراضية المتاحة.

emulator start

الاستخدام: android emulator start <device-name>

الوصف: تشغيل الجهاز الافتراضي المحدّد

الوسيطات (إلزامية):

  • <device-name>: اسم الجهاز الذي تريد بدء البث منه (مثلاً، medium_phone). استخدِم android emulator list للاطّلاع على الأجهزة المتاحة.

مثال: android emulator start medium_phone

emulator stop

الاستخدام: android emulator stop <device-serial-number>

الوصف: لإيقاف الجهاز الافتراضي المحدّد.

الوسيطات (إلزامية):

  • <device-serial-number>: الرقم التسلسلي للجهاز المطلوب إيقافه

مثال: android emulator stop emulator-5554

info

الاستخدام: android info

الوصف: عرض مسار حزمة تطوير البرامج (SDK) التلقائية لنظام التشغيل Android المستخدَمة لتغيير حزمة تطوير البرامج (SDK) لنظام التشغيل Android المستخدَمة، استخدِم --sdk.

init

الاستخدام: android init

الوصف: يمكنك إعداد بيئتك للوكلاء من خلال تثبيت مهارة android-cli.

layout

الاستخدام: android layout [--pretty] [--output] [--diff]

الوصف: تعرض هذه السمة تخطيط واجهة المستخدم لتطبيق Android النشط (المرتبط بجهاز فعلي أو محاكي) بتنسيق JSON.

الخيارات:

  • ‫-p, --pretty: ينسّق مخرجات JSON باستخدام المسافة البادئة والفواصل بين الأسطر لتسهيل قراءتها.
  • -o, --output: تحدّد موقع ملف لحفظ شجرة التنسيق. في حال عدم تحديد هذا الخيار، تتم طباعة JSON مباشرةً إلى stdout.
  • ‫-d, --diff: تعرض هذه السمة قائمة بعناصر التصميم التي تم تغييرها منذ آخر لقطة داخلية تم التقاطها (آخر مرة تم فيها تنفيذ التصميم)، بدلاً من شجرة التصميم الكاملة.

مثال:: android layout --output=./hierarchy.json

skills add

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

الاستخدام: android skills add [--all] [--agent=<agent-name>] [--skill=<skill-name>]

الوصف: تثبيت مهارات Android في أدلة المهارات لجميع الوكلاء الذين تم رصدهم إذا لم تكن لديك أي أدلة وكلاء حالية ولم تحدّد وكلاء معيّنين، سيتم تثبيت المهارات في Gemini وAntigravity في ~/.gemini/antigravity/skills.

الخيارات:

  • --all: إضافة جميع مهارات Android في آنٍ واحد في حال عدم توفّرها (وعدم تحديد --skill)، سيتم تثبيت مهارة android-cli فقط.
  • --agent: قائمة قيم مفصولة بفاصلة تضمّ الوكلاء الذين سيتم تثبيت المهارة لهم. في حال عدم توفُّرها، سيتم تثبيت المهارة لجميع البرامج التي تم رصدها.
  • ‫--skill: اسم المهارة التي تريد تثبيتها. في حال حذفها (وعدم تحديد --all)، سيتم تثبيت مهارة android-cli فقط.

مثال: android skills add --agent='gemini' edge-to-edge

skills find

الاستخدام: android skills find <string>

الوصف: ابحث عن المهارات التي تطابق سلسلة معيّنة.

الوسيطات (إلزامية):

  • ‫string: سلسلة تطابق وصف مهارة.

مثال: android skills find 'performance'

skills list

الاستخدام: android skills list [--long]

الوصف: أدرِج المهارات المتاحة.

الخيارات:

  • --long - تعرض هذه السمة معلومات إضافية لكل مهارة، بما في ذلك وصف المهارة والوكلاء الذين تم تثبيتها لهم.

skills remove

الاستخدام: android skills remove [--agent] --skill=<skill-name>

الوصف: لإزالة مهارة في حال عدم تحديد وكلاء معيّنين، ستتم إزالة المهارة من جميع الوكلاء.

الوسيطات (إلزامية):

  • استبدِل --skill باسم المهارة التي تريد إزالتها.

الخيارات:

  • --agent: قائمة قيم مفصولة بفاصلة تضمّ العملاء الذين ستتم إزالة المهارة منهم. في حال عدم توفيرها، ستتم إزالة المهارة من جميع الموظفين.

مثال: android skills remove --agent='gemini' --skill=edge-to-edge

screen capture

الاستخدام: android screen capture [--output] [--annotate]

الوصف: تلتقط هذه الخطوة لقطة شاشة للجهاز المتصل.

الخيارات:

  • -o, --output: تحدّد مكان الملف لحفظ لقطة الشاشة. في حال عدم تضمينها، ستتم طباعة بيانات PNG الأولية مباشرةً إلى stdout.
  • ‫-a, --annotate: يرسم مربّعات حدودية مصنّفة حول جميع عناصر واجهة المستخدم التي تم رصدها في الصورة، وذلك لاستخدامها مع الأمر resolve.

مثال: android screen capture --output=ui.png

screen resolve

الاستخدام: android screen resolve --screenshot=<path> --string=<string>

الوصف: يترجم التصنيفات المرئية من لقطة شاشة مزوّدة بتعليقات توضيحية، تم التقاطها باستخدام screen capture، إلى إحداثيات شاشة فعلية (س، ص). يفيد هذا الخيار في كتابة نصوص برمجية للنقر على العناصر بدون الحاجة إلى احتساب مواضعها يدويًا.

العلامات:

  • --screenshot: مسار لقطة الشاشة التي تمّت إضافة تعليقات توضيحية إليها
  • --string - سلسلة تتضمّن عنصر نائب واحدًا على الأقل يتوافق مع تصنيف عنصر في واجهة المستخدم بالتنسيق #<number>. سيتم استبدال الجزء #<number> بإحداثيات الشاشة.

مثال:

إذا كان التصنيف 5 يقع عند الإحداثيات (500, 1000)، فإنّ الأمر

android screen resolve --screenshot=ui.png --string="input tap #5"

تعرض الناتج

input tap 500 1000

sdk install

الاستخدام: android sdk install <package[@version]> [--beta] [--canary] [--force]

الوصف: تثبيت حِزم SDK المحدّدة

الوسيطات (إلزامية):

  • package[@version]: قائمة بالحِزم المطلوب تثبيتها مفصولة بمسافات إذا لم يتم تحديد إصدار، سيتم تثبيت أحدث إصدار من الحزمة في القناة (القناة الثابتة تلقائيًا).

الخيارات:

  • --beta: لتضمين حِزم الإصدار التجريبي
  • ‫--canary: لتضمين حِزم Canary
  • ‫--force: لفرض الرجوع إلى إصدار أقدم

أمثلة:

  • android sdk install platforms/android-34 build-tools/34.0.0 - ثبِّت أحدث إصدارات حزمة Android SDK Platform 34 وحزمة SDK Built Tools 34.0.0 من القناة الثابتة.
  • android sdk install platforms/android-34@2 - ثبِّت الإصدار 2 من حزمة Android SDK Platform 34.
  • android sdk install --canary system-images/android-35/google_apis/x86_6 - ثبِّت أحدث إصدار من صورة نظام Android 35 من قناة Canary.
  • android sdk install --force platforms/android-33@1 - يمكنك الرجوع إلى الإصدار 1 من حزمة Android SDK Platform 33 من القناة الثابتة.

sdk list

الاستخدام: android sdk list <package-pattern>

الوصف: تعرض هذه السمة حِزم SDK المثبَّتة والمتوفّرة.

الوسيطات (إلزامية):

  • <package-pattern>: لفلترة الحِزم حسب النمط يتوافق مع التعبيرات العادية.

الخيارات:

  • --all: لعرض جميع الحِزم المثبَّتة والمتاحة
  • --all-versions: لعرض جميع الإصدارات لكل حزمة
  • --beta: لتضمين حِزم الإصدار التجريبي
  • ‫--canary: لتضمين حِزم Canary

sdk remove

الاستخدام: android sdk remove <package-name>

الوصف: إزالة حزمة من حزمة تطوير البرامج (SDK)

الوسيطات (إلزامية):

  • استبدِل <package-name> باسم الحزمة المطلوب إزالتها.

مثال: android sdk remove build-tools/36.1.0

run

الاستخدام: android run [--debug] [--activity=<activity-name>] [--device=<serial-number>] [--type=<param>] --apks=<apk-paths>

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

الوسيطات (إلزامية):

  • --apks - قائمة قيم مفصولة بفاصلة تتضمّن مسارات ملفات APK التي تريد تثبيتها. المسار نسبي إلى المكان الذي تتواجد فيه حاليًا في نظام الملفات.

الخيارات:

  • --activity: اسم النشاط الذي سيتم تشغيله بعد تثبيت حزمة APK. إذا كانت هناك أنشطة متعددة، يجب تحديد أحد الأنشطة لتشغيله في البداية.
  • --debug - ينشر التطبيق في وضع تصحيح الأخطاء. بعد تشغيل التطبيق في وضع تصحيح الأخطاء، عليك ربط أداة تصحيح الأخطاء من بيئة تطوير متكاملة (IDE)، مثل استوديو Android، أو أداة سطر أوامر لبدء تصحيح الأخطاء.
  • --device - الرقم التسلسلي لجهاز الاختبار أو المحاكي. لا تكون هذه الخطوة مطلوبة إلا إذا كانت أجهزة متعددة متصلة. للعثور على الأرقام التسلسلية للأجهزة، شغِّل الأمر adb devices.
  • --type: نوع المكوّن الذي سيتم بدء تشغيله. استخدِم هذا الخيار إذا أردت بدء خدمة تُشغَّل في الخلفية مباشرةً بدلاً من نشاط واجهة مستخدم. الأنواع المتوافقة:
    • ACTIVITY
    • WATCH_FACE
    • TILE
    • COMPLICATION
    • DECLARATIVE_WATCH_FACE

أمثلة:

  • ‫android run --apks=app/build/outputs/apk/debug/app-debug.apk: يتم نشر حِزمة APK واحدة على الجهاز التلقائي.
  • ‫android run --apks=base.apk,density-hdpi.apk,lang-en.apk: تنشر حِزم APK متعددة على الجهاز التلقائي.
  • android run --apks=app-debug.apk --type=SERVICE --activity=.sync.DataSyncService: لاختبار خدمة بدون نشاط
  • ‫android run --apks=app-debug.apk --device=emulator-5554: تنشر حزمة APK على جهاز معيّن.

sdk update

الاستخدام: android sdk update [--beta] [--canary] [<package-name>]

الوصف: يمكنك تعديل حزمة واحدة أو جميع الحِزم إلى أحدث إصدار في القناة (القناة الثابتة تلقائيًا). إذا لم تحدّد حزمة، سيتم تعديل جميع الحِزم.

الخيارات:

  • ‫<package-name>: اسم الحزمة المطلوب تعديلها.
  • --beta: لتضمين حِزم الإصدار التجريبي
  • ‫--canary: لتضمين حِزم Canary
  • ‫--force: لفرض الرجوع إلى إصدار أقدم

أمثلة:

  • ‫android sdk update: للبحث عن التحديثات وتثبيتها لكل ما هو موجود في حزمة SDK
  • android sdk update build-tools/34.0.0 - يجب تحديث حزمة "أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android" إلى الإصدار 34.0.0 أو إصدار أحدث في القناة الثابتة.
  • android sdk update --canary platforms/android-35 - تحديث حزمة "منصات Android SDK‏ 35" إلى أحدث إصدار في قناة Canary

update

الاستخدام: android update

الوصف: تحديث Android CLI

-V, --version

الوصف: لعرض الإصدار الحالي من واجهة سطر الأوامر لنظام التشغيل Android