Class Document

文件

文件包含一或多個 Tab 物件,每個物件都包含富文字和表格和清單等元素。

您可以使用 DocumentApp 開啟或建立文件。

// Open a document by ID.
let doc = DocumentApp.openById('<my-id>');

// Create and open a document.
doc = DocumentApp.create('Document Title');

Document 類別上的方法會直接存取及修改文字內容,並在目前分頁 (在指令碼中繫結至特定文件) 或第一個分頁 (如果沒有目前分頁) 上運作。依賴這些方法的指令碼 (例如 getBody()) 可以使用 getTabs()Tab.asDocumentTab() 遷移至支援分頁。

方法

方法傳回類型簡短說明
addBookmark(position)BookmarkBookmark 新增至指定 Position 的首個分頁,或將 Bookmark 新增至與文件繫結的指令碼的目前分頁。
addEditor(emailAddress)Document將指定使用者新增至 Document 的編輯者清單。
addEditor(user)Document將指定使用者新增至 Document 的編輯者清單。
addEditors(emailAddresses)Document將指定的使用者陣列新增至 Document 的編輯者清單。
addFooter()FooterSection如果沒有頁尾部分,就會新增至第一個分頁,如果是與文件繫結的指令碼,則會新增至目前的分頁。
addHeader()HeaderSection如果沒有標頭區段,就會新增至第一個分頁,如果是與文件繫結的指令碼,則會新增至目前的分頁。
addNamedRange(name, range)NamedRange在第一個分頁或指令碼的目前分頁中,新增 NamedRange (這是具有名稱和 ID 的 Range,可用於日後擷取)。如果是繫結至文件的指令碼,則會在目前分頁中新增 NamedRange
addViewer(emailAddress)Document將指定使用者新增至 Document 的觀眾名單。
addViewer(user)Document將指定使用者新增至 Document 的觀眾名單。
addViewers(emailAddresses)Document將指定的使用者陣列新增至 Document 的觀眾清單。
getActiveTab()Tab取得使用者在文件中目前使用的 Tab
getAs(contentType)Blob將目前的 Document 內容擷取為指定類型的 blob。
getBlob()Blob以 blob 的形式擷取目前的 Document 內容。
getBody()Body擷取第一個分頁的 Body,或是針對繫結至文件的指令碼,擷取目前分頁的 DocumentBodySection
getBookmark(id)Bookmark取得第一個分頁中具有指定 ID 的 Bookmark,如果是與文件繫結的指令碼,則取得目前分頁。
getBookmarks()Bookmark[]取得第一個分頁中的所有 Bookmark 物件,或是與文件繫結的指令碼的目前分頁。
getCursor()Position取得使用者在有效分頁中的游標。
getEditors()User[]取得這個 Document 的編輯者清單。
getFooter()FooterSection擷取第一個分頁的頁尾部分,或是與文件繫結的指令碼的目前分頁頁尾部分。
getFootnotes()Footnote[]擷取第一個分頁主體中的所有 Footnote 元素,或是與文件繫結的指令碼的目前分頁主體。
getHeader()HeaderSection擷取第一個分頁的標題區段,或是與文件繫結的指令碼的目前分頁標題區段。
getId()String擷取文件的專屬 ID。
getLanguage()String取得文件的語言代碼。
getName()String擷取文件的標題。
getNamedRangeById(id)NamedRange取得第一個分頁中具有指定 ID 的 NamedRange,如果是與文件繫結的指令碼,則取得目前分頁。
getNamedRanges()NamedRange[]取得第一個分頁中的所有 NamedRange 物件,或是與文件繫結的指令碼的目前分頁。
getNamedRanges(name)NamedRange[]在第一個分頁中,或針對已繫結至文件的腳本,在有效分頁中,取得所有具有指定名稱的 NamedRange 物件。
getSelection()Range取得使用者在現用分頁中的選項。
getSupportedLanguageCodes()String[]取得 Google 文件檔案支援的所有語言代碼。
getTab(tabId)Tab取得含有指定 ID 的 Tab
getTabs()Tab[]取得文件中所有未巢狀的 Tab
getUrl()String擷取可存取目前文件的網址。
getViewers()User[]取得這個 Document 的檢視者和加註者清單。
newPosition(element, offset)Position建立新的 Position,這是對分頁中位置的參照,相對於第一個分頁中的特定元素,或是對已繫結至文件的指令碼,則是目前分頁。
newRange()RangeBuilder建立建構工具,用於從第一個分頁中的分頁元素,或 (對於與文件繫結的腳本) 有效分頁中,建構 Range 物件。
removeEditor(emailAddress)Document將指定使用者從 Document 的編輯者清單中移除。
removeEditor(user)Document將指定使用者從 Document 的編輯者清單中移除。
removeViewer(emailAddress)Document將指定使用者從 Document 的觀眾和留言者名單中移除。
removeViewer(user)Document將指定使用者從 Document 的觀眾和留言者名單中移除。
saveAndClose()void儲存目前的 Document
setActiveTab(tabId)void將使用者在目前文件中選取的 Tab 設為含有指定 ID 的分頁。
setCursor(position)Document在提供 Position 的情況下,設定使用者的游標。
setLanguage(languageCode)Document設定文件的語言代碼。
setName(name)Document設定文件標題。
setSelection(range)Document在提供 Range 的情況下,在有效分頁中設定使用者的選取項目。

