Memilih item dalam presentasi

Pilihan adalah apa pun yang saat ini dipilih di halaman presentasi yang terbuka, seperti rentang teks yang disoroti atau tabel. Panduan ini memberi tahu Anda cara mendapatkan dan menyetel pilihan dalam presentasi aktif menggunakan Apps Script.

Pilihan adalah snapshot dari apa yang ada saat skrip dimulai. Jika pengguna mengklik dan pilihan berubah saat skrip berjalan, perubahan tersebut tidak akan tercermin.

Pilihan dan jenis pilihan

Anda dapat membaca pilihan menggunakan class Selection. Class ini memiliki berbagai metode untuk mendapatkan objek yang dipilih berdasarkan jenis objek yang dipilih.

Enum SelectionType mewakili jenis objek yang dipilih tertentu. Misalnya, jika pengguna telah memilih beberapa teks dalam bentuk, jenis pilihan akan berupa TEXT. Dalam hal ini, Anda dapat mengambil rentang teks yang dipilih menggunakan metode selection.getTextRange().

Anda juga dapat mengambil objek yang berisi pilihan; melanjutkan contoh di atas, Anda dapat mengambil bentuk yang berisi teks yang dipilih menggunakan selection.getPageElementRange().getPageElements()[0]. Demikian pula, halaman yang berisi bentuk penutup adalah halaman aktif saat ini; untuk mengambil halaman tersebut, gunakan selection.getCurrentPage().

Membaca pilihan

Untuk membaca pilihan, gunakan metode Presentation.getSelection() seperti yang ditunjukkan dalam contoh berikut:

slides/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();

Membaca halaman saat ini

Untuk mengambil Page saat ini yang sedang dilihat pengguna, gunakan metode getSelection() dan getCurrentPage() seperti berikut:

slides/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

Perhatikan bahwa halaman saat ini dapat berupa salah satu jenis berikut:

Halaman saat ini dapat memiliki satu atau beberapa objek yang dipilih, dan SelectionType menentukan jenis pilihan.

Membaca pilihan berdasarkan jenis pilihan

Contoh berikut menunjukkan cara menggunakan jenis pilihan untuk membaca pilihan saat ini dengan cara yang sesuai dengan jenisnya.

slides/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;
}

Membaca pilihan teks

Anda dapat membaca pilihan teks menggunakan metode Selection.getTextRange(). Ada dua jenis pemilihan teks:

  • Pemilihan rentang: Jika bentuk berisi teks "Hello", dan "He" dipilih, rentang yang ditampilkan memiliki startIndex=0, dan endIndex=2.
  • Pemilihan kursor: Jika bentuk berisi teks "Hello", dan kursor berada setelah "H" ("H|ello"), rentang yang ditampilkan adalah rentang kosong dengan startIndex=1 dan endIndex=1.

Mengubah pilihan

Skrip dapat mengubah pilihan pengguna. Setiap perubahan pilihan yang dibuat skrip pada presentasi akan tercermin dalam operasi pilihan berikutnya selama durasi eksekusi skrip.

Perubahan pilihan ditampilkan di browser pengguna hanya setelah eksekusi skrip selesai, atau saat Presentation.saveAndClose() dipanggil.

Memilih halaman saat ini

Halaman dalam presentasi aktif dapat dipilih sebagai halaman saat ini dengan memanggil metode selectAsCurrentPage(). Metode ini menghapus elemen halaman, halaman, atau pilihan teks sebelumnya. Jadi, menggunakan metode ini di halaman saat ini memungkinkan Anda membatalkan pilihan saat ini di halaman. Contoh:

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

Memilih elemen halaman

Untuk memilih elemen halaman di halaman, gunakan metode PageElement.select(). Tindakan ini juga membatalkan pilihan elemen halaman yang sebelumnya dipilih.

Contoh:

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

Memilih beberapa elemen halaman

Untuk menambahkan elemen halaman tambahan ke pilihan, gunakan metode PageElement.select(false). Semua elemen halaman harus berada di halaman saat ini.

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

Mentransformasi pilihan

Pengeditan yang dilakukan skrip Anda dapat mengubah pilihan saat ini, sehingga pilihan yang dipilih berubah sebagai akibat dari pengeditan. Contoh:

  1. Misalnya, Anda telah memilih dua bentuk A dan B.
  2. Selanjutnya, skrip Anda akan menghapus bentuk A.
  3. Akibatnya, pilihan diubah terhadap hasil edit sehingga hanya bentuk B yang dipilih.

Contoh berikut menunjukkan cara transformasi pilihan dengan memanipulasi elemen halaman yang dipilih.

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

Memilih teks

Teks yang ada dalam bentuk atau dalam sel tabel dapat dipilih menggunakan metode TextRange.select(). Jika teks berada dalam bentuk, bentuk tersebut juga akan dipilih. Jika teks berada dalam sel tabel, sel tabel tersebut dan tabel yang melampirkannya akan dipilih.

Tindakan ini juga menetapkan halaman induk sebagai halaman saat ini.

Pilihan rentang dalam bentuk

Contoh berikut menunjukkan cara membuat pilihan rentang dalam teks yang terdapat dalam bentuk.

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

Pemilihan kursor dalam bentuk

Contoh berikut menunjukkan cara membuat pilihan kursor dalam teks yang terdapat dalam bentuk.

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

Pemilihan rentang dalam sel tabel

Contoh berikut menunjukkan cara membuat pilihan rentang dalam teks yang ada di sel tabel.

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

Pemilihan kursor di TableCell

Contoh berikut menunjukkan cara membuat pilihan kursor dalam teks yang ada di sel tabel.

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

Transformasi pilihan dengan pengeditan tekstual

Contoh berikut menunjukkan cara mengubah pilihan dengan mengedit teks yang dipilih.

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

Membatalkan pilihan

Tidak ada metode eksplisit untuk membatalkan pilihan teks atau elemen halaman. Namun, hasil ini dapat dicapai menggunakan metode Page.selectAsCurrentPage() atau pageElement.select().

Pilih halaman saat ini

Contoh berikut menunjukkan cara membatalkan pilihan saat ini di halaman dengan menetapkan halaman tersebut sebagai halaman saat ini.

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

Pilih elemen halaman

Contoh berikut menunjukkan cara membatalkan pilihan saat ini di halaman dengan memilih satu elemen halaman, sehingga menghapus semua item lain dari pilihan.

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