اختيار عناصر ضمن عرض تقديمي

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

التحديد هو كل ما يتم تحديده حاليًا في صفحة عرض تقديمي مفتوحة، مثل امتداد للنص المميز أو الجدول. يخبرك هذا الدليل بكيفية الحصول على المجموعة وتحديدها في عرض تقديمي نشط باستخدام "برمجة التطبيقات".

التحديد هو لقطة لما كان عليه عند بدء النص البرمجي. إذا نقر المستخدم، وتغير التحديد أثناء تشغيل النص البرمجي، فلن تنعكس هذه التغييرات.

الاختيارات ونوع التحديد

يمكنك قراءة الاختيار باستخدام صف الاختيار. تتضمن الفئة طرقًا متنوعة للحصول على الكائنات المحددة بناء على نوع الكائنات المحددة.

يمثل تعداد SelectionType النوع المحدد من الكائنات المحددة. على سبيل المثال، إذا اختار المستخدم نصًا في شكل معيّن، سيكون نوع الاختيار هو نص. في هذه الحالة، يمكنك استرداد نطاق النص المحدد باستخدام طريقة selection.getTextRange().

يمكنك أيضًا استرداد الكائن الذي يحتوي على التحديد، ومواصلة المثال أعلاه، يمكنك استرداد الشكل الذي يحتوي على النص المحدد باستخدام selection.getPageElementRange().getPageElements()[0]. وبالمثل، فإن الصفحة التي تحتوي على شكل التضمين هي الصفحة النشطة الحالية، ولاسترداد هذه الصفحة، استخدم selection.getCurrentPage().

قراءة التحديد

لقراءة التحديد، استخدم طريقة present.getSelection() كما هو موضح في المثال التالي:

الشرائح/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();

قراءة الصفحة الحالية

لاسترداد الصفحة الحالية التي يعرضها المستخدم، استخدم طريقتي getSelection() وgetCurrentPage() على النحو التالي:

الشرائح/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

لاحظ أن الصفحة الحالية قد تكون أيًا من الأنواع التالية:

يمكن أن تتضمن الصفحة الحالية كائنًا واحدًا أو أكثر من العناصر المحددة، ويحدد TypeType نوع التحديد.

قراءة التحديد استنادًا إلى نوع الاختيار

يوضح المثال التالي كيفية استخدام نوع التحديد لقراءة التحديد الحالي بطريقة مناسبة للنوع.

الشرائح/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();
const selectionType = selection.getSelectionType();
let currentPage;
switch (selectionType) {
  case SlidesApp.SelectionType.NONE:
    console.log('Nothing selected');
    break;
  case SlidesApp.SelectionType.CURRENT_PAGE:
    currentPage = selection.getCurrentPage();
    console.log('Selection is a page with ID: ' + currentPage.getObjectId());
    break;
  case SlidesApp.SelectionType.PAGE_ELEMENT:
    const pageElements = selection.getPageElementRange().getPageElements();
    console.log('There are ' + pageElements.length + ' page elements selected.');
    break;
  case SlidesApp.SelectionType.TEXT:
    const tableCellRange = selection.getTableCellRange();
    if (tableCellRange !== null) {
      const tableCell = tableCellRange.getTableCells()[0];
      console.log('Selected text is in a table at row ' +
        tableCell.getRowIndex() + ', column ' +
        tableCell.getColumnIndex());
    }
    const textRange = selection.getTextRange();
    if (textRange.getStartIndex() === textRange.getEndIndex()) {
      console.log('Text cursor position: ' + textRange.getStartIndex());
    } else {
      console.log('Selection is a text range from: ' + textRange.getStartIndex() + ' to: ' +
        textRange.getEndIndex() + ' is selected');
    }
    break;
  case SlidesApp.SelectionType.TABLE_CELL:
    const tableCells = selection.getTableCellRange().getTableCells();
    const table = tableCells[0].getParentTable();
    console.log('There are ' + tableCells.length + ' table cells selected.');
    break;
  case SlidesApp.SelectionType.PAGE:
    const pages = selection.getPageRange().getPages();
    console.log('There are ' + pages.length + ' pages selected.');
    break;
  default:
    break;
}

قراءة تحديدات النص

يمكنك قراءة النص المحدد باستخدام طريقة Selection.getTextRange(). هناك نوعان من تحديد النص:

  • تحديد النطاق: إذا كان أحد الأشكال يحتوي على النص "مرحبًا"، وتم تحديد "هو"، يكون للنطاق الذي يتم عرضه startIndex=0 وendIndex=2.
  • اختيار المؤشر: إذا كان أحد الأشكال يحتوي على النص "مرحبًا"، وكان المؤشر بعد "H" ("H|ello")، يكون النطاق المعروض نطاقًا فارغًا مع startIndex=1 وendIndex=1.

تعديل التحديد

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

لا تنعكس تغييرات التحديد على متصفح المستخدم إلا بعد اكتمال تنفيذ النص البرمجي، أو عند استدعاء Presentation.saveAndClose().

اختيار الصفحة الحالية

يمكن تحديد صفحة في العرض التقديمي النشط كالصفحة الحالية من خلال استدعاء الطريقة selectAsCurrentPage(). تؤدي هذه الطريقة إلى إزالة تحديد أي عنصر صفحة أو نص أو صفحة سابقة. لذا يتيح لك استخدام هذه الطريقة في الصفحة الحالية إلغاء تحديد أي تحديدات حالية في الصفحة. مثلاً:

الشرائح/selection/selection.gs
// Select the first slide as the current page selection and remove any previous selection.
  const selection = SlidesApp.getActivePresentation().getSelection();
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.selectAsCurrentPage();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.CURRENT_PAGE
// selection.getCurrentPage() = slide
//

