Class Position

موقعیت

ارجاعی به مکانی در تب سند، نسبت به یک عنصر خاص. مکان‌نمای کاربر به صورت Position نمایش داده می‌شود، در کنار کاربردهای دیگر. اسکریپت‌ها فقط می‌توانند به مکان‌نمای کاربری که اسکریپت را اجرا می‌کند دسترسی داشته باشند، و فقط در صورتی که اسکریپت به سند متصل باشد.

// Insert some text at the cursor position and make it bold.
const cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns
  // null, the cursor's containing element doesn't allow insertions, so show the
  // user an error message.
  const element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}

روش‌ها

روش نوع بازگشتی شرح مختصر
get Element() Element عنصری را که شامل این Position است، برمی‌گرداند.
get Offset() Integer مکان نسبی این Position را درون عنصری که شامل آن است، برمی‌گرداند.
get Surrounding Text() Text یک عنصر Text مصنوعی ایجاد می‌کند که متن و قالب‌بندی Paragraph یا List Item را که شامل Position است، به طور مستقیم یا از طریق زنجیره‌ای از عناصر فرزند، نشان می‌دهد.
get Surrounding Text Offset() Integer مقدار انحراف این Position (Position) را درون عنصر Text ) که توسط get Surrounding Text() برگردانده می‌شود، برمی‌گرداند.
insert Bookmark() Bookmark یک Bookmark جدید ایجاد و در این Position درج می‌کند.
insert Inline Image(image) Inline Image |null یک Inline Image جدید را در این Position از حباب تصویر مشخص‌شده ایجاد و درج می‌کند.
insert Text(text) Text |null متن مشخص شده را در این Position وارد می‌کند.

مستندات دقیق

getElement()

عنصری را که شامل این Position است، برمی‌گرداند. این می‌تواند یک عنصر Text یا یک عنصر نگهدارنده مانند Paragraph باشد. در هر صورت، موقعیت نسبی درون عنصر را می‌توان با getOffset() تعیین کرد.

بازگشت

Element - ظرف یا عنصر Text که این شیء Position در آن قرار دارد

getOffset()

موقعیت نسبی این Position را در عنصری که آن را در بر می‌گیرد، دریافت می‌کند. اگر عنصر یک عنصر Text باشد، offset تعداد کاراکترهای قبل از Position است (یعنی، شاخص کاراکتر بعد از این Position )؛ برای هر عنصر دیگر، offset تعداد عناصر فرزند قبل از این Position در همان عنصر نگهدارنده است (یعنی، شاخص عنصر فرزند بعد از Position ).

بازگشت

Integer - برای عناصر Text ، تعداد کاراکترهای قبل از این Position ؛ برای سایر عناصر، تعداد عناصر فرزند قبل از این Position در همان عنصر نگهدارنده

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getSurroundingText()

یک عنصر Text مصنوعی ایجاد می‌کند که متن و قالب‌بندی Paragraph یا ListItem که شامل Position است را نشان می‌دهد، چه مستقیماً و چه از طریق زنجیره‌ای از عناصر فرزند. برای تعیین انحراف Position در عنصر Text برگردانده شده، getSurroundingTextOffset() استفاده کنید.

بازگشت

Text - عنصری معادل با نتیجه فراخوانی editAsText() روی Paragraph یا ListItem که شامل Position است، چه مستقیماً و چه از طریق زنجیره‌ای از عناصر فرزند.

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

getSurroundingTextOffset()

مقدار offset این Position را درون عنصر Text که توسط getSurroundingText() برگردانده شده است، برمی‌گرداند. offset تعداد کاراکترهای قبل از Position (یعنی اندیس کاراکتر بعد از این Position ) است.

بازگشت

Integer - تعداد کاراکترهای قبل از این Position در Paragraph یا ListItem که شامل Position است، چه مستقیماً و چه از طریق زنجیره‌ای از عناصر فرزند

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertBookmark()

یک Bookmark جدید ایجاد و در این Position درج می‌کند.

بازگشت

Bookmark - نشانک جدید

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertInlineImage(image)

یک InlineImage جدید را در این Position از حباب تصویر مشخص شده ایجاد و درج می‌کند.

پارامترها

نام نوع توضیحات
image Blob Source داده‌های تصویر برای درج در این Position

بازگشت

InlineImage |null — عنصر تصویر جدید، یا null اگر عنصری که این Position در آن قرار دارد اجازه درج تصاویر را نمی‌دهد.

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents

insertText(text)

متن مشخص شده را در این Position وارد می‌کند. این متد یک عنصر Text جدید ایجاد می‌کند، حتی اگر رشته درون یک عنصر Text موجود وارد شده باشد، به طوری که استایل‌دهی به عنصر جدید آسان باشد.

پارامترها

نام نوع توضیحات
text String رشته‌ای که باید در این Position وارد شود

بازگشت

Text |null — عنصر متن جدید، یا اگر عنصری که این Position در آن قرار دارد اجازه درج متن را نمی‌دهد، null

مجوز

اسکریپت‌هایی که از این روش استفاده می‌کنند، نیاز به مجوز با یک یا چند مورد از حوزه‌های زیر دارند:

  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/documents