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|nullتُنشئ هذه الدالة InlineImage جديدًا وتُدرجه في Position الحالي من الصورة المحدّدة blob.
insertText(text)Text|nullيُدرج النص المحدّد في هذا الموضع 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 الحالي من الصورة المحدّدة blob.

المعلمات

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

الإرجاع

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

التفويض

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

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

insertText(text)

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

المعلمات

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

الإرجاع

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

التفويض

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

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