Class Document

文件，內含一或多個 Tab 物件，每個物件都包含 RTF 和表格、清單等元素。

您可以使用 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)`	`Bookmark`	在第一個分頁中加入指定的 `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`，可用於稍後擷取；如果是繫結至文件的指令碼，則會新增至目前的分頁。
`addViewer(emailAddress)`	`Document`	將指定使用者新增至 `Document` 的檢視者清單。
`addViewer(user)`	`Document`	將指定使用者新增至 `Document` 的檢視者清單。
`addViewers(emailAddresses)`	`Document`	將指定的使用者陣列新增至 `Document` 的檢視者清單。
`getActiveTab()`	`Tab\|null`	取得文件中目前使用者的有效 `Tab`。
`getAs(contentType)`	`Blob`	以指定型別的 Blob 形式，擷取目前的 `Document` 內容。
`getBlob()`	`Blob`	以 Blob 形式擷取目前的 `Document` 內容。
`getBody()`	`Body`	擷取第一個分頁的 `Body`，或是繫結至文件的指令碼目前分頁的 `DocumentBodySection`。
`getBookmark(id)`	`Bookmark\|null`	在第一個分頁中取得具有指定 ID 的 `Bookmark`，或在繫結至文件的指令碼中取得目前的分頁。
`getBookmarks()`	`Bookmark[]`	取得第一個分頁中的所有 `Bookmark` 物件，或取得繫結至文件的指令碼目前的分頁。
`getCursor()`	`Position\|null`	取得使用者的游標在活動分頁中的位置。
`getEditors()`	`User[]`	取得這個 `Document` 的編輯者清單。
`getFooter()`	`FooterSection\|null`	擷取第一個分頁的頁尾區段，或擷取繫結至文件的指令碼目前分頁的頁尾區段。
`getFootnotes()`	`Footnote[]`	擷取第一個分頁主體中的所有 `Footnote` 元素，或是擷取繫結至文件的指令碼所屬有效分頁主體中的所有元素。
`getHeader()`	`HeaderSection\|null`	擷取第一個分頁的標題區段，或是繫結至文件的指令碼目前分頁的標題區段。
`getId()`	`String`	擷取文件的專屬 ID。
`getLanguage()`	`String\|null`	取得文件的語言代碼。
`getName()`	`String`	擷取文件標題。
`getNamedRangeById(id)`	`NamedRange\|null`	在第一個分頁中取得具有指定 ID 的 `NamedRange`，或在繫結至文件的指令碼中取得目前的分頁。
`getNamedRanges()`	`NamedRange[]`	取得第一個分頁中的所有 `NamedRange` 物件，或取得繫結至文件的指令碼目前的分頁。
`getNamedRanges(name)`	`NamedRange[]`	在第一個分頁中取得具有指定名稱的所有 `NamedRange` 物件，或是取得與文件繫結的指令碼所屬的有效分頁。
`getSelection()`	`Range\|null`	取得現用分頁中使用者選取的項目。
`getSupportedLanguageCodes()`	`String[]`	取得 Google 文件檔案支援的所有語言代碼。
`getTab(tabId)`	`Tab\|null`	取得具有指定 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)`

在第一個分頁中加入指定的 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());

參數

名稱	類型	說明
`position`	`Position`	新書籤的位置。

回攻員

Bookmark：新的書籤。

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addEditor(emailAddress)`

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

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addEditor(user)`

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

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addEditors(emailAddresses)`

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

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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，請使用 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());

參數

名稱	類型	說明
`name`	`String`	範圍名稱，不一定要是專用的，但長度必須介於 1 到 256 個字元之間。
`range`	`Range`	要與名稱建立關聯的元素範圍；範圍可以是有效選取範圍、搜尋結果，或使用 `newRange()` 手動建構。

回攻員

NamedRange - NamedRange。

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addViewer(emailAddress)`

將指定使用者新增至 Document 的檢視者清單。如果使用者已在編輯者名單中，這個方法不會有任何作用。

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addViewer(user)`

將指定使用者新增至 Document 的檢視者清單。如果使用者已在編輯者名單中，這個方法不會有任何作用。

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`addViewers(emailAddresses)`

將指定的使用者陣列新增至 Document 的檢視者清單。如果使用者已在編輯者清單中，這個方法對他們不會有任何影響。

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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|null：使用者目前使用的 Tab，如果指令碼未繫結至文件，則為 null。

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`getAs(contentType)`

以指定型別的 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');

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

參數

名稱	類型	說明
`contentType`	`String`	要轉換的 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() 方法。

分頁可能包含不同類型的區段 (例如 HeaderSection、FooterSection)。分頁的有效區段為 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.');
}

參數

名稱	類型	說明
`id`	`String`	`Bookmark` 的 ID。

回攻員

Bookmark|null：具有指定 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：代表使用者的游標，如果使用者未在分頁中放置游標，或指令碼未繫結至文件，則為 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|null：分頁的頁尾。

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`getFootnotes()`

擷取第一個分頁主體中的所有 Footnote 元素，或是擷取繫結至文件的指令碼所屬有效分頁主體中的所有 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|null - 分頁的標題。

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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()`

