Name of the blog

Short description of the blog

fghfghgf6551fh05g101hgfh

ساخت یک رابط کاربری/UI ساده

این مبحث شما را با Xcode، محیط برنامه نویسی و ساخت اپلیکیشن برای سیستم عامل IOS، آشنا می سازد. در این مبحث همچنین با ساختار پروژه در Xcode آشنا شده و نحوه ی پیمایش بین کامپوننت ها و استفاده از آن ها را خواهید آموخت.

از ابتدا تا انتهای مبحث، یک رابط کاربری ساده (UI) برای اپلیکیشن FoodTracker طراحی کرده و سپس آن را در محیط شبیه ساز (Simulator) اجرا و مشاهده می کنید. در پایان برنامه ظاهری مشابه زیر خواهد داشت:

clip_image002

آنچه خواهید آموخت

· یک پروژه جدید در محیط کاری Xcode ایجاد نمایید.

· کاربرد فایل های اصلی که به همراه الگو یا قالب پروژه (project template) ایجاد می شوند را بدانید.

· فایل های پروژه را باز کرده و بین آن ها راه گزینی (switch) کنید.

· یک اپلیکیشن را در محیط شبیه ساز (simulator) اجرا نمایید.

· در سطح storyboard المان های UI جدید اضافه کرده، آن ها را جابجا و تغییر اندازه دهید.

· با استفاده از Attribute inspector، attribute های المان های UI را در storyboard ویرایش نمایید.

· المان های UI را با استفاده از outline view مشاهده و در صورت لزوم مجددا سازمان دهی نمایید.

· با استفاده از Preview assistant editor، پیش نمایشی از یک UI storyboard (پیش نمایشی از طرح کلی و ظاهر برنامه) داشته باشید.

· UI طراحی کنید که به وسیله ی امکان Auto Layout خود را با اندازه ی دستگاه میزبان (کاربر) تنظیم می کند.

ایجاد پروژه ی جدید

Xcode الگو یا template های درون ساخته ی متعددی دارد که ساخت و توسعه ی اپلیکیشن های متعارف IOS همچون بازی ها، برنامه هایی با قابلیت پیمایش با تب (tab-based navigation) و همچنین اپلیکیشن های با نمای جدولی (table-view-based) را آسان می سازد. بیشتر این template ها دارای interface و فایل های source code از پیش تنظیم شده هستند و شما می توانید از آن ها به صورت آماده استفاده کنید.

در آموزش حاضر کار را با ساده ترین نوع template آغاز می کنیم: Single View Application.

برای ایجاد پروژه ی جدید:

1. Xcode را از پوشه ی /Applications  باز کنید. پنجره ی زیر به نمایش در می آید.

clip_image004

ممکن است بجای پنجره ی فوق، پنجره ی پروژه نمایش داده شود. جای نگرانی نیست، احتمالا از قبل یک پروژه در محیط Xcode تعریف کرده یا فایل یک پروژه ی آماده را باز کرده اید. کافی است بر روی آیتم مربوطه در منو برای ایجاد پروژه ی جدید کلیک نمایید.

2. در پنجره ی آغازین (welcome window)، بر روی گزینه ی “Create a new Xcode project” کلیک کرده و یا این گام ها را دنبال نمایید: File > New > Project.

Xcode یک پنجره ی جدید باز کرده و پنجره ی محاوره ای را نمایش می دهد که می توان در آن template یا الگوی پروژه را انتخاب نمود.

3. در کادر کناری سمت چپ پنجره، گزینه ی Application را از بخش مربوط به IOS انتخاب نمایید.

4. داخل ناحیه ی اصلی پنجره ی محاوره ای، آیکون Single View Application را انتخاب کرده و سپس دکمه ی Next را کلیک نمایید.

image: ../Art/2_singleviewapp_template_2x.png

5. پنجره ی محاوره ای دیگر پدیدار می شود. مقادیر مشخص شده در زیر را وارد فیلدهای آن نموده و تنظیمات لازم را انجام دهید.

· Product Name: FoodTracker

همان طور که از اسم آن پیدا است، Xcode از این فیلد برای نام گذاری پروژه و اپلیکیشن شما بهره می گیرد.

· Organization Name: اسم شرکت تولید نرم افزار یا اسم خودتان را در این فیلد وارد نمایید. می توانید فیلد نام برده را خالی بگذارید.

· Organization Identifier: شناسه ی شرکت خود را وارد نمایید. در اینجا com.example را به عنوان مثال وارد می کنیم.

· Language: Swift

· Devices: Universal

اپلیکیشن Universal قابلیت اجرا بر روی iPhone و iPad را دارا می باشد.

· Bundle identifier: این مقدار به صورت خودکار بر اساس organization identifier و product name تولید می شود.

· Use Core Data: Unselected.

· Include Unit Tests: Selected

· Include UI Tests: Unselected.

image: ../Art/2_newproject_2x.png

6. بر روی دکمه ی Next کلیک کنید.

7. در پنجره ی محاوره ای که به نمایش در می آید، آدرس یا محل ذخیره فایل های پروژه ی خود را انتخاب کرده و بر روی Create کلیک نمایید. Xcode، پروژه ی جدید را داخل workspace window باز می کند (work space = پنجره ی داخل محیط کاری Xcode که امکان مدیریت فایل ها و منابع پروژه و پیمایش در آن ها را برای شما فراهم می کند).

image: ../Art/2_workspacewindow_2x.png

در پنجره ی Workspace، ممکن است پیغام هشدار “No code signing identities found.” را مشاهده نمایید. پیغام ذکر شده بیانگر این است که محیط Xcode را برای توسعه اپلیکیشن و برنامه نویسی IOS تنظیم نکرده اید. اما جای هیچ نگرانی نیست، شما می توانید بدون انجام این تنظیمات، پروژه را کامل کنید.

آشنایی بیشتر با محیط کاری Xcode

هر آنچه برای ساخت یک اپلیکیشن کارامد به آن نیاز دارید را در محیط Xcode خواهید یافت. این محیط نه تنها فایل های تشکیل دهنده ی پروژه ی را سازمان دهی می کند، ابزارهایی جهت ویرایش کد و المان های UI فراهم نموده و به شما امکان می دهد اپلیکیشن خود را کامپایل و اجرا نمایید. جهت خطایابی و اشکال زدایی، Xcode یک debugger درون ساخته در اختیار شما قرار می دهد که با استفاده از آن می توانید خط به خط برنامه را بررسی و debug کنید.

توصیه می کنیم زمانی را به آشنایی با بخش های مختلف پنجره ی Xcode تخصیص دهید. چرا که بخش های نام گذاری شده در پنجره ی زیر را در سرتاسر پروژه های این سری آموزشی بکار خواهید برد. در نگاه اول ممکن است کمی گیج کننده به نظر برسد، اما لازم نیست نگران باشید. به هنگام استفاده، هر بخش با جزئیات بیشتری شرح داده خواهد شد.

image: ../Art/2_workspacewindow_callouts_2x.png

راه اندازی محیط شبیه ساز (Simulator)

از آنجایی که پروژه ی خود را با استفاده از یک template در Xcode ایجاد کردید (پروژه ی خود را بر مبنای template آماده پی ریزی کرده اید)، محیط اولیه ی اپلیکیشن به صورت خودکار برای شما تنظیم می شود. با اینکه هیچ کدی برای برنامه خود ننوشته اید، می توانید قالب آماده ی Single View Application را بدون هیچگونه تنظیمات اضافی کامپایل (build) و اجرا نمایید.

جهت کامپایل و اجرای اپلیکیشن، می توانید از اپلیکیشن Simulator (یا برنامه ی شبیه ساز IOS) که همراه با محیط Xcode ارائه می شود، استفاده نمایید. Simulator به شما امکان می دهد اپلیکیشن خود را (در محیط شبیه ساز) اجرا کرده و پیش نمایشی از عملکرد و قابلیت های آن در یک دستگاه واقعی IOS را مشاهده نمایید.

Simulator قادر است سخت افزار دستگاه های iPad و iPhone (با صفحه نمایش بزرگ و کوچک) را شبیه سازی کند. این امر به شما امکان می دهد برنا��ه ی کاربردی خود را بر روی دستگاهی که می خواهید اپلیکیشن بر روی آن اجرا شود (اپلیکیشن را ویژه ی آن طراحی و تولید می کنید)، تست کرده و از عملکرد صحیح آن در دستگاه میزبان اطمینان حاصل نمایید. برای این پروژه simulator را بر روی گزینه ی iPhone 6 تنظیم نمایید.

جهت اجرای برنامه در محیط شبیه ساز:

1. به نوار ابزار Xcode مراجعه نموده، و از منوی pop-up (که Scheme نام دارد) گزینه ی iPhone 6 را انتخاب نمایید. این منوی pop-up به شما اجازه می دهد تا شبیه ساز یا دستگاهی که اپلیکیشن بر روی آن اجرا می شود را انتخاب نمایید.

به خاطر داشته باشید که محیط میزبان برنامه را حتما بر روی گزینه ی iPhone 6 Simulator تنظیم نمایید، نه IOS Device.

image: ../Art/2_schememenu_2x.png

2. جهت اجرا، بر روی دکمه ی Run در نوار ابزار محیط Xcode (واقع در بالای محیط سمت چپ) کلیک نمایید.

image: ../Art/2_toolbar_2x.png

برای اجرای پروژه همچنین می توانید به دو روش رو به رو اقدام نمایید: 1. Product > Run 2. کلید Command-R را فشار دهید.

زمانی که برای اولین بار اپلیکیشینی را بر روی محیط Mac اجرا می کنید، Mac از شما می پرسد آیا مایلید developer mode را فعال نمایید یا خیر. این حالت به Xcode اجازه می دهد به برخی امکانات ویژه ی عیب یابی و debugging دسترسی داشته باشد، بدون اینکه برای هر بار دسترسی شما مجبور شوید گذرواژه ی لازم را وارد نمایید (برای دسترسی به برخی قابلیت های debugging و فایل های playground شما ملزوم به ارائه ی گذرواژه ی خود هستید. با فعال کردن این مد دیگر برای دسترسی به امکانات نام برده نیازی به ارائه ی پسورد نیست). پس از تصمیم گیری در خصوص فعال کردن/نکردن developer mode، بر روی دکمه ی مربوطه کلیک نمایید.

image: ../Art/2_developermode_2x.png

برای پروژه های این سری آموزشی، developer mode را فعال نمایید.

4. همین که فرایند build تکمیل می شود، به نوار ابزار Xcode دقت کنید. Xcode اطلاعاتی را در خصوص فرایند build، داخل activity viewer نمایش می دهد. activity viewer در وسط نوار ابزار محیط Xcode قرار دارد.

پس از اینکه Xcode پروژه ی شما را با موفقیت کامپایل کرد، شبیه ساز به صورت خودکار راه اندازی می شود. راه اندازی برای اولین بار ممکن است کمی زمان ببرد.

