برای استفاده مؤثر از Google Docs API، باید معماری سند Google Docs و عناصر تشکیل دهنده یک سند و همچنین رابطه بین آنها را درک کنید. این صفحه یک نمای کلی از این موضوعات ارائه می دهد:
- مدل مفهومی عناصر سند
- چگونه Docs API این عناصر را نشان می دهد
- ویژگی های ظاهری عناصر
عناصر سطح بالا
بیرونی ترین عنصر ظرف در Google Docs یک سند است. این واحدی است که می تواند در Google Drive ذخیره شود، با سایر کاربران به اشتراک گذاشته شود و با متن و تصاویر به روز شود.
عناصر سطح بالای یک منبع documents شامل Tab s، SuggestionsViewMode و سایر ویژگی‌های آن است:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
زبانه ها
یک سند واحد می‌تواند حاوی چندین برگه باشد که دارای محتوای متفاوت در سطح متن هستند. ویژگی tabs سند، دنباله ای از اشیاء 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 مبتنی بر صفر هستند. اینها نشان دهنده انحراف شروع و پایان یک عنصر، نسبت به ابتدای بخش محصور آن است. برای اطلاعات بیشتر درباره نحوه سفارش تماس‌های دسته‌ای Docs API، به به‌روزرسانی‌های دسته‌ای را ببینید.
شاخص ها در واحد کد UTF-16 اندازه گیری می شوند. این بدان معناست که جفت های جایگزین دو شاخص مصرف می کنند. به عنوان مثال، ایموجی "GRINNING FACE"، 😄، به صورت \uD83D\uDE00 نشان داده می شود و دو شاخص مصرف می کند.
برای عناصر درون یک بدنه سند، ایندکس ها از ابتدای محتوای بدنه، که عنصر "ریشه" است، فاصله ها را نشان می دهند.
انواع «شخصی‌سازی» برای عناصر ساختاری - SectionBreak ، TableOfContents ، Table ، و Paragraph - این شاخص‌ها را ندارند زیرا StructuralElement محصور آنها دارای این فیلدها است. این موضوع در مورد انواع شخصی‌سازی موجود در یک ParagraphElement مانند TextRun ، AutoText و PageBreak نیز صادق است.
دسترسی به عناصر
بسیاری از عناصر با روش documents.batchUpdate قابل تغییر هستند. به عنوان مثال، با استفاده از InsertTextRequest ، می توانید محتوای هر عنصر حاوی متن را تغییر دهید. به طور مشابه، می‌توانید از UpdateTextStyleRequest برای اعمال قالب‌بندی در محدوده‌ای از متن موجود در یک یا چند عنصر استفاده کنید.
برای خواندن عناصر سند، از روش documents.get استفاده کنید تا یک فایل JSON از سند کامل به دست آورید. سپس می توانید JSON حاصل را برای یافتن مقادیر عناصر جداگانه تجزیه کنید. برای اطلاعات بیشتر، محتویات سند خروجی را به صورت JSON ببینید.
تجزیه محتوا می تواند برای موارد استفاده مختلف مفید باشد. به عنوان مثال، سندی را در نظر بگیرید که فهرستی از اسنادی را که برنامه پیدا می کند فهرست بندی می کند. این برنامه می‌تواند عنوان، شناسه بازبینی و شماره صفحه شروع برگه‌های یک سند را استخراج کند، همانطور که در نمودار زیر نشان داده شده است:
از آنجایی که هیچ روشی برای خواندن صریح این تنظیمات وجود ندارد، برنامه شما باید کل سند را دریافت کند و سپس JSON را برای استخراج این مقادیر تجزیه کند.
وراثت اموال
یک StructuralElement می تواند خواص را از اشیاء والد خود به ارث ببرد. ویژگی‌های یک شی، از جمله ویژگی‌هایی که تعریف می‌کند و آن‌هایی که به ارث می‌برد، ظاهر بصری نهایی آن را تعیین می‌کنند.
قالب بندی کاراکترهای متن نحوه نمایش متن را در یک سند، مانند پررنگ، مورب و زیرخط تعیین می کند. قالب‌بندی که اعمال می‌کنید، قالب‌بندی پیش‌فرض به ارث رسیده از TextStyle پاراگراف زیرین را لغو می‌کند. برعکس، هر کاراکتری که قالب بندی آنها را تنظیم نکرده اید همچنان از سبک های پاراگراف به ارث می رسد.
قالب بندی پاراگراف تعیین می کند که چگونه بلوک های متن در یک سند ارائه می شوند، مانند تراز، حاشیه و تورفتگی. قالب‌بندی که اعمال می‌کنید، قالب‌بندی پیش‌فرض به ارث رسیده از ParagraphStyle زیرین را لغو می‌کند. برعکس، هر ویژگی قالب‌بندی که تنظیم نکرده‌اید، همچنان از سبک پاراگراف به ارث می‌رسد.