內容詳盡的說明文件

addBookmark(position)

Bookmark 新增至指定 Position 的首個分頁,或將 Bookmark 新增至與文件繫結的指令碼的目前分頁。如要在任何分頁中新增書籤,請使用 DocumentTab.addBookmark(position) 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the active or first tab's body and adds a paragraph.
const paragraph = doc.getBody().appendParagraph('My new paragraph.');

// Creates a position at the first character of the paragraph text.
const position = doc.newPosition(paragraph.getChild(0), 0);

// Adds a bookmark at the first character of the paragraph text.
const bookmark = doc.addBookmark(position);

// Logs the bookmark ID to the console.
console.log(bookmark.getId());

參數

名稱類型說明
positionPosition新書籤的位置。

回攻員

Bookmark - 新的書籤。

授權

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

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

addEditor(emailAddress)

將指定使用者新增至 Document 的編輯者清單。如果使用者已在觀看者名單中,這個方法會將使用者從觀看者名單中移除。

參數

名稱類型說明
emailAddressString要新增的使用者電子郵件地址。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

addEditor(user)

將指定使用者新增至 Document 的編輯者清單。如果使用者已在觀看者名單中,這個方法會將使用者從觀看者名單中移除。

參數

名稱類型說明
userUser要新增的使用者代表。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

addEditors(emailAddresses)

將指定的使用者陣列新增至 Document 的編輯者清單。如果有任何使用者已在觀眾名單中,這個方法會將他們從觀眾名單中移除。

參數

名稱類型說明
emailAddressesString[]要新增的使用者電子郵件地址陣列。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

addFooter()

如果沒有頁尾部分,就會新增至第一個分頁,如果是與文件繫結的指令碼,則會新增至目前的分頁。如要在任何分頁中新增頁尾,請使用 DocumentTab.addFooter() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Adds a footer to the document's active or first tab.
const footer = doc.addFooter();

// Sets the footer text to 'This is a footer.'
footer.setText('This is a footer');

回攻員

FooterSection:分頁頁尾。

授權

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

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

addHeader()

如果沒有標頭區段,就會新增至第一個分頁,如果是與文件繫結的指令碼,則會新增至目前的分頁。如要在任何分頁中新增標頭區段,請使用 DocumentTab.addHeader() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Adds a header to the document's active or first tab.
const header = doc.addHeader();

// Sets the header text to 'This is a header.'
header.setText('This is a header');

回攻員

HeaderSection:分頁標頭。

授權

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

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

addNamedRange(name, range)

在第一個分頁或指令碼的目前分頁中,新增 NamedRange (這是具有名稱和 ID 的 Range,可用於日後擷取)。如果是繫結至文件的指令碼,則會在目前分頁中新增 NamedRange。如要在任何分頁中新增 NamedRange,請使用 DocumentTab.addNamedRange(name, range) 方法。名稱不一定是唯一的;同一份文件中的多個範圍可以共用相同的名稱,就像 HTML 中的類別一樣。相較之下,ID 在文件中是唯一的,就像 HTML 中的 ID 一樣。在文件中加入 NamedRange 後,您無法修改,只能移除。