شبیه ساز/simulator در حالت iPhone mode اجرا شده، سپس اپلیکیشن شما در صفحه نمایش شبیه ساز اجرا و به نمایش گذاشته می شود. اما قبل از اینکه شبیه ساز اپلیکیشن را به طور کامل راه اندازی (launch) کند، launch screen برنامه به همراه اسم آن (FoodTracker) به مدت چند ثانیه نشان داده شده و سپس خود اپلیکیشن اجرا می شود.

image: ../Art/2_sim_launchscreen_2x.png

سپس صفحه ی زیر به نمایش در می آید:

image: ../Art/2_sim_blank_2x.png

در حال حاضر، قالب Single View Application کار خاصی انجام نمی دهد – همان طور که می بینید صرفا یک صفحه ی سفید را برای کاربر به نمایش می گذارد. سایر Template هایی که Xcode در اختیار شما قرار می دهد، از قابلیت ها و رفتارهای بسیار پیچیده تری برخوردار هستند.

لازم است قبل از انتخاب یک template و توسعه ی آن برای ساخت اپلیکیشن خود، از موارد استفاده و قابلیت های آن کاملا مطلع باشید. اجرای برنامه در محیط شبیه ساز، بدون ایجاد تغییرات در آن روشی خوبی برای فهم این مسئله هست.

از محیط شبیه ساز خارج شوید (Simulator > Quit Simulator یا کلید Command-Q را فشار دهید).

مشاهده و بررسی Source code پروژه

به هنگام انتخاب قالب Single View Application، تعدادی فایل source code همراه آن ارائه می شود که این فایل ها وظیفه ی تنظیم محیط اپلیکیشن را بر عهده دارند. ابتدا فایل AppDelegate.swift  را مورد بررسی قرار می دهیم.

برای مشاهده ی محتویات فایل AppDelegate.swift:

1. ابتدا project navigator را در navigator area باز کنید. project navigator تمامی فایل های پروژه را نمایش می دهد. اگر project navigator باز نبود، می توانید آن را با کلیک بر روی دکمه ی سمت چپ در نوار navigator selector، باز نمایید (یا می توانید این مسیر را طی نمایید: View > Navigators > Show Project Navigator).

image: ../Art/2_projectnavigator_2x.png

2. در صورت لزوم، پوشه ی FoodTracker را (در کادر project navigator) با کلیک بر روی آیکون مثلث کوچک در کنار آن، باز نمایید.

3. فایل AppDelegate.swift را انتخاب نمایید. Xcode فایل نام برده را داخل editor area (ناحیه ی ویرایش) پنجره ی محیط باز کرده و محتویات/کدهای آن را به نمایش می گذارد.

image: ../Art/2_appdelegate_file_2x.png

و یا جهت مشاهده ی محتویات فایل در پنجره ی مجزا، دوبار بر روی فایل AppDelegate.swift کلیک نمایید.

فایل App Delegate

فایل AppDelegate.swift دو کاربرد اصلی دارد:

· علاوه برentry point یا نقطه ی شروع اجرای برنامه، یک run loop تعریف می کند که وظیفه ی تحویل رخدادهای ورودی به برنامه را دارد (run loop یک حلقه ی پردازش event است که برای زمان بندی کارها و هماهنگ سازی دریافت رخدادهای ورودی به برنامه، مورد استفاده قرار می گیرد. به عبارت دیگر هدف از run loop، فعال نگه داشتن thread به هنگام نیاز/زمانی که عملیاتی و کارهایی باید پردازش و انجام شوند و در حالت sleep قرار دادن آن در زمان بی کاری است). این کار توسط attribute ای به نام @UIApplicationMain، درج شده در بالای فایل مزبور، انجام می شود.

UIApplicationMain در واقع یک application object ( مسئول مدیریت life cycle برنامه از زمان اجرا تا پایان) و یک آبجکت app delegate تعریف می کند. در زیر به شرح مفهوم app delegate خواهیم پرداخت.

· این فایل همچنین کلاس AppleDelegate را تعریف می کند. کلاس مذکور الگو یا نقشه ای برای (ساخت) آبجکت app delegate می باشد. app delegate نیز پنجره ای را می سازد که محتوای اپلیکیشن شما در آن به تصویر کشیده شده و بستری را تعریف می کند که در آن می توان به تغییرات در وضعیت برنامه واکنش نشان داد. کدهای اختصاصی در سطح اپلیکیشن (custom app-level code­­­­­­­) داخل کلاس AppDelegate تعریف می شوند.

کلاس AppleDelegate یک property بیشتر ندارد و آن window است. app delegate به کمک این property پنجره ای که محتوای برنامه در آن نمایش داده می شود را رصد می کند. window از نوع optional است بدین معنی که می تواند در برهه ای از زمان هیچ مقداری نداشته و به اصطلاح nil باشد.

var window: UIWindow?

کلاس AppleDelegate همچنین الگویی آماده برای پیاده سازی متدهای پرکاربرد و مهم ارائه می دهد. این متدهای از پیش تعریف شده به application object امکان می دهند تا با app delegate تعامل داشته و ارتباط برقرار کند.

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool

func applicationWillResignActive(application: UIApplication)

func applicationDidEnterBackground(application: UIApplication)

func applicationWillEnterForeground(application: UIApplication)

func applicationDidBecomeActive(application: UIApplication)

func applicationWillTerminate(application: UIApplication)

در طول تغییر برنامه از یک وضعیت به وضعیت دیگر (state transition) – برای مثال، اجرا و شروع برنامه، تغییر وضعیت به پس زمینه و اتمام آن – application object متد متناظر در app delegate را صدا زده و به آن امکان می دهد پاسخ یا واکنش مناسب را نشان دهد.

لازم نیست زمان فراخوانی این متدها را خود مدیریت کرده و از اجرای به موقع آن ها اطمینان حاصل کنید. application object این وظیفه را بر عهده می گیرد.

هر یک از این متدها (که به صورت خودکار پیاده سازی می شوند) رفتار پیش فرضی داشته و عملیات خاصی را انجام می دهند. اگر پیاده سازی های الگو (template implementation) را خالی گذاشته یا آن را کلا از کلاس AppDelegate حذف کنید، در آن صورت هرگاه که متد صدا خورده می شود، دقیقا همان رفتار پیش فرض را از خود نشان خواهد داد. می توانید به این method template ها (الگو پیاده سازی یا قالب آماده ی متدها) کد اختصاصی خود را اضافه کنید تا با فراخوانی آن متد، رفتار دلخواه را به اجرا بگذارند.

در این مبحث هیچ کد اختصاصی به فایل AppDelegate.swift اضافه نخواهیم کرد.

فایل View Controller

با انتخاب قالب Single View Application، یک فایل دیگر به نام ViewController.swift ایجاد می شود. برای مشاهده ی محتوای این فایل بر روی ViewController.swift  در کادر project navigator کلیک نمایید.

image: ../Art/2_viewcontroller_file_2x.png

این فایل یک کلاس فرزند/subclass از UIViewController به نام ViewController ایجاد می کند. در حال حاضر، این کلاس صرفا رفتارهای (تعریف شده توسط) کلاس UIViewController را به ارث می برد. جهت بازنویسی (override) یا بسط این رفتارها، لازم است متدهای تعریف شده در UIViewController را override نمایید (همان طور که دو متد viewDidLoad() و didReceiveMemoryWarning() در فایل ViewController.swift  بازنویسی شده اند) و یا متدهای اختصاصی خود را پیاده سازی کنید.

در این فایل متدی به نامdidReceiveMemoryWarning()  نیز پیاده سازی شده که در حال حاضر با آن کاری نداریم. می توانید این متد را از کلاس ViewController حذف کنید.

پس از حذف متد ذکر شده، کد فایل ViewController.swift مشابه زیر خواهد بود:

import UIKit

class ViewController: UIViewController {

override func viewDidLoad() {

super.viewDidLoad()

// Do any additional setup after loading the view, typically from a nib.

}

}

در ادامه ی مبحث حاضر کدهایی را به این فایل اضافه خواهیم کرد.

مشاهده ی محتوای فایل Storyboard

در این بخش با فایل storyboard اپلیکیشن خود کار خواهیم کرد.

Storyboard در واقع فایلی است که نمودی (ظاهری) از (کدهای پشت) رابط کاربری اپلیکیشن را ارائه می دهد. به عبارتی روشن تر کدهای نوشته شده در فایل، به صورت مستقیم اجرا شده و می توان در هر لحظه خروجی کدها را مشاهده نمود.

در واقع با استفاده از storyboard جریان برنامه را به تصویر می کشید، آنچه برای برنامه طراحی می کنید را در حین طراحی و در لحظه مشاهده نموده، می توانید بخش هایی که درست کار می کند و بخش هایی که از عملکرد صحیح برخوردار نیستند را به چشم خود ببینید، تغییرات لازم را بر روی UI اعمال نمایید و مستقیما نتیجه ی آن را مشاهده کنید.

برای مشاهده ی فایل storyboard:

· در کادر project navigator، بر روی فایل Main.storyboard کلیک نمایید. Xcode این فایل را داخل Interface Builder، در ناحیه ی ویرایشگر (editor area) محیط باز می کند.

به پس زمینه ی storyboard در اصطلاح Canvas گفته می شود. می توانید Canvas را برای افزودن و مدیریت چیدمان المان های UI بکار ببرید.

Storyboard می بایست ظاهری مشابه زیر داشته باشد:

image: ../Art/2_storyboard_empty_2x.png

در این مرحله، storyboard تنها یک scene دارد. به یک صفحه از برنامه که حامل محتوا است در اصطلاح scene گفته می شود. پیکانی که به ضلع سمت چپ صفحه ی محتوا یا scene (بر روی canvas) اشاره می کند، نقطه ی شروع storyboard می باشد. بدین معنی که این scene اولین صفحه ای است که به مجرد اجرای اپلیکیشن بارگذاری می شود (اولین صفحه ی محتوای برنامه که جریان و چرخه ی اپلیکیشن از آنجا شروع می شود).

در حال حاضر، scene جاری (که بر روی canvas یا پس زمینه ی storyboard مشاهده می کنید) دربردارنده ی یک view بیشتر نیست. مدیریت این View یا هر Viewدیگری بر عهده ی view controller است. به زودی درباره ی مفهوم view،view controller و وظیفه ی هر یک توضیحاتی را ارائه خواهیم داد.

زمانی که اپلیکیشن خود را بر روی محیط شبیه ساز iPhone 6 در Xcode راه اندازی کردید، آنچه با اجرای برنامه برای شما به نمایش گذاشته شد، در واقع همین view یا محتوایی است که هم اکنون در این scene مشاهده می کنید. اما یک نکته ی جالب توجه: با دقت به scene مورد نظر، متوجه می شوید که ابعاد آن با اندازه ی صفحه نمایش iPhone 6 دقیق همخوانی ندارد. به نظر شما علتش چیست؟ در پاسخ باید گفت که scene قابل مشاهده بر روی پس زمینه یا canvas، یک نمای کلی از رابط کاربری است که برای هر دستگاهی و با هر جهت نمایشی (نمای افقی/عمودی)، قابل استفاده می باشد.

