برای استفاده مؤثر از رابط برنامهنویسی کاربردی اسلایدها، باید معماری ارائهها و اجزای آنها و همچنین تعاملات بین این اجزا را درک کنید. این صفحه مروری دقیق بر این مباحث ارائه میدهد:
- مدل مفهومی اجزای ارائه
- نحوه نمایش این اجزا توسط API
- ویژگیهای استایلدهی اجزا
خواندن این و سایر مرورهای مفهومی، درک و استفاده از راهنماهای آموزشی ، مستندات مرجع و نمونههای دستور پخت را آسانتر میکند.
ارائهها، صفحات و عناصر صفحه
بیرونیترین عنصر کانتینر در گوگل اسلایدز، یک ارائه (presentation) است. این واحدی است که میتواند در گوگل درایو ذخیره شود، با سایر کاربران به اشتراک گذاشته شود و غیره.
هر ارائه شامل انواع مختلفی از صفحات است. یک نوع صفحه، اسلاید است که صفحاتی هستند که کاربران هنگام نمایش ارائه روی صفحه، آنها را میبینند و بین آنها جابهجا میشوند.
هر صفحه شامل تعدادی عنصر صفحه است که در کنار هم محتوای صفحه را تشکیل میدهند، همانطور که در نمودار زیر نشان داده شده است:
گذشته از اسلایدها، انواع دیگری از صفحات وجود دارند که به شما امکان میدهند طراحی را روی اسلایدهای مختلف اعمال کنید و ظاهری یکپارچه ایجاد کنید. این انواع دیگر صفحات، صفحات اصلی و طرحبندی هستند و ویژگیهای آنها نحوه نمایش اسلایدها را تعیین میکند، همانطور که در نمودار زیر نشان داده شده است:
صفحات اصلی - صفحه اصلی دو هدف را دنبال میکند. متغیرهای موجود در صفحه اصلی شامل پیشفرضهای سبکهای متنی مورد استفاده در طول ارائه شما هستند. پسزمینه و هر شکل دیگری در اسلاید اصلی، پسزمینه پیشفرض برای همه اسلایدها را بر اساس آن صفحه اصلی تشکیل میدهد. اگر لوگوی شرکتی دارید که میخواهید در هر اسلاید ارائه شما نمایش داده شود، آن را در صفحه اصلی قرار دهید.
طرحبندیها — قالبهای طرحبندی نحوه چیدمان محتوا در هر نوع اسلاید را تعیین میکنند. برای مثال، اگر میخواهید همه اسلایدهای عنوان شما به شکل خاصی باشند، میتوانید قالب طرحبندی عنوان را ویرایش کنید.
دو نوع صفحه دیگر وجود دارد - صفحات یادداشتها و صفحات اصلی یادداشتها - که بیشتر برای کار با یادداشتهای گوینده مرتبط هستند.
انواع و ساختار نمایش API
این بخش نحوه نمایش مدل مفهومی گوگل اسلایدز، همانطور که در بالا توضیح داده شد، در رابط برنامهنویسی کاربردی اسلایدها را شرح میدهد.
نمودار زیر رابطه بین ارائهها، صفحات و عناصر صفحه را به عنوان انواع در API اسلایدها نشان میدهد:
بخشهای زیر نحوه نمایش این نوعها در JSON را نشان میدهند.
ارائهها
یک ارائه شامل تعدادی ویژگی است و صفحاتی را که در آن قرار دارند، در بر میگیرد:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
صفحات
یک صفحه شامل مجموعهای از ویژگیها و عناصر صفحهای است که در آن قرار دارند:
{
"objectId": string,
"pageType": enum(PageType),
"pageElements": [ { object(PageElement) } ],
"pageProperties": { object(PageProperties) },
// Union field properties can be only one of the following:
"slideProperties": { object(SlideProperties) },
"layoutProperties": { object(LayoutProperties) },
"notesProperties": { object(NotesProperties) },
// End of list of possible types for union field properties.
}
عناصر صفحه
عناصر صفحه، اجزای بصری هستند که در صفحات قرار میگیرند. یک عنصر صفحه در API شامل تعدادی ویژگی است، از جمله فیلدی که بسته به نوع عنصر صفحه متفاوت است:
{
"objectId": string,
"size": { object(Size) },
"transform": { object(AffineTransform) },
"title": string,
"description": string,
// Union field element_kind can be only one of the following:
"elementGroup": { object(Group) },
"shape": { object(Shape) },
"image": { object(Image) },
"video": { object(Video) },
"line": { object(Line) },
"table": { object(Table) },
"wordArt": { object(WordArt) },
"sheetsChart": { object(SheetsChart) },
// End of list of possible types for union field element_kind.
}
همانطور که در تعریف بالا توسط فیلد element_kind تعریف شده است، انواع مختلفی از عناصر صفحه وجود دارد. این نوع عناصر صفحه در جدول زیر شرح داده شدهاند:
| نوع عنصر | توضیحات |
|---|---|
| گروه | مجموعهای از عناصر صفحه که به عنوان یک واحد مجزا در نظر گرفته میشوند. آنها را میتوان با هم جابجا، مقیاسبندی و چرخاند. |
| شکل | یک شیء بصری ساده، مانند مستطیل، بیضی و کادرهای متنی. شکلها میتوانند حاوی متن باشند، بنابراین رایجترین عناصر صفحه برای ساخت اسلایدها هستند. |
| تصویر | گرافیکی که به اسلایدها وارد شده است. |
| ویدئو | ویدیویی که به اسلایدها وارد شده است. |
| خط | یک خط، منحنی یا رابط بصری. |
| میز | شبکهای از محتوا. |
| وردآرت | یک عنصر متنی بصری که بیشتر شبیه یک شکل رفتار میکند. |
| چارتهای ورقی | نموداری که از Google Sheets به اسلایدها وارد شده است. |
ویژگیهای صفحه و عنصر صفحه
رابط برنامهنویسی کاربردی اسلایدها (Slides API) به شما امکان میدهد ظاهر صفحات و عناصر صفحه را در ارائه خود بخوانید و بهروزرسانی کنید. عناصر مختلف صفحه از ویژگیهای مختلفی پشتیبانی میکنند که نحوه رندر شدن عنصر صفحه را کنترل میکنند.
هر نوع عنصر صفحه دارای یک عنصر ویژگیهای مربوطه و یک پیام بهروزرسانی ویژگیها است، برای مثال:
- یک نوع عنصر صفحه به نام شکل وجود دارد
- فیلد ویژگی آن shapeProperties است.
- درخواست بهروزرسانی این ویژگیها UpdateShapePropertiesRequest است.
همان مجموعه درخواستهای عنصر/ویژگیها/بهروزرسانی برای هر نوع عنصر صفحه وجود دارد: تصویر / تصویرویژگیها / بهروزرسانیتصویرویژگیها و غیره.
میتوانید ویژگی properties را هر جا که هنگام خواندن یک عنصر با آن مواجه شدید، بخوانید؛ برای تغییر مقادیر موجود در آن، از آن به همراه نوع درخواست منطبق به عنوان payload برای متد batchUpdate استفاده کنید و به شما امکان میدهد این مقادیر را در ارائه تغییر دهید.
انواع املاک
برخی از ویژگیها بین چندین نوع شیء در API اسلایدها مشترک هستند:
| ملک | توضیحات |
|---|---|
| رنگ | رنگها در رابط برنامهنویسی کاربردی اسلایدها میتوانند یا یک مقدار RGB باشند یا ارجاعی به رنگ تم. رنگهای تم با نام (مثلاً "DARK1") مشخص میشوند و میتوانند با استفاده از طرح رنگ یک صفحه به مقادیر RGB نگاشت شوند. این طرح رنگ معمولاً هنگام تغییر تم ارائه در ویرایشگر اسلایدها بهروزرسانی میشود. |
| پر کردن | پر کردن، نمایش فضای خالی درون یک شیء را نشان میدهد. رایجترین پر کردن پشتیبانی شده در اسلایدها، پر کردن جامد است که در آن فضای داخلی یک شیء با یک رنگ جامد پر میشود. پر کردنها همچنین میتوانند برای پسزمینههای صفحات استفاده شوند. |
| طرح کلی | طرح کلی (outline) مجموعهای از خطوط است که عنصر صفحه را احاطه کردهاند. رنگ خطوط با Fill کنترل میشود. همچنین میتوان عرض و سبک خط تیره خطوط کلی را تنظیم کرد. |
| سایه | سایه یک جلوه بصری است که به منظور تقلید از سایه فیزیکی ایجاد شده توسط شیء به کار میرود. در حال حاضر، سایهها در API اسلایدها فقط خواندنی هستند. |
بهروزرسانی ویژگیها
برای بهروزرسانی یک ویژگی، از درخواست Update ... Properties مناسب در یک فراخوانی batchUpdate استفاده کنید - برای مثال، UpdateShapeProperties برای Shapes. این درخواستها یک پیام ویژگیهای کامل را میپذیرند و میتوانند از ماسکهای فیلد برای تعیین اینکه کدام فیلدها در پیام ویژگیها باید بهروزرسانی شوند، استفاده کنند.
ارث اموال
یک صفحه یا عنصر صفحه میتواند ویژگیهایی را از اشیاء والد خود به ارث ببرد. ویژگیهای یک شیء، شامل آنهایی که تعریف میکند و آنهایی که به ارث میبرد، ظاهر بصری نهایی آن را تعیین میکنند.
- ویژگیهای صفحه - یک صفحه، هر ویژگیای را که تعریف نمیکند، اما در طرحبندی یا صفحه اصلی که بر اساس آن ساخته شده است، تعریف شدهاند، به ارث میبرد.
- ویژگیهای شکل — یک شکل میتواند به عنوان یک نگهدارنده مکان (placeholder ) علامتگذاری شود، که به شما امکان میدهد به طور صریح به یک شکل نگهدارنده مکان دیگر (در طرحبندی والد یا طرحبندی اصلی صفحه) ارجاع دهید تا ویژگیهای آن را به ارث ببرید.
این ایدهها در پاراگرافهای بعدی بیشتر توضیح داده شدهاند.
ارث بری از ویژگی های صفحه
ساختار اسلایدها، طرحبندیها و طرحهای اصلی، سلسله مراتب وراثت را در ارائه تعریف میکنند: اسلایدها از طرحبندیها و طرحبندیها از طرحهای اصلی به ارث میرسند. طرحبندی والد و طرح اصلی یک اسلاید در فیلد slideProperties اسلاید مشخص میشوند.
یک صفحه میتواند ویژگیهایی مانند پسزمینه و طرح رنگ را از صفحه والد به ارث ببرد. برای به ارث بردن یک ویژگی، صفحه فرزند به سادگی مقداری را برای آن ویژگی در پیام PageProperties خود تعیین نمیکند. با "لغو" نکردن مقدار تعریف شده توسط والد، صفحه مقدار به ارث برده شده را میپذیرد.
نمودار زیر اسلایدی را نشان میدهد که ویژگیهایی را از یک طرحبندی به ارث میبرد، که آن طرحبندی نیز از یک طرحبندی اصلی به ارث میبرد:
ویژگیهایی که برای رندر کردن یک اسلاید استفاده میشوند، ترکیبی از ویژگیهایی هستند که آن اسلاید تعریف میکند و ویژگیهایی که از آن ارثبری میکند. در این مثال، مقادیر حلشدهی مورد استفاده برای رندر کردن اسلاید ۱ به شرح زیر است:
- ملک A "قرمز" است.
- ملکB "نارنجی" است.
وراثت ویژگیهای شکل
شکلها میتوانند ویژگیهایی مانند پر کردن، طرح کلی یا سایه را از شکلهای دیگر به ارث ببرند. یک شکل در صورتی یک نگهدارنده مکان است که فیلد Shape.placeholder آن تنظیم شده باشد. فیلد Shape.placeholder.parentObjectId نگهدارنده مکان فرزند، نگهدارنده مکان والد آن را مشخص میکند. وقتی یک اسلاید جدید بر اساس یک طرحبندی ایجاد میکنید، هر نگهدارنده مکان در آن طرحبندی به عنوان شکلهای فرزند در اسلاید جدید ظاهر میشود. به طور مشابه، نگهدارندههای مکان در صفحات اصلی میتوانند به عنوان والد نگهدارندههای مکان طرحبندی عمل کنند.
با تعریف این سلسله مراتب ارثبری، صفحه فرزند با عدم تنظیم مقدار یک ویژگی در پیام ShapeProperties خود، آن را به ارث میبرد. با عدم بازنویسی مقدار تعریف شده توسط والد، شکل فرزند مقدار ارثبری شده را میپذیرد.
نمودار زیر وراثت ویژگیها بین سه متغیر موجود در یک اسلاید، یک طرحبندی و یک عنصر اصلی را نشان میدهد:
ویژگیهایی که برای رندر کردن یک شکل حفره یا سوراخ استفاده میشوند، ترکیبی از ویژگیهایی هستند که آن شکل تعریف میکند و ویژگیهایی که از آن ارث میبرد. در این مثال، مقادیر حلشده برای این شکلها به شرح زیر است:
- جاینگهدار ۱: ویژگی A به صورت "زرد" و ویژگی B به صورت "سبز" رندر میشود.
- Placeholder2: propertyA به صورت "زرد" و propertyB به صورت "بنفش" رندر میشوند.
- جاینگهدار۳: ویژگیA به صورت "زرد" و ویژگیB به صورت "بنفش" رندر میشوند.
شکلها تنها نوع عنصر صفحه هستند که میتوانند والد داشته باشند. انواع دیگر، مانند تصاویر، جداول و نمودارها، نمیتوانند جانگهدار باشند و والد ندارند.
پنهان کردن ویژگیها با استفاده از PropertyState
شمارش PropertyState کنترل میکند که آیا ویژگی یک شکل واقعاً برای رندر کردن استفاده میشود یا اینکه مقدار آن فقط برای ارثبری توسط شکلهای فرزند استفاده میشود. یک ویژگی با حالت ویژگی NOT_RENDERED هنگام رندر کردن شکل در صفحهاش استفاده نمیشود، با این حال، فرزندانی که حالت ویژگی متناظر RENDERED دارند، همچنان میتوانند این ویژگی را به ارث ببرند.
نمودار زیر وراثت ویژگیها بین سه متغیر که فیلد PropertyState را دستکاری میکنند، نشان میدهد:
رندر کردن ویژگیهای شکل میتواند تحت تأثیر فیلد PropertyState قرار گیرد. در این مثال، مقادیر حلشده برای این شکلها به شرح زیر است:
- Placeholder1: propertyA به صورت "Red" رندر میشود.
- Placeholder2: propertyA رندر نشده است. اگر این ویژگی outline بود، Placeholder2 هیچ outline نداشت.
- Placeholder3: propertyA رندر نشده است.
یک مقدار دیگر برای شمارش PropertyState وجود دارد: حالت ویژگی INHERIT به این معنی است که خود حالت ویژگی به ارث میرسد و باید از مقدار والد استفاده شود. شکلهایی که والد ندارند نمیتوانند حالت ویژگی INHERIT داشته باشند.