اختيار عنصر صفحة

لاختيار عنصر صفحة في إحدى الصفحات، استخدم طريقة PageElement.select(). يؤدي هذا أيضًا إلى إلغاء تحديد أي من عناصر الصفحة المحددة مسبقًا.

مثلاً:

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const pageElement = slide.getPageElements()[0];
  // Only select this page element and remove any previous selection.
  pageElement.select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = pageElement
//

تحديد عناصر متعددة للصفحة

لإضافة عناصر صفحة إضافية إلى التحديد، استخدِم طريقة PageElement.select(false). يجب أن تكون جميع عناصر الصفحة في الصفحة الحالية.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // First select the slide page, as the current page selection.
  slide.selectAsCurrentPage();
  // Then select all the page elements in the selected slide page.
  const pageElements = slide.getPageElements();
  for (let i = 0; i < pageElements.length; i++) {
    pageElements[i].select(false);
  }
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = pageElements
//

تغيير الاختيارات

يمكن أن تؤدي التعديلات التي ينفذها النص البرمجي إلى تحويل التحديد الحالي، بحيث يتغير ما يتم تحديده نتيجة التعديل. مثلاً:

  1. لنفترض أنه تم تحديد شكلين (أ) و(ب).
  2. بعد ذلك، يزيل النص البرمجي الشكل (أ).
  3. نتيجة لذلك، يتم تحويل التحديد مقابل التعديل بحيث يتم تحديد الشكل ب فقط.

يوضح المثال التالي كيف يمكن تحويل التحديد عن طريق معالجة عناصر الصفحة المحددة.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape1 = slide.getPageElements()[0].asShape();
  const shape2 = slide.getPageElements()[1].asShape();
  // Select both the shapes.
  shape1.select();
  shape2.select(false);
  // State of selection
  //
  // selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
  // selection.getCurrentPage() = slide
  // selection.getPageElementRange().getPageElements() = [shape1, shape2]
  //
  // Remove one shape.
  shape2.remove();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = [shape1]
//

تحديد نص

يمكن تحديد النص الموجود في شكل أو في خلية جدول باستخدام طريقة TextRange.select(). إذا كان النص مضمنًا في شكل، يتم تحديد ذلك الشكل أيضًا. إذا كان النص مضمّنًا في خلية جدول، سيتم عندئذٍ تحديد خلية الجدول هذه وجدول التضمين لها.

يؤدي هذا أيضًا إلى تعيين الصفحة الرئيسية كالصفحة الحالية.

تحديد النطاق في شكل

يوضح المثال التالي كيفية تحديد نطاق ضمن نص مضمن في شكل.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  shape.getText().setText('Hello');
  // Range selection: Select the text range 'He'.
  shape.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

اختيار المؤشر في شكل

يوضح المثال التالي كيفية إجراء تحديد المؤشر داخل النص الموجود في شكل.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  shape.getText().setText('Hello');
  // Cursor selection: Place the cursor after 'H' like 'H|ello'.
  shape.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

تحديد النطاق في خلية جدول

يوضح المثال التالي كيفية تحديد نطاق داخل النص الموجود في خلية الجدول.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const table = slide.getPageElements()[0].asTable();
  const tableCell = table.getCell(0, 1);
  tableCell.getText().setText('Hello');
  // Range selection: Select the text range 'He'.
  tableCell.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

تحديد المؤشر في TableCell

يوضح المثال التالي كيفية إجراء تحديد المؤشر داخل النص الموجود في خلية الجدول.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const table = slide.getPageElements()[0].asTable();
  const tableCell = table.getCell(0, 1);
  tableCell.getText().setText('Hello');
  // Cursor selection: Place the cursor after 'H' like 'H|ello'.
  tableCell.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

تحويل التحديد باستخدام التعديلات النصية

يوضح المثال التالي كيف يمكن تحويل التحديد عن طريق تعديل النص المحدد.

الشرائح/selection/selection.gs
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  const textRange = shape.getText();
  textRange.setText('World');
  // Select all the text 'World'.
  textRange.select();
  // State of selection
  //
  // selection.getSelectionType() = SlidesApp.SelectionType.TEXT
  // selection.getCurrentPage() = slide
  // selection.getPageElementRange().getPageElements()[0] = shape
  // selection.getTextRange().getStartIndex() = 0
  // selection.getTextRange().getEndIndex() = 6
  //
  // Add some text to the shape, and the selection will be transformed.
  textRange.insertText(0, 'Hello ');

// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 12
//

جارٍ إلغاء الاختيار

ليست هناك طرق صريحة لإلغاء تحديد عناصر النص أو الصفحة. ويمكن تحقيق هذه النتيجة باستخدام طريقتَي Page.selectAsCurrentPage() أو pageElement.select().

اختيار صفحة حالية

يوضح المثال التالي كيفية إلغاء تحديد أي تحديدات حالية في الصفحة عن طريق تعيين هذه الصفحة كالصفحة الحالية.

الشرائح/selection/selection.gs
// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected, setting the
// same (or any other) slide page as the current page would do the unselect.
//
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.selectAsCurrentPage();

اختيار عنصر صفحة

يوضح المثال التالي كيفية إلغاء تحديد أي تحديدات حالية في الصفحة بتحديد عنصر صفحة واحد، وبالتالي إزالة جميع العناصر الأخرى من التحديد.

الشرائح/selection/selection.gs
// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected,
// selecting any pageElement in the first slide (or any other pageElement) would
// do the unselect and select that pageElement.
//
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.getPageElements()[0].select();