از این نمای کلی برای ایجاد یک adaptive interface یا رابط کاربری سازگار با (اندازه و جهت نمایش) صفحه نمایش دستگاه میزبان استفاده می شود. به عبارت دیگر adaptive interface، همان طور که از نامش پیدا است، یک رابط کاربری انعطاف پذیر است که خود را به صورت اتوماتیک، جهت نمایش دقیق المان های UI، متناسب با صفحه نمایش دستگاه میزبان تنظیم می کند.

ساخت یک رابط کاربری/UI ساده

اکنون به ساخت یک رابط کاربری ساده می پردازیم. ابتدا UI را برای scene (صفحه ی محتوایی) طراحی می کنیم که به ما اجازه می دهد یک آیتم جدید به برنامه ی ثبت و رصد اطلاعات غذا (meal tracking app) ،که آن را FoodTracker نام گذاری کردیم، اضافه نماییم.

Xcode کتابخانه ای از اشیای آماده (object library) دارد که می توانید آن ها را به فایل storyboard اضافه نمایید. برخی از این اشیا، المان های قابل مشاهده هستند که در UI به نمایش درمی آیند. از جمله ی آن های می توان به button و text field اشاره کرد. برخی دیگر مانند view controller ها و gesture recongnizer ها، صرفا رفتار اپلیکیشن را تعریف می کنند و بر روی صفحه نمایش قابل مشاهده نیستند.

المان هایی که در UI برای کاربر قابل مشاهده هستند در اصطلاح view خوانده می شوند. View ها در واقع محتوای اپلیکیشن را برای کاربر به نمایش می گذارند. می توان آن ها را ابزار اصلی و مصالح تشکیل دهنده ی رابط کاربری تلقی کرد که توسط آن محتوا را به صورت کارامد و زیبا در صفحه نمایش به تصویر می کشیم.

View ها طیفی وسیعی از رفتارهای ذاتی و درون ساخته دارند که از جمله ی آن ها می توان از نمایاندن خود بر روی صفحه نمایش و واکنش نشان دادن به ورودی کاربر نام برد.

تمامی view object ها در IOS از جنس UIView یا یکی از کلاس های فرزند (subclass) آن هستند. بسیاری از کلاس هایی که از UIView ارث بری می کنند (subclass های آن محسوب می شوند)، در ظاهر و رفتار منحصر بفرد هستند.

برای شروع یک کادر متن/text field (کلاس UITextField که یکی از کلاس های زیرمجموعه ی UIView است) به scene اضافه می کنیم. همان طور که می دانید، text field یک کادر متن است که به کاربر اجازه می دهد، اسم آیتم جدید (در این برنامه نام غذا) را وارد کند.

برای اضافه کردن یک text field به scene:

1. Object Library را باز نمایید.

Object library در پایین utility area، سمت راست محیط کاری Xcode قابل دسترسی می باشد. اگر Object library قابل مشاهده نبود، می توانید با کلیک بر روی دکمه سوم از سمت چپ در library selector bar، آن را باز کنید (یا می توانید به این روش اقدام نمایید: View > Utilities > Show Object Library).

image: ../Art/object_library_2x.png

یک لیست پدیدار می شود که اسم هر آبجکت را به همراه شرحی درباره ی کاربرد و نمای ظاهری آن نمایش می دهد.

2. در Object library، اسم آبجکت دلخواه (text field) را داخل کادر جستجو (filter field) وارد نمایید. بدین وسیله شی مورد نظر به سرعت در اختیار شما قرار می گیرد.

3. آبجکت Text Field را از Object Library کشیده و بر روی سطح scene جایگذاری کنید.

image: ../Art/2_textfield_drag_2x.png

در صورت لزوم، با طی این مراحل Editor > Canvas > Zoom، زمینه را بزرگ نمایید.

4. بر روی Text field کلیک کرده و آن را در جهت نیمه ی بالایی scene، هم تراز با حاشیه ی سمت چپ بکشید. هنگامی که خط نقطه چین آبی رنگ مانند زیر نمایان شد، کشیدن را متوقف کرده و آبجکت مزبور را رها کنید.

image: ../Art/2_textfield_place_2x.png

راهنمای آبی رنگ به شما کمک می کند آبجکت text field را در جایگاه مناسب آن قرار دهید. در حقیقت این راهنما تنها زمانی پدیدار می شود که آبجکت ها را در نزدیکی آن ها جابجا کرده یا تغییر اندازه دهید. هرگاه آبجکت را رها کنید، راهنمای آبی رنگ نیز محو می شود.

5. جهت تنظیم اندازه ی المان UI مورد نظر، کافی است resize handle آن المان را بکشید. Resize handle یا دستگیره های تنظیم اندازه، مربع های کوچک سفید رنگی هستند که با کلیک بر روی المان مورد نظر، بر روی لبه های آن المان نمایان می شوند.

همان طور که گفته شده برای نمایان شدن resize handle، باید المان را با کلیک بر روی آن انتخاب نمایید. از آنجایی که text field را تازه رها کردیم، المان انتخاب شده و resize handle های آن هنوز قابل مشاهده می باشند.

image: ../Art/2_textfield_resizehandles_2x.png

6. لبه های سمت چپ و راست المان را در جهات مربوطه کشیده تا سه خط عمودی آبی رنگ به صورت زیر نمایان شود.

image: ../Art/2_textfield_finalsize_2x.png

Text field در scene جایگذاری شده، اما هیچ سرنخی که کاربر را در خصوص ورودی مورد انتظار راهنمایی کند، لحاظ نشده است. حال بایستی با استفاده از فیلد placeholder، ویژه ی آبجکت text field، به کاربر اعلان کنیم که در کادر متن اسم یک غذا را درج کند.

جهت تنظیم مقدار فیلد placeholder مربوط به این آبجکت:

1. پس از انتخاب text field، به utility area داخل محیط کاری Xcode مراجعه کرده و Attributes inspector را (در inspector selector bar) با کلیک بر روی دکمه ی سوم از سمت راست، باز نمایید. Attributes inspector به شما امکان می دهد مقدار property های یک آبجکت را در storyboard ویرایش نمایید.

image: ../Art/2_inspector_attributes_2x.png

2. داخل کادر Attributes inspector، فیلدی که Placeholder نام دارد را یافته و مقدار Enter meal name را در آن وارد نمایید.

3. کلید Return را فشار داده تا متن مورد نظر داخل آبجکت text field نمایش داده شود.

پس از اعمال تغییرات نام برده، scene ظاهری مشابه نمونه ی زیر خواهد داشت:

image: ../Art/2_textfield_withplaceholder_2x.png

همزمان با ویرایش attribute های آبجکت text field، همچنین می توانید attribute های صفحه کلیدی که با انتخاب آبجکت ذکر شده نمایان می شود را تغییر دهید.

جهت تنظیم صفحه کلید:

1. Text field را انتخاب نمایید.

2. داخل کادر Attributes inspector، فیلدی که Return Key نام دارد را یافته و مقدار آن را بر روی Done تنظیم کنید. با این کار مقدار پیش فرض Return در صفحه کلید به Done تغییر کرده و بیشتر مورد توجه کاربر قرار می گیرد.

3. حال در کادر Attributes inspector، گزینه ی Auto-enable Return Key را تیک دار نمایید. با فعال نمودن این گزینه، کاربر دیگر قادر نخواهد بود بدون وارد کردن متن در text field (اسم غذا) کلید Done را فشار دهد.

اکنون یک label (از کلاس UILabel) جهت ارائه ی اطلاعات درباره ی کادر متن (آبجکت text field) به بالای آن اضافه می کنیم. همان طور که می دانید label یک المان هوشمند و تعاملی نیست بلکه صرفا یک متن ساده را برای کاربر نمایش می دهد. برای اینکه شما بتوانید نحوه ی تعریف تعامل بین المان های مختلف UI را بهتر درک کنید، این label را طوری تنظیم می کنیم که ورودی کاربر در کادر متن را نمایش دهد. با این کار می توان اطمینان حاصل نمود که المان مورد نظر ورودی کاربر را به درستی دریافت و پردازش می کند.

جهت افزودن یک label به scene:

1. به Object library مراجعه نموده، واژه ی label را در کادر جستجوی (filter field) آن وارد نمایید تا آبجکت Label به سرعت در اختیار شما قرار گیرد.

2. آبجکت Label را از Object library کشیده و بر روی سطح scene جایگذاری کنید.

3. آبجکت نام برده را به بالای کادر متن کشیده و آن را همتراز با حاشیه ی سمت چپ قرار دهید. هنگامی که خط نقطه چین افقی، مانند زیر نمایان می شود، المان را رها کنید.

image: ../Art/2_label_place_2x.png

4. بر روی label دوبار کلیک کرده و سپس واژه ی Meal Name را وارد نمایید.

5. کیلد Return را فشار داده تا متن جدید در label نمایش داده شود.

با اضافه شدن یک المان جدید به scene، ظاهر برنامه به این صورت در خواهد آمد:

image: ../Art/2_label_rename_2x.png

آخرین المانی که به رابط کاربری اضافه می کنیم، یک دکمه (از کلاس UIButton) است. دکمه برخلاف label، یک المان تعاملی می باشد. بدین معنی که با کلیک بر روی آن، فعل یا عملیات خاصی (که شما تعریف می کنید) انجام می شود. در همین مبحث رفتاری (action) برای دکمه تعریف می کنیم که با کلیک بر روی آن، متن label را به مقدار پیش فرض برمی گرداند.

به منظور افزودن المان دکمه به scene:

1. به Object library مراجعه نمایید و پس از یافتن آبجکت Button، آن را کشیده و در سطح scene جایگذاری کنید.

2. حال المان دکمه را کشیده و در زیر کادر متن قرار دهید. زمانی که دو خط نقطه چین آبی رنگ نمایان شد، المان را رها کنید.

image: ../Art/2_button_place_2x.png

3. بر روی دکمه دابل کلیک کرده و عبارت Set Default Label Text را وارد نمایید.

4. کلید Return را فشار دهید. متن جدید بر روی دکمه نمایش داده می شود.

ظاهر جدید برنامه:

image: ../Art/2_button_rename_2x.png

بد نیست پس از افزودن تمامی المان های لازم، چیدمان آن ها در scene را بررسی کنیم. برای این منظور از outline view کمک می گیریم.

جهت مشاهده ی outline view:

1. در Storyboard، دکمه ی toggle (نمایش دادن/پنهان کردن) outline view را پیدا کنید.

image: ../Art/2_outlineview_toggle_2x.png

2. در صورتی که outline view در حالت collapsed قرار داشته باشد (پنهان باشد)، بر روی دکمه ی toggle کلیک کرده تا کادر outline view باز شود. با این دکمه می توانید outline view را با توجه به نیاز باز کرده و یا آن را جمع کنید.