取得文件的語言代碼。這是文件編輯器「檔案」>「語言」中顯示的語言，可能與文件實際內容的語言不同。

回攻員

String|null：文件語言，如果未定義，則為 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 一樣。

參數

名稱	類型	說明
`id`	`String`	範圍的 ID，在分頁中不得重複。

回攻員

NamedRange|null - 具有指定 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。為避免指令碼之間發生非預期的衝突，建議您在範圍名稱加上專屬字串前置字元。

參數

名稱	類型	說明
`name`	`String`	範圍的名稱 (不一定不得重複)。

回攻員

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：代表使用者選取的內容，如果使用者未在分頁中選取任何內容、只選取段落結尾、只選取段落結尾和新行，或指令碼未繫結至文件，則為 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。可存取任何巢狀層級的分頁。

參數

名稱	類型	說明
`tabId`	`String`	要取得的分頁 ID。

回攻員

Tab|null：具有指定 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);

參數

名稱	類型	說明
`element`	`Element`	應包含新 `Position` 的元素；這必須是 `Text` 元素或容器元素 (例如 `Paragraph`)。
`offset`	`Integer`	如果是 `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。

如果是雲端硬碟檔案，系統也會從檢視者清單中移除使用者。

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`removeEditor(user)`

如果是雲端硬碟檔案，系統也會從檢視者清單中移除使用者。

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`removeViewer(emailAddress)`

從 Document 的觀眾和留言者清單中移除指定使用者。如果使用者是編輯者，而非檢視者或留言者，這個方法不會起任何作用。如果使用者屬於具有一般存取權的使用者類別 (例如 Document 與使用者的整個網域共用，或 Document 位於使用者可存取的共用雲端硬碟中)，這個方法也無法禁止使用者存取 Document。

如果是雲端硬碟檔案，系統也會從編輯者清單中移除使用者。

參數

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

回攻員

Document — This Document for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`removeViewer(user)`

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

如果是雲端硬碟檔案，系統也會從編輯者清單中移除使用者。

參數

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

回攻員

Document — This Document for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`saveAndClose()`

儲存目前的 Document。清除並套用待處理的更新。

指令碼執行完畢後，系統會自動為每個開啟的可編輯 saveAndClose() 叫用 Document 方法。

已結案的 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');

參數

名稱	類型	說明
`tabId`	`String`	要設為使用中的分頁 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);

參數

名稱	類型	說明
`position`	`Position`	新的游標位置。

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`setLanguage(languageCode)`

設定文件的語言代碼。這是文件編輯器「檔案」>「語言」中顯示的語言，可能與文件實際內容的語言不同。使用 getSupportedLanguageCodes() 取得所有有效的語言代碼。

參數

名稱	類型	說明
`languageCode`	`String`	語言代碼。

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

`setName(name)`

設定文件標題。

參數

名稱	類型	說明
`name`	`String`	新文件標題。

回攻員

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

參數

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

回攻員

Document — This Document, for chaining.

授權

使用這個方法的指令碼需要透過下列一或多個範圍授權：

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

Class Document 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

方法

內容詳盡的說明文件

addBookmark(position)

參數

回攻員

授權

addEditor(emailAddress)

參數

回攻員

授權

addEditor(user)

參數

回攻員

授權

addEditors(emailAddresses)

參數

回攻員

授權

addFooter()

回攻員

授權

addHeader()

回攻員

授權

addNamedRange(name, range)

參數

回攻員

授權

addViewer(emailAddress)

參數

回攻員

授權

addViewer(user)

參數

回攻員

授權

addViewers(emailAddresses)

參數

回攻員

授權

getActiveTab()

回攻員

授權

getAs(contentType)

參數

回攻員

getBlob()

回攻員

getBody()

回攻員

授權

getBookmark(id)

參數

回攻員

授權

getBookmarks()

回攻員

授權

getCursor()

回攻員

授權

getEditors()

回攻員

授權

getFooter()

回攻員

授權

getFootnotes()

回攻員

授權

getHeader()

回攻員

授權

getId()

回攻員

授權

getLanguage()

回攻員

授權

Class Document

`addBookmark(position)`

`addEditor(emailAddress)`

`addEditor(user)`

`addEditors(emailAddresses)`

`addFooter()`

`addHeader()`

`addNamedRange(name, range)`

`addViewer(emailAddress)`

`addViewer(user)`

`addViewers(emailAddresses)`

`getActiveTab()`

`getAs(contentType)`

`getBlob()`

`getBody()`

`getBookmark(id)`

`getBookmarks()`

`getCursor()`

`getEditors()`

`getFooter()`

`getFootnotes()`

`getHeader()`

`getId()`

`getLanguage()`

`getName()`

`getNamedRangeById(id)`

`getNamedRanges()`

`getNamedRanges(name)`

`getSelection()`

`getSupportedLanguageCodes()`

`getTab(tabId)`

`getTabs()`

`getUrl()`

`getViewers()`

`newPosition(element, offset)`

`newRange()`

`removeEditor(emailAddress)`

`removeEditor(user)`

`removeViewer(emailAddress)`

`removeViewer(user)`

`saveAndClose()`

`setActiveTab(tabId)`

`setCursor(position)`

`setLanguage(languageCode)`

`setName(name)`