任何存取文件的指令碼都可以存取 NamedRange。為避免指令碼之間發生非預期的衝突,建議在範圍名稱前方加上專屬字串。

// Creates a named range that includes every table in the active tab.
const doc = DocumentApp.getActiveDocument();
const rangeBuilder = doc.newRange();
const tables = doc.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
// Adds the named range to the document's active tab.
doc.addNamedRange('Document tables', rangeBuilder.build());

參數

名稱類型說明
nameString範圍名稱 (不必是唯一名稱),範圍名稱長度必須介於 1 至 256 個半形字元之間。
rangeRange要與名稱建立關聯的元素範圍。範圍可以是有效的選取範圍搜尋結果,或是使用 newRange() 手動建立。

回攻員

NamedRangeNamedRange

授權

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

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

addViewer(emailAddress)

將指定使用者新增至 Document 的觀眾名單。如果使用者已在編輯者名單中,這個方法就不會生效。

參數

名稱類型說明
emailAddressString要新增的使用者電子郵件地址。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

addViewer(user)

將指定使用者新增至 Document 的觀眾名單。如果使用者已在編輯者名單中,這個方法就不會生效。

參數

名稱類型說明
userUser要新增的使用者代表。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

addViewers(emailAddresses)

將指定的使用者陣列新增至 Document 的觀眾清單。如果有任何使用者已在編輯者清單中,則此方法對他們不會有任何影響。

參數

名稱類型說明
emailAddressesString[]要新增的使用者電子郵件地址陣列。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

getActiveTab()

取得使用者在文件中目前使用的 Tab。指令碼只能存取執行指令碼的使用者所屬的有效分頁,且必須是指令碼繫結至文件。

// Display a dialog box that shows the title of the tab that the
// user is currently viewing.
const tab = DocumentApp.getActiveDocument().getActiveTab();
DocumentApp.getUi().alert(`ID of selected tab: ${tab.getTitle()}`);

回攻員

Tab:使用者目前的 Tab,如果指令碼未繫結至文件,則為 null

授權

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

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

getAs(contentType)

將目前的 Document 內容擷取為指定類型的 Blob。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the document as a PDF.
const pdf = doc.getAs('application/pdf');

// Logs the name of the PDF to the console.
console.log(pdf.getName());

參數

名稱類型說明
contentTypeString要轉換的 MIME 類型;支援 'application/pdf''text/markdown'

回攻員

Blob:目前的文件為 Blob。


getBlob()

以 blob 的形式擷取目前的 Document 內容。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Retrieves the current document's contents as a blob and logs it to the
// console.
console.log(doc.getBlob().getContentType());

回攻員

Blob:目前的文件為 Blob。


getBody()

擷取第一個分頁的 Body,或是與文件繫結的指令碼的目前分頁 DocumentBodySection。如要取得任何分頁的 DocumentBodySection,請使用 DocumentTab.getBody() 方法。

分頁可能包含不同類型的部分 (例如 HeaderSectionFooterSection)。分頁的有效部分是 Body

Document 中的元素方法會委派至有效的 Body

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the active or first tab's body.
const body = doc.getBody();

// Gets the body text and logs it to the console.
console.log(body.getText());

回攻員

Body:分頁內文區段。

授權

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

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

getBookmark(id)

取得第一個分頁中具有指定 ID 的 Bookmark,或是與文件繫結的指令碼的目前分頁。如要取得任何分頁中的書籤,請使用 DocumentTab.getBookmark(id) 方法。如果分頁中沒有此類 Bookmark,這個方法會傳回 null

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the bookmark by its ID in the document's active or first tab.
const bookmark = doc.getBookmark('id.xyz654321');

// If the bookmark exists, logs the character offset of its position to the
// console. otherwise, logs 'No bookmark exists with the given ID.' to the
// console.
if (bookmark) {
  console.log(bookmark.getPosition().getOffset());
} else {
  console.log('No bookmark exists with the given ID.');
}

參數

名稱類型說明
idStringBookmark 的 ID。

回攻員

Bookmark:具有指定 ID 的 Bookmark,如果分頁中沒有這樣的 Bookmark,則為 null

授權

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

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

getBookmarks()