Outline view – کادری که در سمت چپ canvas نمایش داده می شود – به شما اجازه می دهد اشیای موجود در storyboard را با نمای درختی (به صورت سلسله مراتب) مشاهده نمایید. به عبارت بهتر در این کادر می توانید المان هایی که به رابط کاربری برنامه خود اضافه کردید را در سلسله مراتب مشاهده نمایید. با دیدن این سلسله مراتب در کادر مذکور، شاید این سوال پیش آید که چرا المان های UI در زیر گره ی View لیست شده اند (به عبارت دیگر داخل view دیگر گنجانده شده اند)؟

View ها علاوه بر نمایش محتوا و تعامل با کاربر، می توانند ظرفی برای نگهداری سایر view ها باشند. View ها در قالب یک سلسله مراتب نمایش داده می شوند که در اصطلاح view hierarchy خوانده می شود. view hierarchy چیدمان و ترتیب view ها را نسبت به دیگر view ها مشخص می کند. داخل این سلسله مراتب، view هایی که داخل view دیگری جای گرفته اند subview نامیده و view هایی که دربرگیرنده و میزبان view های دیگر هستند superview خوانده می شوند. یک view می تواند چندین subview داشته باشد، اما خود زیرمجموعه ی تنها یک superview باشد.

image: ../Art/2_outlineview_2x.png

به طور کلی هر scene یک view hierarchy دارد. در بالاترین مرتبه ی هر view hierarchy نیز یک content view مشاهده می شود. برای مثال در scene جاری، View ای که در بالاترین مرتبه قرار دارد، content view نامیده می شود و همان طور که می بینید خود داخل View Controller قرار دارد. text field، label، button و هر المان دیگری که داخل این scene قرار می دهید زیرمجموعه ی content view خواهد بود (هرچند این المان ها نیز می توانند view های دیگری به عنوان زیرمجموعه ی خود داشته باشند).

پیش مشاهده ی User Interface برنامه

اپلیکیشن خود را در فواصل زمانی معین بررسی کرده و مطمئن شوید همه چیز مورد انتظار و دلخواه شما می باشد. به عنوان مثال جهت پیش مشاهده ی رابط کاربری برنامه ی خود می توانید از ابزاری به نام assistant editor بهره بگیرید. این ابزار یک ویرایشگر کمکی در کنار ویرایشگر اصلی Xcode به نمایش در می آورد که در آن می توانید نمایی از برنامه ی خود را مشاهده نمایید.

جهت پیش مشاهده ی رابط کاربری برنامه ی خود:

1. بر روی دکمه ی اشاره شده در تصویر زیر کلیک نموده و ابزار assistant editor را باز کنید (این دکمه در نوار ابزار Xcode، بالای محیط گوشه سمت راست قابل مشاهده و دسترسی می باشد).

image: ../Art/assistant_editor_toggle_2x.png

2. اگر در محیط به فضای کاری بیشتری نیاز دارید، در آن صورت می توانید project navigator و utility area را با کلیک بر روی دکمه های مربوطه در نوار ابزار محیط (اشاره شده در تصویر زیر) کوچک نمایید.

image: ../Art/navigator_utilities_toggle_on_2x.png

در صورت نیاز می توانید outline view را نیز جمع نمایید.

3. در editor selector bar، مقیم در بالای assistant editor (اشاره شده در تصویر زیر)، با طی کردن مراحل زیر، assistant editor را از حالت Automatic بر روی Preview تنظیم نمایید: Preview > Main.storyboard (Preview) .

image: ../Art/2_assistant_editorselectorbar_2x.png

همان طور که در assistant editor مشاهده می کنید، طول المان text field از لبه ی صفحه ی جاری بیرون می زند. اما اگر به خاطر داشته باشید، رابط کاربری که در storyboard تعریف کردیم کاملا بی نقص نمایش داده می شود. پس چرا همین رابط کاربری در حالت preview یا پیش نمایش iPhone متوازن نیست و به طور صحیح مقیاس دهی نمی شود؟

image: ../Art/2_preview_2x.png

همان طور که قبلا ذکر شد، رابط کاربری که طراحی می کنیم، در واقع یک interface انعطاف پذیر و قابل تنظیم است که متناسب با اندازه ی دستگاه میزبان (صفحه نمایش دستگاه های iPhone و iPad) مقیاس بندی می شود. scene یا صفحه ی محتوایی که به صورت پیش فرض در storyboard می بینید عملا یک نما و نسخه ی کلی از UI برنامه ی شما را به نمایش می گذارد. اما در بستر assistant editor می بایست نحوه ی نمایش و مقیاس interface را برای دستگاه های مختلف (فضای موجود و اندازه ی صفحه نمایش مربوطه) درنظر گرفته و مشخص نمایید. برای مثال، زمانی که رابط کاربری بایستی خود را برای تطبیق با اندازه ی صفحه نمایش دستگاه iPhone کوچک کند، المان text field نیز باید همراه با آن کوچک شود و یا زمانی که می بایست جهت تطبیق با صفحه نمایش iPad بزرگ شود، المان مزبور باید متناسب با آن مقیاس بندی شود.

برای تعیین قوانین مقیاس دهی و تنظیم رابط کاربری متناسب با دستگاه، می توانید از موتور نمایش Auto Layout استفاده نمایید.

استفاده از موتور نمایش Auto Layout

Auto Layout یک layout engine یا موتور نمایش و رندرینگ قدرتمند است که به شما امکان می دهد به آسانی layout (قالب های) انعطاف پذیر و قابل تنظیم طراحی نمایید. بدین صورت است که شما خواسته یا ایده ی خود را در خصوص موقعیت دهی المان ها در یک scene توصیف می کنید و سپس به layout engine واگذار می کنید خود تصمیم بگیرد چگونه به بهترین نحو این ایده را پیاده سازی کند. تمایل خود در خصوص چیدمان المان ها را بایستی در قالب constraint ها بیان کنید – constraint ها قوانینی هستند که مشخص می کنند المان ها چگونه باید نسبت به دیگر المان ها موقعیت دهی شوند، چه اندازه ای داشته باشند و در صورت کاهش فضای موجود، کدام المان اول کوچک شود.

یکی دیگر از ابزار قدرتمندی که همراه با Auto Layout، در راستای مدیریت چیدمان و تنظیم اندازه ی المان متناسب با اندازه ی دستگاه (کار با layout) بکار می رود، stack view (کلاس UIStackView) می باشد. stack view یک رابط ساده و پربازده برای نمایش و چیدمان مجموعه ای از view ها در قالب ستون یا سطر ارائه می دهد. این ابزار به شما اجازه می دهد از قدرت Auto Layout بهترین استفاده را کرده و UI هایی طراحی کنید که به صورت پویا و در لحظه خود را با جهت (نمای افقی/عمودی)، اندازه ی صفحه نمایش و سایر تغییراتی که در فضای موجود ایجاد می شود، تطبیق دهد.

شما می توانید به آسانی رابط جاری را در یک stack view گنجانده، سپس با اعمال constraint های لازم اطمینان حاصل نمایید این stack view در دستگاه های مختلف به درستی نمایش داده می شود.

جهت افزودن constraint های مورد نیاز به scene جاری:

1. ابتدا می بایست با کلیک بر روی دکمه ی Standard، اشاره شده در تصویر زیر، Standard editor را باز نمایید.

image: ../Art/standard_toggle_2x.png

با کلیک بر روی دکمه های Navigator و Utilities در نوار ابزار محیط Xcode، کادر project navigator و utility area را باز نمایید.

2. کلید Shift را نگه داشته و سپس المان های text field، label و button را انتخاب نمایید.

image: ../Art/2_AL_shift_select_2x.png

3. در پایین canvas، سمت راست بر روی دکمه یStack کلیک نمایید (و یا این مسیر را طی کنید: Editor > Embed In > Stack View).

image: ../Art/2_AL_stackmenu_2x.png

پس از کلیک بر روی دکمه ی مزبور، Xcodeالمان های UI را به صورت پشته بر روی هم قرار داده یا به اصطلاح آن ها را در قالب یکstack view می گنجاند (wrap می کند). با بررسی و تحلیل layout یا طرح بندی جاری، Xcode تصمیم می گیرد که المان ها را باید به صورت عمودی بر روی هم انباشته و نمایش دهد (نه به صورت افقی).

image: ../Art/2_AL_stack_2x.png

4. در صورت لزوم، می توانید outline view را باز کرده، سپس آبجکت Stack View را انتخاب نمایید.

image: ../Art/2_AL_outlineview_2x.png

5. در Attribute inspector، داخل فیلد Spacing مقدار 12 را وارد نمایید. حال کلید Return را فشار دهید. خواهید دید که المان های UI به اندازه ی مقداری که در فیلد نام برده درج کردید، به صورت عمودی از هم فاصله داده شده و همزمان با آن stack view نیز بزرگتر می شود.

image: ../Art/2_AL_stackspaced_2x.png

6. در پایین canvas، سمت راست، با کلیک بر روی دکمه ی سوم (از سمت چپ) منوی Pin را باز نمایید.

image: ../Art/2_AL_pinmenu_2x.png

7. در بالای عبارت “Spacing to nearest neighbor” در تصویر زیر، با کلیک بر روی دو constraint افقی و همچنین constraint عمودی سمت بالا، آن ها را انتخاب نمایید. constraint های نام برده پس از انتخاب قرمز رنگ می شوند.

image: ../Art/2_AL_pinconstraints_2x.png

این Constraint ها در واقع نشانگر میزان فاصله المان جاری با المان های مجاور است. در اینجا منظور از اصطلاح nearest neighbor، لبه ی نزدیکترین المان UI به عنصر مورد نظر است که ممکن است superview، peer view یا صرفا یک margin (حاشیه ی پس زمینه یا canvas) باشد. از آنجایی که گزینه ی “Constrain to margins” انتخاب شده، stack view به حاشیه ی سمت چپ، راست و بالای المان superview چسبانده شده و فاصله ی اندکی از لبه ی سمت چپ صفحه را خالی می گذارد.

8. در کادرهای سمت چپ و راست مقدار 0 و در کادر سمت بالا مقدار 60 را وارد نمایید.

9. از منوی pop-up جنب عبارت Update Frames، گزینه ی Items of New Constraints را انتخاب نمایید. منوی Pin هم اکنون می بایست ظاهری مشابه زیر داشته باشد:

image: ../Art/2_AL_stackconstraints_2x.png

10. در منوی Pin، بر روی دکمه ی Add 3 Constraints کلیک نمایید.

image: ../Art/2_AL_add3constraints_2x.png

رابط کاربری برنامه هم اکنون باید چنین بنظر برسد:

image: ../Art/2_AL_stackfinal_2x.png

همان طور که می بینید که المان text field مانند قبل تا انتهای scene (لبه ی سمت راست) کشیده نمی شود. در زیر به تنظیم پهنای المان ذکر شده می پردازیم.

جهت تنظیم عرض المان text field در scene جاری:

1. (داخل storyboard) ابتدا المان مورد نظر را در scene فعلی انتخاب نمایید.

