برای استفاده مؤثر از Slides API، باید معماری ارائه‌ها و مؤلفه‌های آن‌ها و همچنین تعاملات بین این مؤلفه‌ها را درک کنید. این صفحه نمای کلی دقیقی از این موضوعات ارائه می‌دهد:
- مدل مفهومی مؤلفه‌های ارائه
- نحوه نمایش این مؤلفه‌ها توسط API
- ویژگی‌های سبک‌بندی مؤلفه‌ها
خواندن این نمای کلی و سایر نماهای کلی مفهومی، درک و استفاده از راهنماهای گام‌به‌گام، اسناد مرجع، و نمونه‌های کد را آسان‌تر می‌کند.
ارائه‌ها، صفحه‌ها، و عناصر صفحه
بیرونی‌ترین عنصر نگهدارنده در «اسلایدنگار Google» ارائه است. این واحدی است که می‌تواند در Google Drive ذخیره شود، با کاربران دیگر هم‌رسانی شود، و غیره.
هر ارائه حاوی انواع مختلفی از صفحه‌ها است. یک نوع صفحه، اسلاید است که صفحاتی هستند که کاربران هنگام ارائه روی صفحه‌نمایش می‌بینند و بین آن‌ها جابه‌جا می‌شوند.
هر صفحه حاوی تعدادی عنصر صفحه است که باهم محتوای صفحه را تشکیل می‌دهند، همان‌طور که در نمودار زیر نشان داده شده است:
علاوه‌بر اسلایدها، انواع دیگری از صفحه‌ها وجود دارد که به شما امکان می‌دهد طراحی را روی اسلایدهای مختلف اعمال کنید و ظاهری یکپارچه ایجاد کنید. این انواع دیگر صفحه صفحه اصلی و چیدمان هستند و ویژگی‌های آن‌ها نحوه ارائه اسلایدها را تعیین می‌کند، همان‌طور که در نمودار زیر نشان داده شده است:
صفحه‌های اصلی — صفحه اصلی دو هدف را دنبال می‌کند. جای‌بان‌ها در اسلاید اصلی حاوی پیش‌فرض‌های سبک‌های نوشتار استفاده‌شده در سراسر ارائه شما هستند. پس‌زمینه و هر شکل دیگری در اسلاید اصلی، پس‌زمینه پیش‌فرض را برای همه اسلایدهای مبتنی بر آن اسلاید اصلی تشکیل می‌دهند. اگر نشان‌واره شرکتی دارید که می‌خواهید در همه اسلایدهای ارائه‌تان نشان داده شود، آن را در اسلاید اصلی قرار دهید.
چیدمان‌ها — الگوهای چیدمان تعیین می‌کنند که محتوا در هر نوع اسلاید چگونه چیده شود. برای مثال، اگر می‌خواهید همه اسلایدهای عنوانتان ظاهر خاصی داشته باشند، می‌توانید الگوی چیدمان عنوان را ویرایش کنید.
دو نوع صفحه دیگر وجود دارد—صفحه‌های یادداشت و یادداشت‌های اصلی—که بیشتر برای کار با یادداشت‌های گوینده مناسب هستند.
ساختار و انواع نمایش API
این بخش توضیح می‌دهد که چگونه مدل مفهومی «اسلایدنگار Google»، همان‌طور که در بالا شرح داده شد، در Slides API نشان داده می‌شود.
نمودار زیر رابطه بین ارائه‌ها، صفحه‌ها، و عناصر صفحه را به‌عنوان انواع در Slides API نشان می‌دهد:
بخش‌های زیر نشان می‌دهند که این انواع چگونه در JSON نمایش داده می‌شوند.
ارائه‌ها
ارائه شامل تعدادی ویژگی است و صفحه‌هایی را که در آن وجود دارد دربرمی‌گیرد:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Pages
صفحه شامل مجموعه‌ای از ویژگی‌ها است و عناصر صفحه موجود در آن را دربرمی‌گیرد:
{
"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 در تعریف بالا تعریف شده است. این نوع عناصر صفحه در جدول زیر شرح داده شده‌اند:
| نوع عنصر | شرح |
|---|---|
| گروه | مجموعه‌ای از عناصر صفحه که به‌عنوان واحدی مجزا درنظر گرفته می‌شود. می‌توان آن‌ها را با هم جابه‌جا کرد، مقیاس‌بندی کرد، و چرخاند. |
| شکل‌ها | شیء دیداری ساده، مثل مستطیل، بیضی، و چارگوش نوشتاری. شکل‌ها می‌توانند حاوی نوشتار باشند، بنابراین رایج‌ترین عناصر صفحه برای ساختن اسلاید هستند. |
| تصویر | گرافیکی که به «اسلایدنگار» وارد شده است. |
| ویدیو | ویدیویی که به «اسلایدنگار» وارد شده است. |
| خط | خط، منحنی، یا اتصال‌دهنده دیداری. |
| جدول | شبکه‌ای از محتوا. |
| WordArt | عنصر نوشتاری دیداری که بیشتر شبیه شکل عمل می‌کند. |
| SheetsChart | نموداری که از «کاربرگ‌نگار Google» به «اسلایدنگار» وارد شده است. |
خصوصیات صفحه و عنصر صفحه
Slides API به شما امکان می‌دهد ظاهر صفحه‌ها و عناصر صفحه را در ارائه‌تان بخوانید و به‌روز کنید. عناصر مختلف صفحه از ویژگی‌های مختلفی پشتیبانی می‌کنند که نحوه ارائه عنصر صفحه را کنترل می‌کنند.
هر نوع عنصر صفحه دارای یک عنصر ویژگی‌های متناظر و یک پیام به‌روزرسانی ویژگی‌ها است، برای مثال:
- عنصر صفحه از نوع شکل وجود دارد
- فیلد ویژگی آن shapeProperties است
- درخواست به‌روزرسانی این ویژگی‌ها UpdateShapePropertiesRequest است
مجموعه یکسانی از عنصر/ویژگی‌ها/درخواست به‌روزرسانی برای هر نوع عنصر صفحه وجود دارد: Image/imageProperties/UpdateImageProperties، و غیره.
هرجا که در خواندن عنصر با مشخصه properties مواجه شدید، می‌توانید آن را بخوانید؛ برای تغییر مقادیر آن، از آن با نوع درخواست منطبق به‌عنوان بار مفید برای روش batchUpdate استفاده کنید، که به شما امکان می‌دهد این مقادیر را در ارائه تغییر دهید.
انواع دارایی‌ها
برخی‌از ویژگی‌ها بین چند نوع شیء در Slides API مشترک است:
| دارایی | شرح |
|---|---|
| رنگ | رنگ‌ها در Slides API می‌توانند مقدار RGB یا ارجاعی به رنگ زمینه باشند. رنگ‌های زمینه با نام (مثلاً «DARK1») ارجاع داده می‌شوند و می‌توانند بااستفاده از طرح رنگ صفحه به مقادیر RGB نگاشت شوند. این آرایش رنگ‌ها معمولاً هنگام تغییر دادن زمینه ارائه در ویرایشگر «اسلایدنگار» به‌روز می‌شود. |
| پرکننده | پر کردن نشان‌دهنده رندر کردن فضای خالی داخل شیء است. رایج‌ترین پرکننده پشتیبانی‌شده در «اسلایدنگار» پرکننده یک‌رنگ است که در آن داخل شیء با یک رنگ ثابت پر می‌شود. از رنگ‌های پرکننده می‌توان برای پس‌زمینه «صفحه‌ها» نیز استفاده کرد. |
| رئوس مطالب | خط پیرامونی نشان‌دهنده مجموعه‌ای از خطوط است که عنصر صفحه را احاطه کرده‌اند. رنگ خطوط با «پر کردن» کنترل می‌شود. تماس‌گیرندگان همچنین می‌توانند پهنا و سبک خط‌چین حاشیه‌ها را تنظیم کنند. |
| سایه | سایه نشان‌دهنده جلوه دیداری است که برای تقلید از سایه فیزیکی ایجادشده توسط شیء طراحی شده است. درحال‌حاضر، سایه‌ها در Slides API فقط خواندنی هستند. |
درحال به‌روزرسانی مشخصات
برای به‌روزرسانی یک ویژگی، از درخواست مناسب
Update...Properties در یک فراخوانی
batchUpdate
استفاده کنید—برای مثال، UpdateShapeProperties برای اشکال. این درخواست‌ها
پیام کامل ویژگی‌ها را می‌پذیرند و می‌توانند از
ماسک‌های فیلد برای تعیین اینکه کدام فیلدها در
پیام ویژگی‌ها باید به‌روزرسانی شوند استفاده کنند.
ارثیه ملکی
صفحه یا عنصر صفحه می‌تواند خصوصیت‌ها را از اشیاء ولی خود به ارث ببرد. ویژگی‌های یک شیء، ازجمله ویژگی‌هایی که تعریف می‌کند و ویژگی‌هایی که به ارث می‌برد، ظاهر بصری نهایی آن را تعیین می‌کنند.
- ویژگی‌های صفحه — صفحه هر ویژگی‌ای را که تعریف نکند، اما در چیدمان یا صفحه اصلی که بر آن مبتنی است تعریف شده باشد، به ارث می‌برد.
- ویژگی‌های شکل — شکل را می‌توان به‌عنوان جای‌بان علامت‌گذاری کرد، که به شما اجازه می‌دهد صریحاً به شکل جای‌بان دیگری (در چیدمان ولی یا اصلی صفحه) ارجاع دهید تا ویژگی‌ها را از آن به ارث ببرید.
این ایده‌ها در پاراگراف‌های زیر بیشتر توضیح داده شده‌اند.
توارث خصوصیات صفحه
ساختار اسلایدها، چیدمان‌ها، و الگوها سلسله‌مراتب ارث‌بری را در ارائه تعریف می‌کند: اسلایدها از چیدمان‌ها ارث‌بری می‌کنند و چیدمان‌ها از الگوها ارث‌بری می‌کنند. چیدمان ولی و اسلاید اصلی در فیلد slideProperties اسلاید مشخص می‌شود.
صفحه می‌تواند ویژگی‌هایی مثل پس‌زمینه و طرح رنگ را از صفحه ولی به‌ارث ببرد. برای به‌ارث بردن یک ویژگی، صفحه فرزند به‌سادگی مقداری برای آن ویژگی در پیام PageProperties خود تنظیم نمی‌کند. با «لغو نکردن» مقدار تعریف‌شده توسط والد، صفحه مقدار موروثی را می‌پذیرد.
نمودار زیر اسلایدی را نشان می‌دهد که ویژگی‌ها را از چیدمانی به ارث می‌برد که از اسلاید اصلی به ارث می‌برد:
ویژگی‌های استفاده‌شده برای ارائه اسلاید ترکیبی از ویژگی‌هایی است که تعریف می‌کند و ویژگی‌هایی که به ارث می‌برد. در این مثال، مقادیر حل‌شده‌ای که برای ارائه «اسلاید ۱» استفاده شده است به شرح زیر است:
- PropertyA «قرمز» است.
- PropertyB «نارنجی» است.
وراثت ویژگی‌های شکل
شکل‌ها می‌توانند ویژگی‌هایی مانند پر کردن، طرح کلی، یا سایه را از شکل‌های دیگر به ارث ببرند. اگر فیلد
Shape.placeholder
شکل تنظیم شده باشد، آن شکل جای‌بان است. فیلد Shape.placeholder.parentObjectId جای‌بان فرزند
جای‌بان والد آن را شناسایی می‌کند. وقتی اسلاید جدیدی براساس یک چیدمان ایجاد می‌کنید، هر جای‌بانی که در آن چیدمان وجود دارد به‌عنوان شکل فرزند در اسلاید جدید ظاهر می‌شود.
به‌طور مشابه، جای‌بان‌ها در صفحه‌های اصلی می‌توانند به‌عنوان والد جای‌بان‌های چیدمان‌ها عمل کنند.
با تعریف این سلسله‌مراتب وراثت، صفحه فرزند با تنظیم نکردن آن مقدار در پیام ShapeProperties خود، ویژگی را به ارث می‌برد. با لغو نکردن مقدار تعریف‌شده توسط والد، شکل فرزند مقدار موروثی را می‌پذیرد.
نمودار زیر وراثت ویژگی‌ها را بین سه جای‌بان که در اسلاید، چیدمان، و الگو قرار دارند نشان می‌دهد:
ویژگی‌های مورداستفاده برای ارائه شکل جای‌بان ترکیبی از ویژگی‌هایی است که تعریف می‌کند و ویژگی‌هایی که به ارث می‌برد. در این مثال، مقادیر حل‌شده برای این شکل‌ها به‌صورت زیر است:
- Placeholder1: propertyA is rendered as "Yellow", propertyB as "Green".
- Placeholder2: propertyA به‌صورت «زرد» و propertyB به‌صورت «بنفش» ارائه شده است.
- Placeholder3: propertyA به‌صورت «زرد» و propertyB به‌صورت «بنفش» ارائه می‌شود.
شکل‌ها تنها نوع عنصر صفحه هستند که می‌توانند والد داشته باشند. انواع دیگر، مثل تصاویر، جدول‌ها، و نمودارها، نمی‌توانند جای‌بان باشند و نمی‌توانند والد داشته باشند.
«پنهان کردن» دارایی‌ها بااستفاده از PropertyState
شمارش
PropertyState
کنترل می‌کند که آیا از ویژگی شکل واقعاً برای پرداخت استفاده می‌شود یا نه،
یا اینکه از مقدار فقط برای ارث‌بری توسط شکل‌های فرزند استفاده می‌شود. هنگام ارائه شکل در صفحه آن، از ویژگی‌ای با وضعیت ویژگی NOT_RENDERED استفاده نخواهد شد، اما فرزندانی که وضعیت ویژگی متناظر RENDERED دارند همچنان می‌توانند این ویژگی را به‌ارث ببرند.
نمودار زیر وراثت ویژگی‌ها را بین سه جای‌بان که فیلد PropertyState را دستکاری می‌کنند نشان می‌دهد:
پرداخت ویژگی‌های شکل می‌تواند تحت‌تأثیر فیلد PropertyState قرار گیرد. در این مثال، مقادیر حل‌شده برای این شکل‌ها به‌صورت زیر است:
- Placeholder1: propertyA به‌صورت «قرمز» ارائه می‌شود.
- Placeholder2: propertyA is not rendered. اگر این ویژگی طرح کلی بود، Placeholder2 طرح کلی نداشت.
- Placeholder3: propertyA پرداز نمی‌شود.
یک مقدار احتمالی دیگر برای شمارش
PropertyState
وجود دارد: وضعیت ویژگی INHERIT به این معنی است که خود وضعیت ویژگی
به‌ارث رسیده است و باید از مقدار والد استفاده شود. شکل‌های بدون والد
نمی‌توانند وضعیت ویژگی INHERIT داشته باشند.