Class FormResponse

表單回覆

回覆整份表單。FormResponse 有三種用途：存取受訪者提交的答案 (請參閱 getItemResponses())、以程式輔助方式將回覆提交至表單 (請參閱 withItemResponse(response) 和 submit())，以及為表單產生網址，以便使用提供的答案預先填入欄位。FormResponse 可透過 Form 建立或存取。

// Open a form by ID and log the responses to each question.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const formResponses = form.getResponses();
for (let i = 0; i < formResponses.length; i++) {
  const formResponse = formResponses[i];
  const itemResponses = formResponse.getItemResponses();
  for (let j = 0; j < itemResponses.length; j++) {
    const itemResponse = itemResponses[j];
    Logger.log(
        'Response #%s to the question "%s" was "%s"',
        (i + 1).toString(),
        itemResponse.getItem().getTitle(),
        itemResponse.getResponse(),
    );
  }
}

方法

方法	傳回類型	簡短說明
getEditResponseUrl()	String	產生網址，可用於編輯已提交的回覆。
getGradableItemResponses()	ItemResponse[]	依照項目在表單中顯示的順序，取得表單回應中包含的所有項目回應。
getGradableResponseForItem(item)	ItemResponse	取得指定項目的表單回應中所含的項目回應。
getId()	String	取得表單回覆的 ID。
getItemResponses()	ItemResponse[]	依照項目在表單中顯示的順序，取得表單回應中包含的所有項目回應。
getRespondentEmail()	String	取得提交回覆的使用者電子郵件地址 (如果已啟用 Form.setCollectEmail(collect) 設定)。
getResponseForItem(item)	ItemResponse	取得此表單回應中，針對特定項目所包含的項目回應。
getTimestamp()	Date	取得表單回覆提交作業的時間戳記。
submit()	FormResponse	提交回應。
toPrefilledUrl()	String	產生表單的網址，其中的答案會根據表單回覆中的答案預先填入。
withItemGrade(gradedResponse)	FormResponse	將指定項目回覆的成績加入表單回覆。
withItemResponse(response)	FormResponse	將指定的項目回應新增至表單回應。

內容詳盡的說明文件

getEditResponseUrl()

產生網址，可用於編輯已提交的回覆。如果 Form.setAllowResponseEdits(enabled) 設定已停用，連結會導向說明停用表單回應編輯功能的頁面。任何造訪連結的使用者都能編輯回覆，但如果啟用 Form.setRequireLogin(requireLogin) 設定，他們必須擁有可存取表單的帳戶。如果啟用 Form.setCollectEmail(collect) 設定，表單會記錄編輯回覆的使用者電子郵件地址，而非原始回覆者的電子郵件地址。

如果是指令碼已建立但尚未提交的表單回覆，這個方法會傳回 null。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets the first form response.
const formResponse = form.getResponses()[0];

// Gets the edit URL for the first form response and logs it to the console.
const editUrl = formResponse.getEditResponseUrl();
console.log(editUrl);

回攻員

String：變更已提交回覆的網址。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

getGradableItemResponses()

以表單中項目顯示的順序，取得表單回應中包含的所有項目回應。這個方法的運作方式與 getItemResponses() 類似，但為了評分缺少的答案，即使沒有實際回應，只要對應的 Item 可評分 (即有分數值)，這個方法仍會傳回 ItemResponse。不過，如果 Item 無法評分，這個方法會從傳回的陣列中排除該項目。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Gets the item responses contained in each form response.
for (const formResponse of formResponses) {
  const gradableItemsResponses = formResponse.getGradableItemResponses();

  // Logs the title and score for each item response to the console.
  for (const gradableItemsResponse of gradableItemsResponses) {
    console.log(`${gradableItemsResponse.getItem().getTitle()}
       score ${gradableItemsResponse.getScore()}`);
  }
}

回攻員

ItemResponse[]：針對表單中每個可讓受訪者獲得分數的問題項目，提供回覆陣列。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

getGradableResponseForItem(item)

取得指定項目的表單回應中所含的項目回應。這個方法的運作方式與 getResponseForItem(item) 類似，但為了評分缺少的答案，如果對應的 Item 可評分 (即有分數值)，即使沒有實際回應，它仍會傳回 ItemResponse。不過，如果 Item 無法評分，這個方法會傳回 null。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Gets the item responses contained in a form response.
for (const formResponse of formResponses) {
  const formItemResponses = formResponse.getGradableItemResponses();

  // Logs the title and score for responses to the first item of the form.
  const itemResponse = formResponse.getGradableResponseForItem(
      formItemResponses[0].getItem(),
  );
  console.log(
      `${itemResponse.getItem().getTitle()} score ${itemResponse.getScore()}`,
  );
}

參數

名稱	類型	說明
item	Item

回攻員

ItemResponse：指定項目的回應，如果沒有回應，且項目未評分，則傳回 null。

---

getId()

取得表單回覆的 ID。如果尚未提交表單回覆，這個方法會傳回 null。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Loops through the form responses and logs the ID for each form response to
// the console.
for (const formResponse of formResponses) {
  console.log(`Response ID: ${formResponse.getId()}`);
}

回攻員

String：表單回應的 ID，如果表單回應尚未提交，則為 null。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

getItemResponses()

以表單中項目顯示的順序，取得表單回應中包含的所有項目回應。如果表單回應未包含特定 TextItem、DateItem、TimeItem 或 ParagraphTextItem 的回應，則針對該項目傳回的 ItemResponse 會以空白字串做為回應。如果表單回應省略任何其他項目類型的回應，這個方法會從傳回的陣列中排除該項目。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets the responses to the form.
const formResponses = form.getResponses();