2. در پایین canvas، سمت راست، با کلیک بر روی دکمه ی سوم (از سمت چپ) منوی Pin را باز نمایید.

image: ../Art/AL_pinmenu_2x.png

3. در بالای عبارت “Spacing to nearest neighbor”، با کلیک بر روی دو constraint افقی، آن ها را انتخاب نمایید. همان طور که قبلا گفته شد، constraint ها پس از انتخاب به رنگ قرمز پر رنگ در می آیند.

4. داخل کادرهای سمت راست و چپ، مقدار 0 را وارد نمایید.

5. از منوی pop-up، جنب عبارت Update Frames، گزینه ی Items of New Constraints را انتخاب نمایید. در حال حاضر منوی Pin می بایست اینگونه به نظر برسد:

image: ../Art/2_AL_textfieldconstraints_2x.png

6. در منوی Pin، بر روی دکمه ی Add 2 Constraints کلیک نمایید.

image: ../Art/2_AL_add2constraints_2x.png

7. در حالی که text field را انتخاب کرده اید، بر روی آیکون در utility area کلیک نموده و Size inspector را باز نمایید. Size inspector به شما امکان می دهد، اندازه و مکان قرارگیری (position) آبجکت مورد نظر را در storyboard ویرایش و تنظیم نمایید.

image: ../Art/2_inspector_size_2x.png

8. از فیلد Intrinsic Size، گزینه ی Placeholder را انتخاب نمایید. (این فیلد در پایین Size inspector قرار گرفته، بنابراین جهت دسترسی به آن باید با نوار پیمایش به پایین کادر بروید.)

لازم به ذکر است که Text field بر اساس محتوای درونی خود اندازه بندی می شود. اندازه ی این المان بر اساس ویژگی intrinsic content size المان مشخص می شود (intrinsic content size به حداقل فضای لازم برای نمایش کامل و بی نقص تمامی محتویات view اشاره دارد).

در مواقعی که فکر می کنید اندازه ی المان UI ممکن است بزرگتر یا کوچکتر از مورد انتظار (در زمانی طراحی) باشد، می توانید فیلد intrinsic size آن را بر روی مقدار placeholder تنظیم نمایید. در حال حاضر، تنها محتوای text field، یک رشته ی مکان نگهدار (placeholder string) بوده که اندازه ی آن احتمالا از طول رشته ای که کاربر وارد می کند، کم تر است.

رابط کاربری برنامه در زمان حاضر می بایست مشابه زیر باشد:

image: ../Art/2_AL_textfieldfinal_2x.png

اکنون برنامه ی خود را در محیط شبیه ساز یا Simulator اجرا کنید. المان text field قاعدتا دیگر نباید از چارچوب صفحه ی جاری بیرون بزند. شما بایستی بتوانید داخل text field کلیک کرده و متن مورد نظر را با استفاده از صفحه کلیدوارد نمایید (در صورت تمایل می توانید صفحه کلید نرم افزار را با زدن Command-K به صورت toggle نمایش داده/پنهان نمایید). حال اگر دستگاه را بچرخانید (با فشردن کلیدهای Command-Left Arrow یا Command-Right Arrow) و یا برنامه را بر روی دستگاه دیگری اجرا کنید، خواهید دید که text field متناسب با جهت و اندازه ی صفحه نمایش دستگاه میزبان، کوچک/بزرگ می شود. لازم به ذکر است که در نمای افقی (landscape orientation) نوار وضعیت/status bar از نظر کاربر محو می شود.

image: ../Art/2_sim_finalUI_2x.png

چنانچه اپلیکیشن رفتار مورد انتظار را ارائه نداد (المان ها را آن طور که باید نمایش نداد)، می توانید از امکانات debugging موتور Auto Layout جهت خطایابی و اشکال زدایی بهره بگیرید. برای این منظور بر روی آیکون Resolve Auto Layout Issues کلیک نموده، سپس گزینه ی Reset to Suggested Constraints را انتخاب نمایید تا Xcode رابط کاربری برنامه ی شما را بروز آوری کرده و constraint های مناسب را اعمال کند.

یا پس از کلیک بر روی آیکون Resolve Auto Layout Issues، گزینه ی Clear Constraints را انتخاب نمایید تا تمامی constraint های اعمال شده بر روی المان های UI حذف گشته و سپس تمامی مراحل فوق را مجددا دنبال نمایید.

image: ../Art/2_AL_resolvemenu_2x.png

scene جاری به جز نمایش تعداد محدودی المان UI، کار به خصوصی انجام نمی دهد. با این حال نمایی از یک رابط کاربری ساده و کاربردی ارائه می دهد که می تواند شما را در طراحی UI برنامه ی خود راهنمایی کند.

ساخت یک layout (قالب و نمای کلی) کارامد و قابل تنظیم (که متناسب با عرض صفحه ی دستگاه میزبان و جهت نمایش، بزرگ/کوچک می شود) می تواند پایه ی قوی برای برنامه باشد. شما می توانید بر اساس این پایه ی قوی نسبت به ساخت دیگر بخش های برنامه اقدام نمایید.

ewew

اضافه کردن models و controller

در این قسمت، ما کلاس های model را برای مشخص کردن ماهیت دیتابیس تعریف می کنیم. سپس شما می توانید Controller های Web API که عملیات CRUD روی آن موجودیت ها را انجام می دهد اضافه کنید.

اضافه کردن کلاس های Model

در این مقاله ما با استفاده از Code First و EntityFramework دیتابیس خود را می سازیم. با Code First شما می توانید کلاس های C# را که با جداول دیتابیس مطابقت دارند با EF بسازید.

ما کار خود را با تعریف object ها به عنوان POCO شروع می کنیم. در ادامه POCO های زیر را خواهیم ساخت:

·         نویسنده

·         کتاب

در solution explorer روی فولدر models کلیک راست کنید و Add را انتخاب کنید و سپس Class را بزنید و نام آن را Author بگذارید.

clip_image002

قطعه کد زیر را با کدهای درون Author.cs جایگزین کنید.

using System.Collections.Generic;

using System.ComponentModel.DataAnnotations;

namespace BookService.Models

{

    public class Author

    {

        public int Id { get; set; }

        [Required]

        public string Name { get; set; }

    }

}

کلاس دیگری با نام Book بسازید و به صورت زیر کد نویسی کنید.

using System.ComponentModel.DataAnnotations;

namespace BookService.Models

{

    public class Book

    {

        public int Id { get; set; }

        [Required]

        public string Title { get; set; }

        public int Year { get; set; }

        public decimal Price { get; set; }

        public string Genre { get; set; }

        // Foreign Key

        public int AuthorId { get; set; }

        // Navigation property

        public Author Author { get; set; }

    }

}

Entityframework از این مدل ها برای ساخت جداول دیتابیس استفاده می کند. برای هر مدل،خاصیت Id در نقش کلید اصلی جدول دیتابیس می باشد.

در کلاس book، AuthorId یک کلید خارجی در جدول Author تعریف می کند.(برای سادگی، فرض می کنیم هر book تنها یک author دارد.) همچنین کلاس book شامل خاصیت جهت یابی (navigation)برای Author مربوط می باشد. شما می توانید از خاصیت  navigationبرای دسترسی به Author مربوط استفاده کنید.

اضافه کردن Comtroller های Web API

در این قسمت، ما Controller هایی اضافه می کنیم که عملیات CRUD(ساختن،خواندن،به روز رسانی و حذف کردن) را پشتیبانی کنند. Controller از Entity Framework برای ارتباط با لایه دیتابیس استفاده می کنیم.

ابتدا، شما می توانید فایل Controllers/ValuesController.cs را حذف کنید. در این فایل یک مثال از Controller Web API موجود است که در این مقاله به آن نیاز نداریم.

clip_image003

در مرحله بعد، پروژه را Build کنید. روش Scaffold کردن Web API از reflection برای پیدا کردن کلاس های model استفاده می کند و برای همین به کامپایل نیاز دارد.

در solution explorer روی فولدر Models  کلیک راست کنید و ابتداAdd  و سپس Controller را انتخاب کنید.

clip_image005

در پنجره Add Scaffold، Web API 2 Controller with actions, using Entity Framework را انتخاب کرده و Ok کنید.

clip_image007

در پنجره Add Controller مراحل زیر را انجام دهید:

1- در لیست Model Class، کلاس Author را انتخاب کنید(اگر این کلاس را پیدا نکردید، دوباره به برنامه خود بازگردید و دوباره Build کنید.)

2- گزینه Use async controller actions را انتخاب کنید.

3- نام Controller را AuthorsController انتخاب کنید.

4- دکمه (+) را برای Data Context Class بزنید.

clip_image009

در پنجره New Data Context ، نام پیش فرض را قرار داده و روی Add کلیک کنید.

clip_image010

برای تکمیل فرآیند پنجره Add Controller، Add را کلیک کنید. این پنجره دو کلاس به پروژه شما اضافه می کند:

·         AuthorsController  یک Controller Web API تعریف می کند. Controller REST API لیست author برای اجرای عملیات CRUD کاربران پیاده سازی می کند.

·         BookServiceContext  موجودیت  object ها را در زمان اجرا مدیریت می کند که شامل پر کردن دیتابیس با object ها، تغییر ردیابی و تداوم داده در دیتابیس می شود. این از DbContex ارث بری می کند.

clip_image011

در این قسمت، پروژه را دوباره build کنید.حالا دوباره این مراحل را برای اضافه کردن Controller API  برای موجودیت های Book طی کنید. در اینجا، Book را به عنوان کلاس model انتخاب کنید و کلاس BookServiceContext  موجود را برای data context انتخاب کنید(data context جدید نسازید) برای اضافه کردن Controller ، Add کنید.

clip_image013

 

 

mr

دوره آموزشی PHP

 کلیه حقوق مادی و معنوی این مقاله متعلق به آموزشگاه تحلیل داده می باشد و هر گونه استفاده غیر قانونی از آن پیگرد قانونی دارد.

آموزش Collection ها در laravel

1. مقدمه

2. نحوه ی ایجاد نمونه ی جدید از کلاس Collection

3. شرح توابع موجود در کلاس  Collection

مقدمه

کلاس Illuminate\Support\Collection از فریم ورک Laravel یک wrapper کارآمد و بهینه برای کار با داده های از نوع آرایه در اختیار برنامه نویس قرار می دهد (wrapper = هر کلاسی که قابلیت و امکانات یک کلاس یا کامپوننت دیگری را در خود کپسوله سازی کند). برای فهم بهتر توجه خود را به مثال ساده ی زیر جلب نمایید.

در این مثال تابع کمکی (helper) collect را فراخوانده و به وسیله ی آن نمونه ای جدید از کلاس collection ایجاد می کنیم. سپس تابع strtoupper را برای هر المان اجرا نموده و تمامی المان های تهی (با مقدار null) را حذف می کنیم:  

$collection = collect(['taylor', 'abigail', null])->map(function ($name) {

    return strtoupper($name);

})

->reject(function ($name) {

    return empty($name);

});