取得第一個分頁中的所有 Bookmark 物件,或是與文件繫結的指令碼的目前分頁。如要取得任何分頁中的所有書籤,請使用 DocumentTab.getBookmarks() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
const doc = DocumentApp.openById('123abc');

// Gets all of the bookmarks in the document's active or first tab.
const bookmarks = doc.getBookmarks();

// Logs the number of bookmarks in the tab to the console.
console.log(bookmarks.length);

回攻員

Bookmark[]:分頁中 Bookmark 物件的陣列。

授權

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

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

getCursor()

取得使用者在有效分頁中的游標。指令碼只能存取執行指令碼的使用者游標,且只有在指令碼繫結至文件時才能存取。

// Insert some text at the cursor position and make it bold.
const cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns
  // null, the cursor's containing element doesn't allow insertions, so show the
  // user an error message.
  const element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}

回攻員

Position:使用者游標的表示法,如果使用者未在分頁中放置游標,或指令碼未繫結至文件,則為 null

授權

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

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

getEditors()

取得這個 Document 的編輯者清單。

回攻員

User[]:具備編輯權限的使用者陣列。

授權

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

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

getFooter()

擷取第一個分頁的頁尾部分,或是與文件繫結的指令碼的目前分頁頁尾部分。如要取得任何分頁的頁尾部分,請使用 DocumentTab.getFooter() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the text of the active or first tab's footer and logs it to the console.
console.log(doc.getFooter().getText());

回攻員

FooterSection:分頁的頁尾。

授權

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

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

getFootnotes()

擷取第一個分頁主體中的所有 Footnote 元素,或是與文件繫結的指令碼的目前分頁主體。如要取得任何分頁中的所有腳註,請使用 DocumentTab.getFootnotes() 方法。

getFootnotes 的呼叫會導致對分頁元素進行疊代。對於大型分頁,請避免不必要地呼叫此方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the first footnote in the active or first tab's body.
const footnote = doc.getFootnotes()[0];

// Logs footnote contents to the console.
console.log(footnote.getFootnoteContents().getText());

回攻員

Footnote[]:分頁的註腳。

授權

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

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

getHeader()

擷取第一個分頁的標頭區段,或是與文件繫結的指令碼的目前分頁標頭區段。如要取得任何分頁的標頭部分,請使用 DocumentTab.getHeader() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the text of the active or first tab's header and logs it to the console.
console.log(doc.getHeader().getText());

回攻員

HeaderSection:分頁標頭。

授權

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

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

getId()

擷取文件的專屬 ID。文件 ID 可搭配 DocumentApp.openById() 使用,用於開啟特定文件例項。

回攻員

String:文件 ID。

授權

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

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

getLanguage()

取得文件的語言代碼。這是文件編輯器的「File」>「Language」中顯示的語言,可能不是文件實際包含的語言。

回攻員

String:文件語言,如未定義,則為 null

授權

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

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

getName()

擷取文件的標題。

回攻員

String:文件標題。

授權

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

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

getNamedRangeById(id)

取得第一個分頁中具有指定 ID 的 NamedRange,或是與文件繫結的指令碼的目前分頁。如要在任何分頁中取得具有指定 ID 的 NamedRange,請使用 DocumentTab.getNamedRangeById(id) 方法。如果分頁中沒有這樣的 NamedRange,這個方法會傳回 null。名稱不一定是唯一的,即使跨分頁也是如此;同一個分頁中的多個不同範圍可能會共用相同的名稱,就像 HTML 中的類別一樣。相較之下,ID 在分頁中是唯一的,就像 HTML 中的 ID 一樣。

參數

名稱類型說明
idString範圍的 ID,在分頁中為唯一的 ID。

回攻員

NamedRange:具有指定 ID 的 NamedRange,如果分頁中沒有這類範圍,則為 null

授權

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

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

getNamedRanges()

取得第一個分頁中的所有 NamedRange 物件,或是與文件繫結的指令碼的目前分頁。如要取得任何分頁中的所有 NamedRange 物件,請使用 DocumentTab.getNamedRanges() 方法。

任何存取分頁的指令碼都可以存取 NamedRange。為避免指令碼之間發生非預期的衝突,建議您在範圍名稱前方加上專屬字串。

回攻員

NamedRange[]:分頁中 NamedRange 物件的陣列,可能包含多個名稱相同的範圍。

