元素運算

Google 簡報 API 可讓您建立及編輯 PageElement 資源,包括文字方塊、圖片、表格、基本形狀、線條和內嵌影片。本頁範例將示範使用 presentations.batchUpdate 方法的一些常見的網頁元素作業。

這些範例使用下列變數:

  • PRESENTATION_ID:指出您提供呈現 ID 的位置。您可以從顯示網址擷取這個 ID 的值。
  • PAGE_ID:指出您在何處提供頁面物件 ID。您可以從網址或使用 API 讀取要求擷取這個值。
  • PAGE_ELEMENT_ID:指出您在何處提供網頁元素物件 ID。您可以為自己建立的元素 (設有部分限制) 指定此 ID,或讓 Slide API 自動建立。您可以透過 API 讀取要求擷取元素 ID。

以下範例是以 HTTP 要求為不受語言限制。如要瞭解如何使用 Google API 用戶端程式庫,以不同語言實作批次更新,請參閱下列指南:

在文字方塊中新增項目符號清單

以下 presentations.batchUpdate 程式碼範例說明如何使用 InsertTextRequest 方法,將文字插入 PAGE_ELEMENT_ID 指定的空白文字方塊中。然後,該範例使用 CreateParagraphBulletsRequest 方法,將所有文字方塊文字轉換為項目符號清單。清單中的項目會以 \n 字元分隔,而阻斷則是由 \t 字元控制。

以下是用於建立簡報的要求通訊協定:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My List\n\tItem 1\n\t\tItem 2\n\t\t\tItem 3",
        "insertionIndex": 0
      },
      "createParagraphBullets": {
        "objectId": PAGE_ELEMENT_ID,
        "bulletPreset": "BULLET_ARROW_DIAMOND_DISC",
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

這項要求可建立類似下方的項目符號清單:

項目符號清單的食譜結果。

在投影片中加入圖案

下列 presentations.batchUpdate 程式碼範例說明如何使用 CreateShapeRequest 方法,在 PAGE_ID 指定的投影片中加入波形形狀。這項要求會指定形狀類型,然後在投影片中縮放及定位形狀。然後使用 InsertTextRequest 方法在該形狀中加入文字。該要求會將行的 ID 設為 PAGE_ELEMENT_ID

以下要求通訊協定可用於在投影片中加入形狀:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "createShape": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 0.6807,
            "scaleY": 0.4585,
            "translateX": 6583050,
            "translateY": 1673950,
            "unit": "EMU"
          }
        },
        "shapeType": "WAVE"
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My Wave Shape",
        "insertionIndex": 0
      }
    }
  ]
}

在投影片中新增影片

以下 presentations.batchUpdate 程式碼範例說明如何使用 CreateVideoRequest 方法,將影片嵌入 PAGE_ID 指定的投影片。這項要求會縮放影片在投影片中的位置,並將影片 ID 設為 PAGE_ELEMENT_ID。來源影片的專屬 ID 會設為 VIDEO_ID。例如,https://www.youtube.com/watch?v=7U3axjORYZ0 的 YouTube 影片 ID 為 7U3axjORYZ0

以下是將影片新增至投影片的要求通訊協定:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "createVideo": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 12000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 9000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 381,
            "scaleY": 381,
            "translateX": 152400,
            "translateY": 152400,
            "unit": "EMU"
          }
        },
        "source": "YOUTUBE",
        "id": VIDEO_ID
      }
    }
  ]
}

複製及編輯元素

以下 presentations.batchUpdate 程式碼範例說明如何使用 DuplicateObjectRequest 方法取得現有形狀 (由 PAGE_ELEMENT_ID 指定) 並建立副本 (由 COPY_ELEMENT_ID 指定)。

接著,後續的要求會對重複的物件進行下列變更:

  • 將背景顏色設為 LIGHT2 主題顏色。
  • 將副本向下移動 (從原始形狀的位置)。
  • 將文字字型設為 18 點 (喬治亞州)。
  • 將文字編輯成「My Shape Copy」。

這裡的要求會使用欄位遮罩,保留未變更的形狀屬性 (例如外框樣式)。使用欄位遮罩也可以改善效能。

如要進一步瞭解如何複製投影片,請參閱「複製投影片」範例。

以下是複製及編輯元素的要求通訊協定:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "duplicateObject": {
        "objectId": PAGE_ELEMENT_ID,
        "objectIds": {
          PAGE_ELEMENT_ID: COPY_ELEMENT_ID
        }
      }
    },
    {
      "updateShapeProperties": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "shapeBackgroundFill.solidFill.color",
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "LIGHT2"
              }
            }
          }
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": COPY_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
          "scaleX": 1,
          "scaleY": 1,
          "translateX": 0,
          "translateY": 1250000,
          "unit": "EMU"
        }
      }
    },
    {
      "updateTextStyle": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "fontFamily,fontSize",
        "textRange": {
          "type": "ALL"
        },
        "style": {
          "fontFamily": "Georgia",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        }
      }
    },
    {
      "deleteText": {
        "objectId": COPY_ELEMENT_ID,
        "textRange": {
          "type": "ALL"
        }
      }
    },
    {
      "insertText": {
        "objectId": COPY_ELEMENT_ID,
        "text": "My Shape Copy",
        "insertionIndex": 0
      }
    }
  ]
}