همان طور که از مثال فوق مشاهده می شود، کلاس Collection به شما اجازه می دهد متدهایش را (با اتصال آن ها به انتهای یکدیگر) به صورت زنجیره ای فراخوانی نموده و آرایه را (علاوه بر ویرایش) به آسانی به فیلد مزبور نگاشت (map) نمایید. شایان توجه است که هر متد Collection به طور کلی نمونه ی کاملا جدید از کلاس Collection را در خروجی برمی گرداند. 

نحوه ی ایجاد نمونه ی جدید از کلاس Collection

همان طور که در بالا نیز ذکر شد، تابع کمکی collect یک نمونه ی کاملا جدید از کلاس Illuminate\Support\Collection را در خروجی برمی گرداند. نحوه ی ایجاد collection جدید به صورت زیر می باشد:

$collection = collect([1, 2, 3]);

به طور پیش فرض، collection های مدل های Eloquent در قالب نمونه هایی جدید از کلاس Collection به عنوان خروجی برگردانده می شوند. البته شما آزادید هر زمان که اپلیکیشن استفاده از Collection را ایجاب می کند، از این کلاس استفاده نمایید. 

شرح توابع موجود در کلاس  Collection

در زیر به شرح تمامی متدهای کلاس Collection می پردازیم. یادآور می شویم که تمامی متدهای این کلاس را می توان به منظور دستکاری و ویرایش آسان آرایه به یکدیگر متصل نموده و به صورت زنجیره ای فراخوانی کرد.

بعلاوه تقریبا تمامی متدهای Collection یک نمونه ی جدید از کلاس مزبور را به عنوان خروجی برگردانده تا نمونه ی اصلی collection در صورت لزوم حفظ شده و برای استفاده در آینده در دسترس باشد.

 

فهرست متدهای کلاس Collection

متد all()     

کل آرایه ی اصلی را به عنوان خروجی برمی گرداند: 

collect([1, 2, 3])->all();

// [1, 2, 3]

متد avg()

متد avg میانگین مقادیر موجود در collection را محسابه کرده و در خروجی برمی گرداند:

collect([1, 2, 3, 4, 5])->avg();

// 3                                                                                                                                                                                          

در صورتی که collection دربردارنده ی آرایه یا اشیا تودرتو باشد، بایستی یک کلید در داخل آرایه برای مشخص کردن مقادیری که می خواهید میانگین آن محاسبه شود، ارسال کنید: 

$collection = collect([

    ['name' => 'JavaScript: The Good Parts', 'pages' => 176],

    ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],

]);

$collection->avg('pages');

// 636

Chunk()

این متد یک مجموعه (آرایه) کامل را بر اساس مقداری که به عنوان آرگومان به آن ارسال می شود، به بخش های کوچکتر با اندا��ه ی مشخص تقسیم می کند: 

$collection = collect([1, 2, 3, 4, 5, 6, 7]);

$chunks = $collection->chunk(4);

$chunks->toArray();

// [[1, 2, 3, 4], [5, 6, 7]]

این متد به خصوص داخل view ها و زمانی که با یک سیستم نمایش gird مانند، همچون bootstrap کار می کنید بسیار کارآمد و مفید واقع می شود. فرض کنید یک مجموعه از مدل های Eloquent در دست دارید و می خواهید آن ها به صورت grid را نمایش دهید:

@foreach ($products->chunk(3) as $chunk)

    <div class="row">

        @foreach ($chunk as $product)

            <div class="col-xs-4">{{ $product->name }}</div>

        @endforeach

    </div>

@endforeach

Collapse()

متد collapse مجموعه ای از چندین آرایه ی مجزا را در قالب یک collection واحد و تک بعدی در خروجی برمی گرداند:

$collection = collect([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);

$collapsed = $collection->collapse();

$collapsed->all();

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

Combine()

متد combine کلیدهای یک مجموعه را با مقادیر آرایه یا مجموعه ی دیگر ترکیب می کند:

$collection = collect(['name', 'age']);

$combined = $collection->combine(['George', 29]);

$combined->all();

// ['name' => 'George', 'age' => 29]

 

 

Contains()

متد contains بررسی می کند آیا مجموعه ی مورد نظر حاوی مقدار خاصی هست یا خیر و در صورت وجود مقدار مورد درخواست، true را برمی گرداند:  

$collection = collect(['name' => 'Desk', 'price' => 100]);

$collection->contains('Desk');

// true

$collection->contains('New York');

// false

همچنین می توانید یک جفت کلید / مقدار به عنوان پارامتر به متد contains ارسال کنید. متد نام برده به وسیله ی پارامتر ارسالی بررسی می کند آیا جفت کلید/مقدار ارائه شده در مجموعه وجود دارد یا خیر:

$collection = collect([

    ['product' => 'Desk', 'price' => 200],

    ['product' => 'Chair', 'price' => 100],

]);

$collection->contains('product', 'Bookcase');

// false

همچنین می توانید یک تابع (بازفراخوان) callback به عنوان پارامتر برای بررسی وجود یا عدم وجود مقدار مورد نظر در مجموعه به تابع contains() ارسال کنید: 

$collection = collect([1, 2, 3, 4, 5]);

$collection->contains(function ($key, $value) {

    return $value > 5;

});

// false

متد count()

تعداد کل آیتم های موجود در یک مجموعه را به عنوان خروجی برمی گرداند:

$collection = collect([1, 2, 3, 4]);

$collection->count();

// 4

متد diff()

متد diff دو مجموعه (collection) را با یکدیگر یا یک مجموعه را با یک آرایه ی متعارف PHP مقایسه می کند و تفاوت بین آن ها را در خروجی برمی گرداند:

$collection = collect([1, 2, 3, 4, 5]);

$diff = $collection->diff([2, 4, 6, 8]);

$diff->all();

// [1, 3, 5]

each()

متد حاضر داخل آیتم های موجود در مجموعه حلقه زده و تمامی آیتم ها را به ترتیب و به صورت جداگانه به تابع callback ارسال می کند:

$collection = $collection->each(function ($item, $key) {

    //

});

 

برای خروج از حلقه باید مقدار false را از تابع callback برگردانید:

$collection = $collection->each(function ($item, $key) {

    if (/* some condition */) {

        return false;

    }

});

متد every()

این متد یک مجموعه ی جدید متشکل از تمامی المان های مشخص شده توسط پارامتر ارسالی را در خروجی برمی گرداند:

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->every(4);

// ['a', 'e']

 

 

در صورت تمایل می توانید اندیس شروع یا نقطه ی برش (offset) را به عنوان پارامتر دوم به متد پاس دهید:

$collection->every(4, 1);

// ['b', 'f']

متد except()

متد except همان طور که از نامش پیداست تمامی آیتم های موجود در مجموعه را به استثنای آن هایی که به عنوان پارامتر به متد پاس داده شده اند را به عنوان خروجی برمی گرداند:

$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);

$filtered = $collection->except(['price', 'discount']);

$filtered->all();

// ['product_id' => 1, 'name' => 'Desk']

متد except درست برعکس متد only عمل می کند.

متد filter()

این متد یک مجموعه را بر اساس شرط مشخص شده در تابع callback فیلتر کرده و تنها آن المان هایی را به عنوان خروجی برمی گرداند که با شرط منطبق باشند (مثلا همگی از دو بزرگتر باشند):

$collection = collect([1, 2, 3, 4]);

$filtered = $collection->filter(function ($value, $key) {

    return $value > 2;

});

$filtered->all();

// [3, 4]

این متد نقطه ی مقابل متد reject می باشد.

fitst()

این متد اولین المانی که با شرط معینی همخوانی داشته باشد را به عنوان خروجی برمی گرداند:

collect([1, 2, 3, 4])->first(function ($key, $value) {

    return $value > 2;

});

// 3

همچنین می توانید متد first را بدون آرگومان صدا بزنید که در این صورت اولین المان موجود در مجموعه در خروجی بازیابی می شود. در صورتی که collection تهی باشد، مقدار null برگردانده می شود: 

collect([1, 2, 3, 4])->first();

// 1

متد flatmap()

متد flatmap() داخل یک collection حلقه زده و سپس تک تک المان های آن را به تابع callback ارسال می کند. تابع بازفراخوان (callback) می تواند آیتم های ارسالی را ویرایش کرده و برگرداند. بدین وسیله مجموعه ای جدید از آیتم های ویرایش شده به عنوان خروجی برگردانده می شود. در نهایت آرایه ها flatten شده و در قالب یک آرایه ی واحد و تک بعدی در خروجی به نمایش در می آید:

$collection = collect(

    ['name' => 'Sally'],

    ['school' => 'Arkansas'],

    ['age' => 28]

]);

$flattened = $collection->flatMap(function ($values) {

    return strtoupper($values);

});

$flattened->all();

// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => 28];

متد flatten()

این متد یک مجموعه ی چند بعدی را به یک collection تک بعدی تبدیل می کند:

$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);

$flattened = $collection->flatten();

$flattened->all();

// ['taylor', 'php', 'javascript'];

 

flip()

این متد کلیدهای یک مجموعه را با مقادیر مربوطه ی آن جابجا (جایگزین) می کند (جای کلید و مقدار را با هم عوض می کند):

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$flipped = $collection->flip();

$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']

forget()

متد forget() یک آیتم را بر اساس کلید آن که به عنوان آرگومان پاس داده می شود از مجموعه حذف می نماید:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$collection->forget('name');

$collection->all();

// ['framework' => 'laravel']

نکته: برخلاف دیگر متدهای collection، forget() یک نمونه ی ویرایش شده از مجموعه ی اصلی را به عنوان خروجی بر نمی گرداند. بلکه تنها آن مجموعه ای که برای آن فراخوانده می شود را با حذف آیتمی از آن ویرایش می کند. 

 

ForPage()

متد forPage یک مجموعه ی جدید حاوی آیتم هایی که در صفحه ی مورد نظر با شماره ی معین موجود می باشد را به عنوان نتیجه ی بازگشتی ارائه می دهد:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunk = $collection->forPage(2, 3);

$chunk->all();

// [4, 5, 6]

این متد شماره ی صفحه  و تعداد آیتم هایی که به ازای هر صفحه باید نمایش داده شود را به ترتیب به عنوان آرگومان های ورودی می پذیرد.

متد get()

این متد آیتمی که دارای کلید معین هست را به عنوان خروجی برمی گرداند (کلید را به عنوان آرگومان پذیرفته و در خروجی مقدار مربوطه را برمی گرداند). در صورتی که کلید مورد نظر در آرایه موجود نباشد، مقدار null را به عنوان خروجی برمی گرداند:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$value = $collection->get('name');

// taylor

همچنین می توان یک callback به عنوان مقدار پیشفرض ارسال کرد. در صورتی که کلید مورد نظر در آرایه موجود نباشد مقدار callback را به عنوان خروجی برمی گرداند:

$collection->get('email', function () {

    return 'default-value';

});

// default-value

 

متد groupBy()