授權

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

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

getNamedRanges(name)

會在第一個分頁中,取得所有具有指定名稱的 NamedRange 物件,或是在與文件繫結的腳本中,取得有效分頁的物件。如要取得任何分頁中的所有 NamedRange 物件,請使用 DocumentTab.getNamedRanges(name) 方法。名稱不一定是唯一的,即使跨分頁也是如此;同一個分頁中的多個不同範圍可能會共用相同的名稱,就像 HTML 中的類別一樣。相較之下,ID 在分頁中是唯一的,就像 HTML 中的 ID 一樣。

任何可存取文件的指令碼都可以存取 NamedRange。為避免指令碼之間發生非預期的衝突,建議您在範圍名稱前方加上專屬字串。

參數

名稱類型說明
nameString範圍名稱,不一定是唯一值。

回攻員

NamedRange[]:指定名稱分頁中 NamedRange 物件的陣列。

授權

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

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

getSelection()

取得使用者在現用分頁中的選項。指令碼只能存取執行指令碼的使用者所選取的項目,且只有在指令碼繫結至文件時才能存取。

// Display a dialog box that tells the user how many elements are included in
// the selection.
const selection = DocumentApp.getActiveDocument().getSelection();
if (selection) {
  const elements = selection.getRangeElements();
  DocumentApp.getUi().alert(`Number of selected elements: ${elements.length}`);
} else {
  DocumentApp.getUi().alert('Nothing is selected.');
}

回攻員

Range:代表使用者的選取項目,如果使用者在分頁中未選取任何項目、只選取段落結尾、只選取段落結尾和新行,或是指令碼未繫結至文件,則會傳回 null

授權

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

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

getSupportedLanguageCodes()

取得 Google 文件檔案支援的所有語言代碼。

回攻員

String[]:語言代碼陣列。

授權

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

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

getTab(tabId)

取得含有指定 ID 的 Tab。如果沒有此類 Tab,這個方法會傳回 null。可存取任何巢狀結構層級的分頁。

參數

名稱類型說明
tabIdString要取得的分頁 ID。

回攻員

Tab:具有指定 ID 的 Tab,如果沒有這樣的 Tab,則為 null

授權

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

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

getTabs()

取得文件中所有未巢狀的 Tab

分頁可以包含子分頁,也就是在另一個分頁中巢狀的分頁。您可以使用 Tab.getChildTabs() 存取子分頁。

回攻員

Tab[]:文件中所有 Tab 的清單。

授權

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

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

getUrl()

擷取可存取目前文件的網址。

const doc = DocumentApp.getActiveDocument();

// Send out the link to open the document.
MailApp.sendEmail('<email-address>', doc.getName(), doc.getUrl());

回攻員

String:存取目前文件的網址。

授權

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

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

getViewers()

取得這個 Document 的檢視者和加註者清單。

回攻員

User[]:具有查看或註解權限的使用者陣列。

授權

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

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

newPosition(element, offset)

建立新的 Position,這是對分頁中位置的參照,相對於第一個分頁中的特定元素,或是對已繫結至文件的指令碼,則是目前分頁。如要根據任何分頁中的某個位置建立 Position,請使用 DocumentTab.newPosition(element, offset) 方法。使用者游標會以 Position 和其他符號表示。

// Append a paragraph to the active tab, then place the user's cursor after the
// first word of the new paragraph.
const doc = DocumentApp.getActiveDocument();
const paragraph = doc.getBody().appendParagraph('My new paragraph.');
const position = doc.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

參數

名稱類型說明
elementElement應包含新 Position 的元素;此元素必須是 Text 元素或 Paragraph 等容器元素。
offsetInteger對於 Text 元素,是 Position 前半形字元數量;對於其他元素,是同一容器元素中 Position 前子項數量。

回攻員

Position:新的 Position

授權

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

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

newRange()

建立建構工具,用於從第一個分頁中的分頁元素,或針對與文件繫結的腳本,從活動分頁中建構 Range 物件。如要建立建構工具,用於從任何分頁中的分頁元素建構 DocumentRange 物件,請使用 DocumentTab.newRange() 方法。

// Change the user's selection to a range that includes every table in the
// active tab.
const doc = DocumentApp.getActiveDocument();
const rangeBuilder = doc.newRange();
const tables = doc.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

