برای استفاده مؤثر از 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
است که یک رشته متنی به هم پیوسته را با تمام سبک متن یکسان نشان می دهد. یک پاراگراف میتواند شامل چندین اجرای متن باشد، اما اجراهای متنی هرگز از مرزهای پاراگراف عبور نمیکنند. محتویات پس از یک کاراکتر خط جدید تقسیم می شوند تا متن جداگانه ای را تشکیل دهند. به عنوان مثال، یک سند کوچک مانند زیر را در نظر بگیرید:
![سند کوچک با پاراگراف ها و لیست گلوله ای.](https://developers.google.com/static/docs/api/images/simpledoc.png?hl=fa)
نمودار زیر نشان می دهد که چگونه می توانید دنباله پاراگراف ها را در سند قبلی تجسم کنید، هر کدام با تنظیمات 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
زیرین را لغو میکند. برعکس، هر ویژگی قالببندی که تنظیم نکردهاید، همچنان از سبک پاراگراف به ارث میرسد.