برای استفاده مؤثر از API گوگل داکس، باید معماری یک سند گوگل داکس و عناصر تشکیلدهنده یک سند و همچنین رابطه بین آنها را درک کنید. این صفحه مروری دقیق بر این مباحث ارائه میدهد:
- یک مدل مفهومی از عناصر سند
- نحوه نمایش این عناصر توسط API اسناد
- ویژگیهای استایلدهی عناصر
عناصر سطح بالا
بیرونیترین عنصر کانتینر در گوگل داکس، یک سند است. این واحدی است که میتواند در گوگل درایو ذخیره شود، با سایر کاربران به اشتراک گذاشته شود و با متن و تصاویر بهروزرسانی شود.
عناصر سطح بالای یک منبع documents شامل Tab ها، SuggestionsViewMode و سایر ویژگیها میشوند:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
تبها
یک سند واحد میتواند شامل چندین تب باشد که محتوای سطح متنی متفاوتی دارند. ویژگی tabs از document دنباله ای از اشیاء Tab است. یک Tab از فیلدهای زیر تشکیل شده است:
-
TabProperties: شامل ویژگیهای یک تب مانند شناسه، عنوان و فهرست است. -
childTabs: تبهای فرزند یک تب (تبهایی که مستقیماً زیر آن قرار گرفتهاند) را نمایش میدهد. -
DocumentTab: محتوای متنی یک تب را نشان میدهد.
بخشهای بعدی، مروری مختصر بر سلسله مراتب تبهای سند ارائه میدهند؛ نمایش Tab JSON نیز اطلاعات دقیقتری ارائه میدهد. برای اطلاعات بیشتر در مورد ویژگی تبها، به بخش «کار با تبها» مراجعه کنید.
برای دستکاری ویژگیهای تب سند سراسری خارج از محتوای Body ، تقریباً همیشه بهتر است از یک یا چند الگوی سند استفاده کنید که میتوانید از آنها به عنوان مبنایی برای تولید اسناد جدید به صورت برنامهنویسی شده استفاده کنید. برای اطلاعات بیشتر، به ادغام متن در یک سند مراجعه کنید.
محتوای بدنه
Body معمولاً شامل کل محتوای تب یک سند است. اکثر مواردی که میتوانید یا احتمالاً میخواهید به صورت برنامهنویسی از آنها استفاده کنید، عناصری در محتوای Body هستند:
عنصر سازهای
یک StructuralElement محتوایی را توصیف میکند که به سند ساختار میدهد. محتوای Body دنباله ای از اشیاء StructuralElement است. یک عنصر محتوا، هر شیء StructuralElement را شخصی سازی میکند، همانطور که در نمودار زیر نشان داده شده است:
عناصر ساختاری و اشیاء محتوایی آنها شامل تمام اجزای بصری درون سند هستند. این شامل متن، تصاویر درون خطی و قالببندی میشود.
ساختار پاراگراف
یک Paragraph یک StructuralElement است که یک پاراگراف را نشان میدهد. این عنصر دارای طیفی از محتوا است که با یک کاراکتر خط جدید خاتمه مییابد. این عنصر از اشیاء زیر تشکیل شده است:
-
ParagraphElement: محتوای درون یک پاراگراف را توصیف میکند. -
ParagraphStyle: یک عنصر اختیاری که به طور صریح ویژگیهای سبک را برای پاراگراف تنظیم میکند. -
Bullet: اگر پاراگراف بخشی از یک لیست باشد، یک عنصر اختیاری که مشخصات بولت را ارائه میدهد.
ParagraphElement چیزی شبیه به یک StructuralElement عمل میکند. مجموعهای از انواع عناصر محتوا (مانند ColumnBreak و Equation ) ParagraphElement مخصوص به خود را شخصیسازی میکنند، همانطور که در نمودار زیر نشان داده شده است:
برای مثالی از ساختار کامل سند، به مثال سند در قالب JSON مراجعه کنید. در خروجی میتوانید بسیاری از عناصر کلیدی ساختاری و محتوایی، و همچنین نحوه استفاده از اندیسهای شروع و پایان را همانطور که در بخش بعدی توضیح داده شده است، مشاهده کنید.
متن اجرا میشود
یک TextRun یک ParagraphElement است که رشتهای پیوسته از متن را با سبک متنی یکسان نشان میدهد. یک پاراگراف میتواند شامل چندین اجرای متن باشد، اما اجرای متن هرگز از مرزهای پاراگراف عبور نمیکند. محتوا پس از یک کاراکتر خط جدید تقسیم میشود تا اجراهای متنی جداگانهای را تشکیل دهد. به عنوان مثال، یک سند کوچک مانند زیر را در نظر بگیرید:
نمودار زیر نشان میدهد که چگونه میتوانید توالی پاراگرافها را در سند قبلی تجسم کنید، که هر کدام تنظیمات TextRun و Bullet اختیاری خود را دارند.
متن خودکار
AutoText یک ParagraphElement است که نشاندهندهی نقطهای در متن است که به صورت پویا با محتوایی که میتواند در طول زمان تغییر کند، جایگزین میشود. در اسناد (Docs)، از این برای شمارهگذاری صفحات استفاده میشود.
شاخصهای شروع و پایان
وقتی محتوای تب یک سند را بهروزرسانی میکنید، هر بهروزرسانی در یک مکان یا در یک محدوده درون سند انجام میشود. این مکانها و محدودهها با استفاده از اندیسها مشخص میشوند که نشاندهندهی یک فاصله در داخل یک بخش سند حاوی سند هستند. یک بخش، بدنه، سربرگ، پاورقی یا پاورقی حاوی عناصر ساختاری یا محتوایی است. اندیسهای عناصر درون یک بخش نسبت به ابتدای آن بخش هستند.
بیشتر عناصر درون محتوای بدنه، ویژگیهای startIndex و endIndex مبتنی بر صفر دارند. این ویژگیها نشاندهندهی فاصلهی شروع و پایان یک عنصر نسبت به ابتدای بخش دربرگیرندهی آن هستند. برای اطلاعات بیشتر در مورد نحوهی مرتبسازی فراخوانیهای API دستهای Docs، به بهروزرسانیهای دستهای مراجعه کنید.
شاخصها با واحدهای کد UTF-16 اندازهگیری میشوند. این یعنی جفتهای جایگزین دو شاخص مصرف میکنند. برای مثال، ایموجی "چهره خندان" 😄 به صورت \uD83D\uDE00 نمایش داده میشود و دو شاخص مصرف میکند.
برای عناصر درون بدنه سند، اندیسها نشاندهنده فاصله از ابتدای محتوای بدنه هستند که همان عنصر "ریشه" است.
انواع «شخصیسازی» برای عناصر ساختاری - SectionBreak ، TableOfContents ، Table و Paragraph - این اندیسها را ندارند زیرا StructuralElement دربرگیرنده آنها دارای این فیلدها است. این موضوع در مورد انواع شخصیسازی موجود در ParagraphElement مانند TextRun ، AutoText و PageBreak نیز صادق است.
عناصر دسترسی
بسیاری از عناصر با متد documents.batchUpdate قابل تغییر هستند. برای مثال، با استفاده از InsertTextRequest میتوانید محتوای هر عنصری که حاوی متن است را تغییر دهید. به طور مشابه، میتوانید از UpdateTextStyleRequest برای اعمال قالببندی به طیفی از متن که در یک یا چند عنصر قرار دارد، استفاده کنید.
برای خواندن عناصر سند، از متد documents.get برای دریافت یک نسخه JSON از کل سند استفاده کنید. سپس میتوانید JSON حاصل را برای یافتن مقادیر عناصر منفرد تجزیه کنید. برای اطلاعات بیشتر، به بخش «محتواهای سند خروجی به صورت JSON» مراجعه کنید.
تجزیه محتوا میتواند برای موارد استفاده مختلفی مفید باشد. برای مثال، یک برنامه فهرستبندی اسناد را در نظر بگیرید که اسنادی را که پیدا میکند فهرست میکند. این برنامه میتواند عنوان، شناسه ویرایش و شماره صفحه شروع تبهای یک سند را استخراج کند، همانطور که در نمودار زیر نشان داده شده است:
از آنجایی که هیچ روشی برای خواندن صریح این تنظیمات وجود ندارد، برنامه شما باید کل سند را دریافت کرده و سپس JSON را برای استخراج این مقادیر تجزیه کند.
ارث اموال
یک StructuralElement میتواند ویژگیهایی را از اشیاء والد خود به ارث ببرد. ویژگیهای یک شیء، شامل آنهایی که تعریف میکند و آنهایی که به ارث میبرد، ظاهر بصری نهایی آن را تعیین میکنند.
قالببندی کاراکترهای متن، نحوهی نمایش متن در یک سند، مانند پررنگ، کج و زیرخطدار را تعیین میکند. قالببندیای که شما اعمال میکنید، قالببندی پیشفرض به ارث رسیده از TextStyle پاراگراف زیرین را لغو میکند. برعکس، هر کاراکتری که قالببندی آن را تنظیم نکردهاید، همچنان از سبکهای پاراگراف به ارث میبرد.
قالببندی پاراگراف، نحوه نمایش بلوکهای متن در یک سند، مانند ترازبندی، حاشیهها و تورفتگی را تعیین میکند. قالببندیای که شما اعمال میکنید، قالببندی پیشفرض به ارث رسیده از ParagraphStyle زیرین را لغو میکند. برعکس، هر ویژگی قالببندی که شما تنظیم نکردهاید، همچنان از سبک پاراگراف به ارث میرسد.