این متد آیتم های یک مجموعه را بر اساس کلید ارسال شده به عنوان آرگومان گروه بندی می کند:

 

$collection = collect([

    ['account_id' => 'account-x10', 'product' => 'Chair'],

    ['account_id' => 'account-x10', 'product' => 'Bookcase'],

    ['account_id' => 'account-x11', 'product' => 'Desk'],

]);

$grouped = $collection->groupBy('account_id');

$grouped->toArray();

/*

    [

        'account-x10' => [

            ['account_id' => 'account-x10', 'product' => 'Chair'],

            ['account_id' => 'account-x10', 'product' => 'Bookcase'],

        ],

        'account-x11' => [

            ['account_id' => 'account-x11', 'product' => 'Desk'],

        ],

    ]

*/

علاوه بر ارسال یک key از نوع رشته، می توانید یک تابع callback را به عنوان آرگومان ارسال کنید. تابع callback بایستی مقداری که می خواهید گروه بر اساس آن کلید گروه بندی شوند را به عنوان خروجی برگرداند:

$grouped = $collection->groupBy(function ($item, $key) {

    return substr($item['account_id'], -3);

});

$grouped->toArray();

/*

    [

        'x10' => [

            ['account_id' => 'account-x10', 'product' => 'Chair'],

            ['account_id' => 'account-x10', 'product' => 'Bookcase'],

        ],

        'x11' => [

            ['account_id' => 'account-x11', 'product' => 'Desk'],

        ],

    ]

*/

 

متد has()

این متد بررسی می کند آیا کلید معینی در مجموعه وجود دارد یا خیر:

$collection = collect(['account_id' => 1, 'product' => 'Desk']);

$collection->has('email');

// false

 

 

متد implode()

 

متد implode دو آیتم در یک مجموعه را به هم پیوند می زند (مقدار دو کلید را به یکدیگر join می کند). آرگومان های این متد به نوع آیتم های موجود در مجموعه بستگی دارد.

 

چنانچه آیتم های داخل مجموعه از نوع شی یا آرایه باشند، در آن صورت بایستی کلید آن attribute هایی را که مایلید به یکدیگر پیوند زده شده و نیز تفکیک گری که باید بین دو مقدار قرار گیرد را به ترتیب به عنوان آرگومان های اول و دوم به تابع implode() ارسال کنید. 

$collection = collect([

    ['account_id' => 1, 'product' => 'Desk'],

    ['account_id' => 2, 'product' => 'Chair'],

]);

$collection->implode('product', ', ');

// Desk, Chair

حال اگر مجموعه حاوی مقادیر رشته ای و عددی باشد، کافی است تفکیک گر (برای مثال '-') را به عنوان آرگومان به تابع ارسال کنید:

collect([1, 2, 3, 4, 5])->implode('-');

// '1-2-3-4-5'

 

متد intersect()

متد intersect() تمامی مقادیری که در array یا collection  مورد نظر موجود نیستند را حذف می کند:

$collection = collect(['Desk', 'Sofa', 'Chair']);

$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);

$intersect->all();

// [0 => 'Desk', 2 => 'Chair']

همان طور که می بینید مجموعه ی خروجی کلیدهای collection اصلی را نگه می دارد.

متد isEmpty()

این متد در صورتی که collection مورد نظر تهی باشد مقدار true را برمی گرداند و در غیر این صورت false را بازیابی می کند:

collect([])->isEmpty();

// true

 

متد keyBy()

متد  keyByیک مجموعه را بر اساس کلیدی که به عنوان آرگومان به آن پاس داده شده، کلید دهی (key) می کند: 

$collection = collect([

    ['product_id' => 'prod-100', 'name' => 'desk'],

    ['product_id' => 'prod-200', 'name' => 'chair'],

]);

 

$keyed = $collection->keyBy('product_id');

$keyed->all();

/*

    [

        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],

        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],

    ]

*/

در صورتی که چندین آیتم دارای کلید یکسان باشند، تنها آخرین آیتم در collection خروجی لحاظ می شود.

البته شما می توانید callback خود را به عنوان آرگومان ارسال کنید که خروجی آن کلیدی خواهد بود که مجموعه بر اساس آن کلیددهی (key) می شود: 

$keyed = $collection->keyBy(function ($item) {

    return strtoupper($item['product_id']);

});

$keyed->all();

/*

    [

        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],

        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],

    ]

*/

متد key()

متد keys تمامی کلیدهای یک مجموعه را برمی گرداند:

$collection = collect([

    'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],

    'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],

]);

$keys = $collection->keys();

$keys->all();

// ['prod-100', 'prod-200']

متد last()

آخرین المان موجود در یک collection را که با شرط مشخص شده در تابع callback منطبق می باشد را در خروجی برمی گرداند:

collect([1, 2, 3, 4])->last(function ($key, $value) {

    return $value < 3;

});

// 2

همچنین می توانید متد last را بدون هیچ آرگومان فراخوانی کنید که در آن صورت آخرین المان موجود در مجموعه را برمی گرداند. در صورت تهی بودن collection، مقدار null برگردانده می شود:

collect([1, 2, 3, 4])->last();

// 4

 

 

متد map()

متد map داخل مجموعه حلقه زده و سپس هر مقدار را به تابع callback پاس می دهد. callback می تواند آیتم را ویرایش نموده و آن را در خروجی برگرداند. بدین وسیله یک نمونه ی جدید از مجموعه، متشکل از آیتم های ویرایش شده ی collection اصلی در خروجی ارائه می شود: 

$collection = collect([1, 2, 3, 4, 5]);

$multiplied = $collection->map(function ($item, $key) {

    return $item * 2;

});

$multiplied->all();

// [2, 4, 6, 8, 10]

 

نکته: درست مانند بیشتر متدهای کلاس collection، تابع map یک نمونه ی جدید از کلاس مزبور را به عنوان خروجی برمی گرداند. بنابراین مجموعه ی اصلی که تابع بر روی آن اجرا شده دست نخورده باقی می ماند. به منظور تغییر collection اصلی بایستی متد transform را بر روی آن فراخونی نمایید.  

متد max()

این متد مقدار بیشینه ی کلید معین (بزرگترین مقدار عددی در مجموعه) را به عنوان خروجی برمی گرداند:

$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');

// 20

$max = collect([1, 2, 3, 4, 5])->max();

// 5

متد merge()

متد merge آرایه ی ارسالی به عنوان پارامتر را با مجموعه ی مورد نظر ترکیب می کند. هر کلید رشته ای  موجود در آرایه که با کلید رشته ای داخل مجموعه منطبق باشد، جایگزین مقدار داخل مجموعه شده و روی مقدار آن بازنویسی می شود:  

$collection = collect(['product_id' => 1, 'name' => 'Desk']);

$merged = $collection->merge(['price' => 100, 'discount' => false]);

$merged->all();

// ['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]

در صورتی که کلیدهای آرایه از نوع عددی باشند، مقادیر به انتهای مجموعه ضمیمه می شوند:

 

$collection = collect(['Desk', 'Chair']);

$merged = $collection->merge(['Bookcase', 'Door']);

$merged->all();

// ['Desk', 'Chair', 'Bookcase', 'Door']

تابع min()

متد min() کمترین مقدار را برمی گرداند:

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

$min = collect([1, 2, 3, 4, 5])->min();

// 1

 

متد only()

این متد آیتم های موجود در مجموعه را که دارای کلید مشخص هستند به عنوان خروجی برمی گرداند:

$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);

$filtered = $collection->only(['product_id', 'name']);

$filtered->all();

// ['product_id' => 1, 'name' => 'Desk']

متد only درست برعکس تابع except می باشد.

متد pluck()

متد pluck() تمامی مقادیر موجود در مجموعه که از نظر کلید ارسالی به آن یکسان هستند را در خروجی بازیابی می کند: 

$collection = collect([

    ['product_id' => 'prod-100', 'name' => 'Desk'],

    ['product_id' => 'prod-200', 'name' => 'Chair'],

]);

$plucked = $collection->pluck('name');

$plucked->all();

// ['Desk', 'Chair']

حتی می توانید با ارسال کلید به عنوان پارامتر دوم به این متد، مشخص نمایید collection خروجی با چه اسمی کلید دهی شود:

$plucked = $collection->pluck('name', 'product_id');

$plucked->all();

// ['prod-100' => 'Desk', 'prod-200' => 'Chair']

pop()

pop() آخرین آیتم را از مجموعه حذف کرده و در خروجی برمی گرداند:

$collection = collect([1, 2, 3, 4, 5]);

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

 

متد prepend() یک آیتم را به ابتدای یک مجموعه اضافه می کند:

$collection = collect([1, 2, 3, 4, 5]);

$collection->prepend(0);

$collection->all();

// [0, 1, 2, 3, 4, 5]

در صورت تمایل می توانید یک آرگومان دوم به متد prepend() ارسال کنید که کلید آیتم ضمیمه شده به مجموعه را مشخص می کند:

$collection = collect(['one' => 1, 'two', => 2]);

$collection->prepend(0, 'zero');

$collection->all();

// ['zero' => 0, 'one' => 1, 'two', => 2]

 

pull()

این متد یک آیتم (مقدار) را بر اساس کلیدی که به عنوان آرگومان به آن ارسال شده از مجموعه حذف کرده و در خروجی برمی گرداند:

$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);

$collection->pull('name');

// 'Desk'

$collection->all();

// ['product_id' => 'prod-100']

متد push()

این متد یک آیتم جدید را به انتهای مجموعه ی جاری اضافه می کند:

$collection = collect([1, 2, 3, 4]);

$collection->push(5);

$collection->all();

// [1, 2, 3, 4, 5]

متد put()

این متد یک جفت کلید مقدار جدید را که به صورت آرگومان به آن ارسال شده، در مجموعه درج می کند:

$collection = collect(['product_id' => 1, 'name' => 'Desk']);

$collection->put('price', 100);

$collection->all();

// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]

random()

این متد یک آیتم را به صورت تصادفی از مجموعه گزینش نموده و در خروجی برمی گردارند:

$collection = collect([1, 2, 3, 4, 5]);

$collection->random();

// 4 - (retrieved randomly)

در صورت تمایل می توانید یک عدد صحیح را به عنوان آرگومان به متد ذکر شده پاس دهید. در صورتی که مقدار این آرگومان بزرگتر از 1 باشد، مجموعه ای از آیتم ها به صورت تصادفی در خروجی بازیابی می شود:

$random = $collection->random(3);

$random->all();

// [2, 4, 5] - (retrieved randomly)

متد reduce()

یک مجموعه از مقادیر را به تنها یک مقدار تبدیل می کند و نتیجه ی هر iteration را به iteration بعدی پاس می دهد: 

$collection = collect([1, 2, 3]);

$total = $collection->reduce(function ($carry, $item) {

    return $carry + $item;

});

// 6

مقدار متغیر $carry در تکرار یا چرخش اول null می باشد. البته شما می توانید با ارسال آرگومان دیگری به تابع مقدار آغازین را مشخص نمایید:

