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.');
}

الطُرق

الطريقةنوع القيمة التي يتم عرضهاوصف قصير
getElement()Elementتحصل على العنصر الذي يحتوي على هذا Position.
getOffset()Integerتحصل على الموقع النسبي لهذا العنصر Position داخل العنصر الذي يحتوي عليه.
getSurroundingText()Textتُنشئ هذه السمة عنصرًا Text اصطناعيًا يمثّل نص Paragraph أو ListItem وتنسيقه الذي يحتوي على Position، إما مباشرةً أو من خلال سلسلة من العناصر الثانوية.
getSurroundingTextOffset()Integerتحصل على الإزاحة لهذا Position ضمن عنصر Text الذي يعرضه getSurroundingText().
insertBookmark()Bookmarkلإنشاء Bookmark جديد وإدراجه في هذا Position
insertInlineImage(image)InlineImageتُنشئ هذه الدالة InlineImage جديدة وتُدرجها في هذا Position من ملف ข้อมูล الصورة المحدّد.
insertText(text)Textتُدرج هذه الدالة النص المحدّد في هذا Position.

مستندات تفصيلية

getElement()

تحصل على العنصر الذي يحتوي على هذا Position. سيكون هذا العنصر إما Text أو عنصر حاوية مثل Paragraph. في كلتا الحالتَين، يمكن تحديد القيمة المطلقة للموضع داخل العنصر باستخدام getOffset().

الإرجاع

Element: الحاوية أو عنصر Text الذي يقع فيه عنصر Position هذا

getOffset()

تحصل على الموقع النسبي لهذا العنصر Position داخل العنصر الذي يحتوي عليه. إذا كان العنصر هو عنصر Text، يكون المرجع هو عدد الأحرف قبل Position (أي فهرس الحرف بعد Position هذا). بالنسبة إلى أي عنصر آخر، يكون المرجع هو عدد العناصر الفرعية قبل 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()

تحصل على الإزاحة لهذا Position ضمن عنصر Text الذي يعرضه getSurroundingText(). الإزاحة هي عدد الأحرف قبل 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 من ملف ข้อมูล الصورة المحدّد.

المعلمات

الاسمالنوعالوصف
imageBlobSourceبيانات الصورة المطلوب إدراجها في هذا Position

الإرجاع

InlineImage: عنصر الصورة الجديد، أو null إذا كان العنصر الذي يقع فيه هذا العنصرPosition لا يسمح بإدراج الصور

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

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

insertText(text)

تُدرج هذه الدالة النص المحدّد في هذا Position. تُنشئ هذه الطريقة عنصرًا جديدًا من النوع Text ، حتى إذا تم إدراج السلسلة داخل عنصر Text حالي، وذلك لتسهيل تنسيق العنصر الجديد.

المعلمات

الاسمالنوعالوصف
textStringالسلسلة المطلوب إدراجها في هذا Position

الإرجاع

Text: عنصر النص الجديد، أو null إذا كان العنصر الذي يقع فيهPosition لا يسمح بإدراج نص

التفويض

تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:

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