// Iterates over the responses.
for (const formResponse of formResponses) {
  // Gets the item responses from each form response.
  const itemResponses = formResponse.getItemResponses();

  // Iterates over the item responses.
  for (const itemResponse of itemResponses) {
    // Logs the items' questions and responses to the console.
    console.log(
        `Response to the question '${itemResponse.getItem().getTitle()}' was
      '${itemResponse.getResponse()}'`);
  }
}

回攻員

ItemResponse[]：針對表單中每個問題項目的回覆陣列，其中包含受訪者提供的答案。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

getRespondentEmail()

如果已啟用 Form.setCollectEmail(collect) 設定，則會取得提交回覆的使用者電子郵件地址。

如果是指令碼已建立但尚未提交的表單回覆，這個方法會傳回 null。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Loops through the responses and logs each respondent's email to the console.
// To collect respondent emails, ensure that Form.setCollectEmail(collect) is
// set to true.
for (const formResponse of formResponses) {
  console.log(`Respondent Email: ${formResponse.getRespondentEmail()}`);
}

回攻員

String：提交此回應的使用者電子郵件地址 (如有)，如果是指令碼建立此回應但尚未提交，則為 null。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

getResponseForItem(item)

取得此表單回應中，針對特定項目所包含的項目回應。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets the first item on the form.
const item = form.getItems()[0];

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Loops through the responses and logs each response to the first item to the
// console.
for (const formResponse of formResponses) {
  const itemResponse = formResponse.getResponseForItem(item);
  console.log(itemResponse.getResponse());
}

參數

名稱	類型	說明
item	Item

回攻員

ItemResponse：指定項目的回應，如果沒有項目，則傳回 null。

---

getTimestamp()

取得表單回覆提交作業的時間戳記。

如果是指令碼已建立但尚未提交的表單回覆，這個方法會傳回 null。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets an array of the form's responses.
const formResponses = form.getResponses();

// Loops through the responses and logs the timestamp of each response to the
// console.
for (const formResponse of formResponses) {
  console.log(`Timestamp: ${formResponse.getTimestamp()}`);
}

回攻員

Date：提交這項回應的時間戳記，如果指令碼建立這項回應但尚未提交，則為 null。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

submit()

提交回應。如果回應已提交，就會擲回指令碼例外狀況。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Creates an empty response for the form.
const formResponse = form.createResponse();

// Submits an empty response.
formResponse.submit();

回攻員

FormResponse：新建立的回覆，已儲存至表單的回覆儲存庫。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

toPrefilledUrl()

產生表單的網址，其中的答案會根據表單回覆中的答案預先填入。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Gets the first form response.
const formResponse = form.getResponses()[0];

// Generates and logs the URL of a pre-filled form response based on the answers
// of the first form response.
const prefilledUrl = formResponse.toPrefilledUrl();
console.log(prefilledUrl);

回攻員

String：含有預填答案的表單網址。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

withItemGrade(gradedResponse)

將指定項目回覆的成績加入表單回覆。這項方法只適用於已提交的表單回覆，且只會影響提交後儲存的分數。這個方法只會更新項目回應的成績，不會影響實際回應 (因為回應已提交)。如果系統針對同一項商品多次呼叫這個方法，則只會保留最後一次的評分。如果 ItemResponse 不含任何成績，這個方法會移除項目的成績。

// Programmatically award partial credit for a given response
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const formResponses = form.getResponses();
const formItems = form.getItems();
for (const formResponse of formResponses) {
  for (const item of formItems) {
    const points = item.asMultipleChoiceItem().getPoints();
    const itemResponse = formResponse.getGradableResponseForItem(item);
    Logger.log('Award half credit for answers containing the word "Kennedy"');
    const answer = itemResponse.getResponse();

    if (answer?.includes('Kennedy')) {
      itemResponse.setScore(points / 2);
      formResponse.withItemGrade(itemResponse);
    }
  }
}
form.submitGrades(formResponses);

參數

名稱	類型	說明
gradedResponse	ItemResponse

回攻員

FormResponse — 這個 FormResponse，用於鏈結

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms

---

withItemResponse(response)

將指定的項目回應新增至表單回應。這個方法只適用於指令碼建立但尚未提交的表單回覆，無法影響已儲存的回覆。如果這個方法針對同一項商品多次呼叫，系統只會保留最後一次的商品回應。

// Opens the Forms file by its ID.
// If you created your script from within a Google Forms file, you can
// use FormApp.getActiveForm() instead.
// TODO(developer): Replace the ID with your own.
const form = FormApp.openById('abc123456');

// Creates a response for the form.
const formResponse = form.createResponse();

// Appends a checkbox item to the form.
const item = form.addCheckboxItem();

// Sets the title of the item to 'Which items are ice cream flavors?'
item.setTitle('Which items are ice cream flavors?');

// Sets choices for the item.
item.setChoices([
  item.createChoice('Vanilla'),
  item.createChoice('Strawberry'),
  item.createChoice('Brick'),
]);

// Creates a response for the item.
const response = item.createResponse(['Vanilla', 'Strawberry']);

// Adds the item response to the form response.
formResponse.withItemResponse(response);

// Submits the form response.
formResponse.submit();

參數

名稱	類型	說明
response	ItemResponse

回攻員

FormResponse：這個 FormResponse，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/forms.currentonly
• https://www.googleapis.com/auth/forms