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 من ملف ข้อมูล الصورة المحدّد.

المعلَمات

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

الإرجاع

InlineImage: عنصر الصورة الجديد، أو 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 لا يسمح بإدراج نص

التفويض

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

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