$collection->reduce(function ($carry, $item) {

    return $carry + $item;

}, 4);

// 10

 

تابع reject()

این متد مجموعه را بر اساس شرط تعیین شده در تابع callback که به عنوان پارامتر پاس داده شده فیلتر می کند. تابع callback بایستی برای هر آیتمی که با شرط منطبق نیستند و می خواهد از مجموعه ی ورودی حذف کند (و در مجموعه ی خروجی لحاظ نکند)، مقدار true را بر گرداند:

$collection = collect([1, 2, 3, 4]);

$filtered = $collection->reject(function ($value, $key) {

    return $value > 2;

});

$filtered->all();

// [1, 2]

متد reject عملکردی متضاد متد filter دارد.

متد reverse()

متد reverse() ترتیب قرارگیری آیتم های مجموعه را معکوس می کند:

$collection = collect([1, 2, 3, 4, 5]);

$reversed = $collection->reverse();

$reversed->all();

// [5, 4, 3, 2, 1]

 

متد search()

این متد مقداری که به عنوان آرگومان به آن پاس داده شده را داخل مجموعه جستجو کرده و کلید آن را در صورت یافتن مقدار مورد درخواست، در خروجی برمی گرداند. اگر آیتم مورد نظر یافت نشد، مقدار false برگردانده می شود:

$collection = collect([2, 4, 6, 8]);

$collection->search(4);

// 1

جستجو داخل مجموعه بر اساس یک مقایسه ی تقریبی صورت می پذیرد. به منظور اعمال مقایسه ی دقیق کافی است مقدار true را به عنوان پارامتر ورودی دوم به متد مذکور ارسال نمایید:

$collection->search('4', true);

// false

همچنین می توانید تابع بازفرخوان (callback) خود را به عنوان آرگومان ارسال نمایید. این تابع به دنبال اولین آیتمی (از نظر مکان قرارگیری) که با شرط مشخص شده داخلش مطابقت دارد گشته و آن را به عنوان خروجی برمی گرداند:

$collection->search(function ($item, $key) {

    return $item > 5;

});

// 2

 

متد shift()

اولین آیتم را از مجموعه حذف کرده و در خروجی بازمی گرداند:

$collection = collect([1, 2, 3, 4, 5]);

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

تابع shuffle()

آیتم های موجود در مجموعه را به طور تصادفی (و نه بر اساس ترتیب مشخص) مرتب می کند:

$collection = collect([1, 2, 3, 4, 5]);

$shuffled = $collection->shuffle();

$shuffled->all();

// [3, 2, 5, 1, 4] // (generated randomly)

 

متد slice()

این متد بر اساس اندیس شروع که به عنوان آرگومان به آن ارسال شده یک مجموعه را برش داده و در خروجی برمی گرداند. مثال زیر آیتم های بعد از شماره ی مکان قرارگیری 4 را از مجموعه استخراج می کند:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$slice = $collection->slice(4);

$slice->all();

// [5, 6, 7, 8, 9, 10]

 برای کاهش سایز خروجی (و محدود تر کردن نتیجه)، می توانید یک آرگومان دوم به متد ارسال کنید. این آرگومان تعداد آیتم های استخراجی از collection را تعیین می کند:

$slice = $collection->slice(4, 2);

$slice->all();

// [5, 6]

آیتم های استخراج شده به عنوان خروجی مجددا با کلیدهای عددی اندیس گذاری می شوند (کلیدهایی از نوع عدد اندیس جدید آن ها خواهد بود). اگر مایلید کلیدهای اصلی را حفظ کنید، درآن صورت کافی است مقدار true را به عنوان آرگومان سوم به متد ارسال نمایید.

sort()

این متد مجموعه را مرتب سازی می نماید:

$collection = collect([5, 3, 1, 2, 4]);

$sorted = $collection->sort();

$sorted->values()->all();

// [1, 2, 3, 4, 5]

مجموعه ی مرتب شده کلیدهای اصلی آرایه را حفظ می کند (کلیدهای اصلی آرایه پس از مرتب سازی تغییر نکرده و ثابت می ماند). در این مثال با استفاده از متد values کلید های آیتم های مجموعه را دوباره (به ترتیب عددی متوالی) اندیس گذاری می کنیم.

به منظور مرتب سازی مجموعه ای از اشیا و آرایه های تودرتو، بخش های مربوط به متدهای sortBy و sortByDesc را مطالعه نمایید.

در صورتی که مرتب سازی شما حالت پیچیده تری به خود می گیرد، درآن صورت می توانید یک تابع callback با الگوریتم اختصاصی خود به عنوان آرگومان به متد sort ارسال کنید. 

متد sortBy()

این متد مجموعه را بر اساس کلید ارسالی (به عنوان آرگومان) مرتب سازی می کند:

$collection = collect([

    ['name' => 'Desk', 'price' => 200],

    ['name' => 'Chair', 'price' => 100],

    ['name' => 'Bookcase', 'price' => 150],

]);

$sorted = $collection->sortBy('price');

$sorted->values()->all();

/*

    [

        ['name' => 'Chair', 'price' => 100],

        ['name' => 'Bookcase', 'price' => 150],

        ['name' => 'Desk', 'price' => 200],

    ]

*/

کلیدهای آرایه پس از مرتب سازی ثابت می ماند. در این نمونه، از متد values برای اندیس گذاری آیتم های آرایه به ترتیب عددی متوالی بهره گرفتیم (با values کلیدهای آرایه را به ترتیب عددی متوالی اندیس گذاری می کنیم).

شما می توانید تابع callback خود را برای تعیین نحوه ی مرتب سازی مقادیر مجموعه به متد نام برده ارسال کنید:

$collection = collect([

    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],

    ['name' => 'Chair', 'colors' => ['Black']],

    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],

]);

$sorted = $collection->sortBy(function ($product, $key) {

    return count($product['colors']);

});

$sorted->values()->all();

/*

    [

        ['name' => 'Chair', 'colors' => ['Black']],

        ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],

        ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],

    ]

*/

متد sortByDesc()

این متد از نظر نوع و تعداد پارامتر ورودی (signature) با متد sortBy یکسان است ولی مجموعه ی مورد نظر را بجای صعودی، به ترتیب نزولی sort می کند.

متد splice()

متد splice یک اندیس شروع به عنوان آرگومان می پذیرد. سپس آیتم هایی که پس از اندیس مشخص شده قرار دارند را از مجموعه برش داده و استخراج می کند:

$collection = collect([1, 2, 3, 4, 5]);

$chunk = $collection->splice(2);

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

می توانید یک آرگومان دوم پاس دهید که تعداد آیتم های استخراجی از مجموعه را مشخص می کند. از این طریق می توانید اندازه ی خروجی را محدود نمایید:

$collection = collect([1, 2, 3, 4, 5]);

$chunk = $collection->splice(2, 1);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

علاوه بر دو آرگومان اول، می توان یک آرگومان سوم حاوی مقادیری که قرار است جایگزین مقادیر حذف شده از مجموعه گردد به متد ارسال کنید:

$collection = collect([1, 2, 3, 4, 5]);

$chunk = $collection->splice(2, 1, [10, 11]);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 10, 11, 4, 5]

متد sum()

این متد حاصل جمع تمامی آیتم های موجود در مجموعه را به عنوان خروجی برمی گرداند:

collect([1, 2, 3, 4, 5])->sum();

// 15

چنانچه مجموعه دربردارنده ی آرایه ها یا اشیا تودرتو باشد، در آن صورت می بایست یک کلید به عنوان آرگومان ارسال کنید. این آرگومان مشخص می کند حاصل جمع کدام مقادیر بایستی به عنوان خروجی برگردانده شوند:

$collection = collect([

    ['name' => 'JavaScript: The Good Parts', 'pages' => 176],

    ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],

]);

$collection->sum('pages');

// 1272

علاوه بر آن می توانید یک تابع callback به متد ارسال کنید که مشخص می کند حاصل جمع کدام مقادیر از مجموعه بایستی محاسبه شده و در خروجی لحاظ شود:

$collection = collect([

    ['name' => 'Chair', 'colors' => ['Black']],

    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],

    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],

]);

$collection->sum(function ($product) {

    return count($product['colors']);

});

// 6

متد take()

این متد یک مجموعه ی جدید از collection جاری ایجاد کرده و در خروجی برمی گرداند. پارامتر ارسالی به متد تعداد آیتم هایی که باید در خروجی لحاظ شود را مشخص می کند:

$collection = collect([0, 1, 2, 3, 4, 5]);

$chunk = $collection->take(3);

$chunk->all();

// [0, 1, 2]

همچنین می توانید یک عدد صحیح منفی به تابع ارسال نموده و آیتم های مورد نظر را از انتهای مجموعه استخراج نمایید:

$collection = collect([0, 1, 2, 3, 4, 5]);

$chunk = $collection->take(-2);

$chunk->all();

// [4, 5]

متد toArray()

این متد همان طور که از نامش پیدا است collection مورد نظر را به یک آرایه ی متعارف در PHP تبدیل می کند. چنانچه مقادیر موجود در مجموعه از مدل های Eloquent باشند، در آن صورت مدل ها نیز در اثر اجرای این متد به آرایه تبدیل می شوند: 

 

$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toArray();

/*

    [

        ['name' => 'Desk', 'price' => 200],

    ]

*/

 

نکته: toArray تمامی اشیای قرار گرفته در دل مجموعه (nested و تودرتو) را نیز به آرایه تبدیل می کند. اگر می خواهید آرایه را همان طور که هست (بدون تغییر) دریافت کنید، در آن صورت بایستی (بجای متد نام برده) متد all را فراخوانی نمایید. 

تابع toJson()

مجموعه را به فرمت JSON تبدیل می کند:

$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toJson();

// '{"name":"Desk","price":200}'

متد transform()

این متد داخل مجموعه حلقه زده و callback ارسالی به متد را به ازای هر آیتم داخل collection صدا می زند. آیتم های موجود در مجموعه با مقادیر بازگشتی (خروجی callback) جایگزین می شوند:  

$collection = collect([1, 2, 3, 4, 5]);

$collection->transform(function ($item, $key) {

    return $item * 2;

});

$collection->all();

// [2, 4, 6, 8, 10]

 

نکته: بر خلاف عمده ی متدهای کلاس collection، تابع transforms در اصل خود مجموعه تغییرات را اعمال نموده و یک مجموعه ی ویرایش شده را در نتیجه بر می گرداند. اگر می خواهید یک مجموعه ی جدید بجای ویرایش مجموعه ی اصلی دریافت کنید، در آن صورت بایستی متد map را فراخوانی نمایید.  

 

 

متد union()

تابع union آرایه ی ورودی را به مجموعه ی جاری اضافه می کند. در صورتی که آرایه ی ورودی دربردارنده ی کلیدهایی باشد که مانند آن ها در مجموعه موجود است، مقادیر مجموعه ارجحیت پیدا می کنند:

$collection = collect([1 => ['a'], 2 => ['b']]);

$union = $collection->union([3 =>