更新完成後,形狀和文案看起來可能會像這樣:

複製並編輯元素方案結果。

編輯圖片或影片大綱

以下 presentations.batchUpdate 程式碼範例說明如何使用 UpdateImagePropertiesRequest 方法,更新 IMAGE_ELEMENT_ID 指定的圖片外框外觀。也會使用 UpdateVideoPropertiesRequest 方法更新 VIDEO_ELEMENT_ID 指定的內嵌影片外框外觀。

要求會對物件進行下列變更:

  • 使用部分透明度,將圖片外框顏色設為 ACCENT5 主題顏色。
  • 將影片外框顏色設為 ACCENT1 主題顏色,不透明。
  • 將兩者的外框粗細設為 3 分。
  • 將圖片外框樣式設為 SOLID
  • 將影片外框樣式設為 DASH_DOT

UpdateImagePropertiesRequest 方法和 UpdateVideoPropertiesRequest 方法都只能變更圖片和影片外框的外觀。所有其他屬性皆為唯讀狀態。這裡的要求會使用欄位遮罩,指定僅應變更外框,以防止程式碼日後出現 API 異動。使用欄位遮罩也可以改善效能。

以下是編輯圖片或影片大綱的要求通訊協定:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "updateImageProperties": {
        "objectId": IMAGE_ELEMENT_ID,
        "fields": "outline",
        "imageProperties": {
          "outline": {
            "dashStyle": "SOLID",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    },
    {
      "updateVideoProperties": {
        "objectId": VIDEO_ELEMENT_ID,
        "fields": "outline",
        "videoProperties": {
          "outline": {
            "dashStyle": "DASH_DOT",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT1"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

更新後,圖片和內嵌影片看起來可能會像這樣:

圖片和影片概述食譜的結果

編輯形狀外框

以下 presentations.batchUpdate 程式碼範例說明如何使用 UpdateShapePropertiesRequest 方法取得現有形狀 (由 PAGE_ELEMENT_ID 指定),並更新其外框外觀。

要求會對物件進行下列變更:

  • 使用部分透明度,將外框顏色設為 ACCENT5 主題顏色。
  • 將外框粗細設為 3 點。
  • 將外框樣式設為 LONG_DASH

這裡的要求會使用欄位遮罩,保留未變更的形狀屬性 (例如形狀填滿顏色)。使用欄位遮罩也可以改善效能。

以下要求通訊協定可用於編輯形狀輪廓:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "outline",
        "shapeProperties": {
          "outline": {
            "dashStyle": "LONG_DASH",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.6,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

更新後的形狀如下:

編輯大綱食譜結果。

設定圖案或文字方塊的文字格式

以下 presentations.batchUpdate 程式碼範例說明如何使用 UpdateTextStyleRequest 方法取得現有形狀 (由 PAGE_ELEMENT_ID 指定),並更新文字的外觀。

要求會對物件進行下列變更:

  • 將文字顏色設為 ACCENT5 主題顏色。
  • 將字型設為粗體、斜體 18-pt 柯西瓦。
  • 為文字加上底線。

這裡的要求會使用欄位遮罩,保留未變更的文字樣式屬性 (例如背景顏色、連結或基準位移)。使用欄位遮罩也能改善效能。

以下要求通訊協定可用於設定形狀或文字方塊的文字格式:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "updateTextStyle": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "foregroundColor,bold,italic,fontFamily,fontSize,underline",
        "style": {
          "foregroundColor": {
            "opaqueColor": {
              "themeColor": "ACCENT5"
            }
          },
          "bold": true,
          "italic": true,
          "underline": true,
          "fontFamily": "Corsiva",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        },
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

更新完成後,形狀文字看起來可能會像這樣:

編輯文字格式的方案結果。

從 Google 試算表匯入圖表

以下 presentations.batchUpdate 程式碼範例說明如何使用 CreateSheetsChartRequest 方法從工作表匯入圖表,並放到 PAGE_ID 指定的投影片中。

要求需要試算表 ID (由 SPREADSHEET_ID 指定) 和試算表圖表 ID (由 SPREADSHEET_CHART_ID 指定)。投影片簡報中的圖表 ID 則由 PRESENTATION_CHART_ID 指定。

這項要求也會將簡報圖表的 LinkingMode 設為 LINKED,這樣一來,如果來源試算表中的圖表已更新,您就可以更新內嵌圖表。

以下為從試算表匯入圖表的要求通訊協定:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "createSheetsChart": {
        "objectId": PRESENTATION_CHART_ID,
        "spreadsheetId": SPREADSHEET_ID,
        "chartId": SPREADSHEET_CHART_ID,
        "linkingMode": "LINKED",
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 4000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 4000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 100000,
            "translateY": 100000,
            "unit": "EMU"
          }
      }
    }
  ]
}

重新整理試算表中的圖表

以下 presentations.batchUpdate 程式碼範例說明如何使用 RefreshSheetsChartRequest 方法重新整理簡報中已連結的圖表,將其替換為試算表來源試算表中該圖表的最新版本。這項要求需要簡報簡報中的圖表 ID (由 PRESENTATION_CHART_ID 指定)。

以下要求通訊協定用於重新整理試算表中圖表:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate
{
  "requests": [
    {
      "refreshSheetsChart": {
        "objectId": PRESENTATION_CHART_ID
      }
    }
  ]
}