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 وارد می‌کند.

مستندات دقیق

get Element()

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

بازگشت

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

get Offset()

موقعیت نسبی این 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

get Surrounding Text()

یک عنصر Text مصنوعی ایجاد می‌کند که متن و قالب‌بندی Paragraph یا List Item را که شامل Position است، به طور مستقیم یا از طریق زنجیره‌ای از عناصر فرزند، نشان می‌دهد. برای تعیین انحراف Position در عنصر Text برگردانده شده، get Surrounding Text Offset() استفاده کنید.

بازگشت

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

مجوز

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

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

get Surrounding Text Offset()

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

بازگشت

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

مجوز

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

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

insert Bookmark()

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

بازگشت

Bookmark - نشانک جدید

مجوز

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

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

insert Inline Image(image)

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

پارامترها

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

بازگشت

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

مجوز

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

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

insert Text(text)

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

پارامترها

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

بازگشت

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

مجوز

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

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