回攻員

RangeBuilder:新建構工具。

授權

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

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

removeEditor(emailAddress)

將指定使用者從 Document 的編輯者清單中移除。如果使用者屬於擁有一般存取權的使用者類別,這個方法就不會阻止他們存取 Document,例如 Document 與使用者的整個網域共用,或是 Document 位於使用者可存取的共用雲端硬碟中。

對於雲端硬碟檔案,這也會將使用者從檢視者清單中移除。

參數

名稱類型說明
emailAddressString要移除的使用者電子郵件地址。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

removeEditor(user)

將指定使用者從 Document 的編輯者清單中移除。如果使用者屬於擁有一般存取權的使用者類別,這個方法就不會阻止他們存取 Document,例如 Document 與使用者的整個網域共用,或是 Document 位於使用者可存取的共用雲端硬碟中。

對於雲端硬碟檔案,這也會將使用者從檢視者清單中移除。

參數

名稱類型說明
userUser要移除的使用者代表。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

removeViewer(emailAddress)

將指定使用者從 Document 的觀眾和留言者名單中移除。如果使用者是編輯者,而非觀眾或評論者,則這個方法不會生效。使用者如果屬於具有一般存取權的使用者類別,這項方法也不會阻止使用者存取 Document,例如 Document 與使用者的整個網域共用,或是 Document 位於使用者可存取的共用雲端硬碟中。

對於雲端硬碟檔案,這也會將使用者從編輯者清單中移除。

參數

名稱類型說明
emailAddressString要移除的使用者電子郵件地址。

回攻員

Document:用於鏈結的 Document

授權

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

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

removeViewer(user)

將指定使用者從 Document 的觀眾和留言者名單中移除。如果使用者是編輯者而非觀眾,這個方法就不會生效。如果使用者屬於具有一般存取權的使用者類別,這項方法也不會阻止使用者存取 Document,例如 Document 與使用者的整個網域共用,或是 Document 位於使用者可存取的共用雲端硬碟中。

對於雲端硬碟檔案,這也會將使用者從編輯者清單中移除。

參數

名稱類型說明
userUser要移除的使用者代表。

回攻員

Document:用於鏈結的 Document

授權

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

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

saveAndClose()

儲存目前的 Document。會導致待處理的更新內容刷新並套用。

系統會在每個可編輯的 Document 指令碼執行結束時,自動叫用 saveAndClose() 方法。

已關閉的 Document 無法編輯。使用 DocumentApp.openById() 重新開啟特定文件進行編輯。

授權

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

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

setActiveTab(tabId)

將使用者在目前文件中選取的 Tab 設為含有指定 ID 的分頁。

const doc = DocumentApp.getActiveDocument();

// Sets the user's selected tab by its ID.
// TODO(developer): Replace the ID with your own.
const tab = doc.setActiveTab('123abc');

參數

名稱類型說明
tabIdString要設為使用中的分頁 ID。

授權

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

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

setCursor(position)

在提供 Position 的情況下,設定使用者的游標。指令碼只能存取執行指令碼的使用者游標,且只有在指令碼繫結至文件時才能存取。

從未啟用的 Tab 提供 Position,可切換使用者的有效分頁。

const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();

// Append a paragraph, then place the user's cursor after the first word of the
// new paragraph.
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
const position = documentTab.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

參數

名稱類型說明
positionPosition新的游標位置。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

setLanguage(languageCode)

設定文件的語言代碼。這是文件編輯器的「File」>「Language」中顯示的語言,但不一定是文件實際包含的語言。使用 getSupportedLanguageCodes() 取得所有有效的語言代碼。

參數

名稱類型說明
languageCodeString語言代碼。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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

setName(name)

設定文件標題。

參數

名稱類型說明
nameString新文件標題。

回攻員

Document:目前的文件。

授權

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

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

setSelection(range)

在提供 Range 的情況下,設定使用者在有效分頁中的選取項目。指令碼只能存取執行指令碼的使用者所選取的項目,且只有在指令碼繫結至文件時才能存取。

const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();

// Change the user's selection to a range that includes every table in the
// document.
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

參數

名稱類型說明
rangeRange要選取的新元素範圍。

回攻員

Document:這個 Document,用於鏈結。

授權

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

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