含有 RTF 格式和元素 (例如表格和清單) 的文件。
您可以使用 DocumentApp
開啟或建立文件。
// Open a document by ID. var doc = DocumentApp.openById("<my-id>"); // Create and open a document. doc = DocumentApp.create("Document Title");
方法
內容詳盡的說明文件
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('abc123456'); // Gets the document 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)
addEditor(user)
addEditors(emailAddresses)
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('abc123456'); // Adds a header to the document. 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
。名稱不一定是唯一的;同一份文件中不同的範圍可能會共用相同的名稱,就像 HTML 中的類別一樣。相反地,ID 是文件中的不重複 ID,例如 HTML 中的 ID。將 NamedRange
新增至文件後即無法修改,只能移除。
存取文件的任何指令碼皆可存取 NamedRange
。為避免指令碼之間出現意外衝突,請考慮在範圍名稱前加上不重複的字串。
// Creates a named range that includes every table in the document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.getBody().getTables(); for (var i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } 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)
addViewer(user)
addViewers(emailAddresses)
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('abc123456'); // 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' 。 |
回攻員
Blob
— 目前的文件為 blob。
getBlob()
將目前的 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('abc123456'); // Retrieves the current document's contents as a blob and logs it to the console. console.log(doc.getBlob().getContentType());
回攻員
Blob
— 目前的文件為 blob。
getBody()
擷取使用中文件的 Body
。
文件可能包含不同類型的章節 (例如 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('abc123456'); // Gets the document 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
。如果沒有這類 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('abc123456'); // Gets the bookmark by its ID. 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
:具有指定 ID 的 Bookmark
,如果不存在這類 Bookmark
,則為 null
。
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getBookmarks()
取得文件中的所有 Bookmark
物件。
// 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('abc123456'); // Gets all of the bookmarks in the document. const bookmarks = doc.getBookmarks(); // Logs the number of bookmarks in the document 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. var 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. var 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()
getFootnotes()
擷取文件內文中的所有 Footnote
元素。
呼叫 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('abc123456'); // Gets the first footnote. 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()
擷取文件的標題區段 (如果有的話)。
// 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('abc123456'); // Gets the text of the document'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
。如果沒有這類 NamedRange
,這個方法會傳回 null
。名稱不一定是唯一的;同一個文件中的不同範圍可能會共用相同名稱,就像 HTML 中的類別一樣。相對地,ID 是文件中的不重複 ID,例如 HTML 中的 ID。
參數
名稱 | 類型 | 說明 |
---|---|---|
id | String | 範圍的 ID,在文件中不得重複 |
回攻員
NamedRange
:具有指定 ID 的 NamedRange
,如果不存在此範圍,則為 null
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getNamedRanges()
取得文件中的所有 NamedRange
物件。
存取文件的任何指令碼都可存取 NamedRange
。為避免指令碼之間出現非預期的衝突,建議您在範圍名稱前面加上不重複的字串。
回攻員
NamedRange[]
:文件中 NamedRange
物件的陣列,可能包括多個名稱相同的範圍
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
getNamedRanges(name)
取得文件中所有具有指定名稱的 NamedRange
物件。名稱可以重複;同一份文件中的多個不同範圍可能會共用相同名稱,就像 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. var selection = DocumentApp.getActiveDocument().getSelection(); if (selection) { var 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
getUrl()
擷取網址以存取目前的文件。
var 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()
newPosition(element, offset)
建立新的 Position
,這是相對於文件中特定元素的位置參照。使用者的遊標會以 Position
表示,以及其他用途。
// Append a paragraph, then place the user's cursor after the first word of the new paragraph. var doc = DocumentApp.getActiveDocument(); var paragraph = doc.getBody().appendParagraph('My new paragraph.'); var 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
物件。
// Change the user's selection to a range that includes every table in the document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.getBody().getTables(); for (var 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 | 要移除的使用者電子郵件地址。 |
回攻員
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeEditor(user)
將指定使用者從 Document
的編輯者清單中移除。如果使用者屬於具備一般存取權的使用者類別,此方法不會禁止使用者存取 Document
。舉例來說,如果 Document
是與使用者整個網域共用,或是 Document
位於該使用者可存取的共用雲端硬碟中,則他們無法這麼做。
若是雲端硬碟檔案,則也會將使用者從檢視者清單中移除。
參數
名稱 | 類型 | 說明 |
---|---|---|
user | User | 代表要移除的使用者。 |
回攻員
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(emailAddress)
將特定使用者從「Document
」的檢視者和加註者清單中移除。如果使用者是編輯者,而非檢視者或加註者,這個方法就不會生效。此外,假如使用者屬於具有一般存取權的使用者類別,例如 Document
已與使用者的整個網域共用,或 Document
位於該使用者可存取的共用雲端硬碟中,此方法也不會阻止使用者存取 Document
。
針對雲端硬碟檔案,這麼做也會將使用者從編輯者清單中移除。
參數
名稱 | 類型 | 說明 |
---|---|---|
emailAddress | String | 要移除的使用者電子郵件地址。 |
回攻員
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
removeViewer(user)
將特定使用者從「Document
」的檢視者和加註者清單中移除。如果使用者是編輯者,而不是檢視者,這個方法就不會生效。如果使用者屬於具有一般存取權的使用者類別,此方法也不會禁止使用者存取 Document
。例如,假設 Document
是與使用者整個網域共用,或是 Document
位於該使用者可存取的共用雲端硬碟中。
針對雲端硬碟檔案,這麼做也會將使用者從編輯者清單中移除。
參數
名稱 | 類型 | 說明 |
---|---|---|
user | User | 代表要移除的使用者。 |
回攻員
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
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
setCursor(position)
根據 Position
,在使用中的文件中設定使用者的遊標。指令碼只能存取執行指令碼的使用者遊標,且只有在指令碼繫結至文件時。
// Append a paragraph, then place the user's cursor after the first word of the new paragraph. var doc = DocumentApp.getActiveDocument(); var paragraph = doc.getBody().appendParagraph('My new paragraph.'); var position = doc.newPosition(paragraph.getChild(0), 2); doc.setCursor(position);
參數
名稱 | 類型 | 說明 |
---|---|---|
position | Position | 新的遊標位置 |
回攻員
Document
— 此 Document
,用於鏈結
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setLanguage(languageCode)
設定文件的語言代碼。這是文件編輯器的「File」(檔案) >「Language」(語言) 中顯示的語言,不一定是文件的實際語言。請使用 getSupportedLanguageCodes()
取得所有有效的語言代碼。
參數
名稱 | 類型 | 說明 |
---|---|---|
languageCode | String | 語言代碼。 |
回攻員
Document
— 此 Document
用於鏈結。
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents
setName(name)
setSelection(range)
根據 Range
,設定使用者在使用中的文件中選取項目。指令碼只能存取執行指令碼的使用者選取項目,且只有在指令碼繫結至文件時。
// Change the user's selection to a range that includes every table in the document. var doc = DocumentApp.getActiveDocument(); var rangeBuilder = doc.newRange(); var tables = doc.getBody().getTables(); for (var i = 0; i < tables.length; i++) { rangeBuilder.addElement(tables[i]); } doc.setSelection(rangeBuilder.build());
參數
名稱 | 類型 | 說明 |
---|---|---|
range | Range | 可供選取的新元素範圍 |
回攻員
Document
— 此 Document
,用於鏈結
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/documents.currentonly
-
https://www.googleapis.com/auth/documents