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

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

لا يمكن للبرنامج النصي الوصول إلا إلى مجموعة المستخدم الذي يشغِّل البرنامج النصي.

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

المجموعات ونوع المجموعة

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

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

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

قراءة المجموعة

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

slides/selection/selection.gs

عرض على GitHub

const selection = SlidesApp.getActivePresentation().getSelection();

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

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

slides/selection/selection.gs

عرض على GitHub

const currentPage = SlidesApp.getActivePresentation()
  .getSelection()
  .getCurrentPage();

يُرجى العِلم أنّ الصفحة الحالية يمكن أن تكون أيًا من الأنواع التالية:

• شريحة
• شريحة رئيسية
• تنسيق

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

قراءة المجموعة استنادًا إلى نوع المجموعة

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

slides/selection/selection.gs

عرض على GitHub

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.
• تحديد المؤشر: إذا كان الشكل يحتوي على النص "Hello" وكان المؤشر بعد "H" ("H|ello")، فسيكون النطاق الذي يتم عرضه نطاقًا فارغًا مع startIndex=1 وendIndex=1.

تعديل المجموعة

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

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

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

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

slides/selection/selection.gs

عرض على GitHub

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

تتطابق الطريقتان select() وselect(true)‎.

على سبيل المثال:

slides/selection/selection.gs

عرض على GitHub

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

slides/selection/selection.gs

عرض على GitHub

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. نتيجةً لذلك، يتم تغيير المجموعة استنادًا إلى التعديل بحيث يتم اختيار الشكل B فقط.

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

slides/selection/selection.gs

عرض على GitHub

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

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

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

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

slides/selection/selection.gs

عرض على GitHub

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
//

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

يوضّح المثال التالي كيفية اختيار المؤشر ضمن نص مضمّن في شكل.

slides/selection/selection.gs

عرض على GitHub

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
//

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

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

slides/selection/selection.gs

عرض على GitHub

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

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

slides/selection/selection.gs

عرض على GitHub

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
//

تغيير المجموعة من خلال التعديلات النصية

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

slides/selection/selection.gs

عرض على GitHub

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()‎.

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

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

slides/selection/selection.gs

عرض على GitHub

// 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();

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

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

slides/selection/selection.gs

عرض على GitHub

// 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();