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

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

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

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

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

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

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

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

لقراءة الاختيار، استخدِم الإجراء Presentation.getSelection() كما هو موضّح في المثال التالي:

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

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

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

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

تجدر الإشارة إلى أنّ الصفحة الحالية قد تكون من بين الأنواع التالية:

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

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

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

الشرائح/sselect/sselect.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(). هناك نوعان من تحديد النص:

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

تعديل الاختيار

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

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

تحديد الصفحة الحالية

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

الشرائح/sselect/sselect.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(). يؤدي هذا الإجراء أيضًا إلى إلغاء اختيار أي عناصر صفحة تم اختيارها سابقًا.

مثال:

الشرائح/sselect/sselect.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). يجب أن تكون جميع عناصر الصفحة في الصفحة الحالية.

الشرائح/sselect/sselect.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. لنفترض أنك اخترت شكلين A وB.
  2. بعد ذلك، يزيل النص البرمجي الشكل A.
  3. ونتيجةً لذلك، يتم تحويل التحديد مقابل التعديل بحيث يتم تحديد الشكل ب فقط.

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

الشرائح/sselect/sselect.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(). إذا كان النص مضمَّنًا في شكل، يتم تحديد هذا الشكل أيضًا. إذا كان النص موجودًا في خلية جدول، فسيتم تحديد كل من خلية الجدول وجدولها المضمّن.

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

اختيار النطاق في شكل

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

الشرائح/sselect/sselect.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
//

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

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

الشرائح/sselect/sselect.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
//

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

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

الشرائح/sselect/sselect.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

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

الشرائح/sselect/sselect.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
//

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

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

الشرائح/sselect/sselect.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().

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

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

الشرائح/sselect/sselect.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();

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

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

الشرائح/sselect/sselect.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();