Class Position

الموضع

مرجع إلى موقع جغرافي في المستند، مقارنةً بعنصر معيّن. ويتم تمثيل مؤشر المستخدم على أنّه Position، من بين استخدامات أخرى. لا يمكن للنصوص البرمجية الوصول إلا إلى مؤشر المستخدم الذي يشغِّل النص البرمجي، وفقط إذا تم ربط النص البرمجي بالمستند.

// Insert some text at the cursor position and make it bold.
var 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.
  var 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 هذه من الصورة المكثّفة المحدّدة.

المَعلمات

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

استرجاع الكرة

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

التفويض

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

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

insertText(text)

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

المَعلمات

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

استرجاع الكرة

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

التفويض

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

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