탭 작업

Google Docs API를 사용하면 문서의 어느 탭에서나 콘텐츠에 액세스할 수 있습니다.

탭이란 무엇인가요?

Google Docs에는 이라는 조직 레이어가 있습니다. 문서를 사용하면 사용자는 하나의 탭 안에 하나 이상의 탭을 만들 수 있습니다. 문서로 확인할 수 있습니다. 탭마다 자체적인 (URL에 추가됨) 탭에는 하위 탭도 있을 수 있으며, 다른 탭 아래에 중첩된 탭입니다.

하위 탭에 대한 API 지원은 현재 제공되지만 UI 지원은 곧 제공될 예정입니다. UI 지원이 시작될 때 코드를 추가로 업데이트하지 않아도 됩니다.

문서 리소스에 문서 콘텐츠가 표시되는 방식의 구조적 변경사항

과거에는 문서에 탭이라는 개념이 없었으므로 Document 리소스 직접 포함됨 모든 텍스트 콘텐츠를 다음 필드를 통해 전달합니다.

탭의 구조적 계층 구조가 추가되면서 이러한 필드는 더 이상 문서의 모든 탭에 있는 텍스트 콘텐츠를 의미론적으로 나타냅니다. 이 텍스트 기반 콘텐츠가 이제 다른 레이어에서 표현됩니다. 탭 속성 및 Google Docs도구의 콘텐츠에 액세스할 수 있는 사용자 document.tabsTab 객체(각각 에는 앞서 언급한 모든 텍스트 콘텐츠 필드가 포함됩니다. 이후 섹션에서는 간략한 개요 탭 JSON 표현 더 자세한 정보도 제공합니다

탭 속성 액세스

탭의 ID, 제목, 위치와 같은 정보가 포함된 tab.tabProperties를 사용하여 탭 속성에 액세스합니다.

탭 내의 텍스트 콘텐츠에 액세스

탭 내의 실제 문서 콘텐츠는 tab.documentTab 모두 tab.documentTab를 사용하여 앞서 언급한 텍스트 콘텐츠 필드에 액세스할 수 있습니다. 예를 들어 document.body를 사용하는 대신 document.tabs[indexOfTab].documentTab.body입니다.

탭 계층 구조

하위 탭은 API에서 tab.childTabs 필드 사용 Tab 탭의 모든 탭에 액세스 문서의 '트리'를 순회해야 함 하위 탭의 예를 들어 문서를 참조하세요.

3개의 최상위 탭이 포함된 탭 목록 UI(일부에는 하위 탭이 있음)

Body 가져오기 탭 3.1.2에서 document.tabs[2].childTabs[0].childTabs[1].documentTab.body 샘플 보기 코드 블록은 반복을 위한 샘플 코드를 제공합니다. 문서 전체의 내용을 볼 수 있습니다.

메서드 변경사항

탭을 도입하면서 각 문서 메서드에는 몇 가지 변경사항이 있습니다. 코드를 업데이트해야 할 수 있습니다.

documents.get

기본적으로 모든 탭 콘텐츠가 반환되지는 않습니다. 개발자는 모든 탭에 액세스할 수 있도록 코드를 업데이트해야 합니다. 이 documents.get 메서드는 다음 URL의 콘텐츠를 구성할 수 있는 includeTabsContent 매개변수입니다. 응답에서 모든 탭이 제공됩니다

  • includeTabsContenttrue로 설정된 경우 documents.get 메서드가 다음을 반환합니다. 다음과 같은 Document 리소스 document.tabs 필드가 채워졌습니다. document에 있는 모든 텍스트 입력란 직접 (예: document.body)는 비워 둡니다.
  • includeTabsContent가 제공되지 않으면 Document 리소스의 텍스트 필드 (예: document.body)는 첫 번째 탭의 콘텐츠로만 채워집니다. document.tabs 필드는 비어 있고 다른 탭의 콘텐츠는 반환되지 않습니다.

documents.create

documents.create 메서드 은 Document 리소스를 반환합니다. 는 생성된 빈 문서를 나타냅니다. 반환된 Document 리소스가 문서의 텍스트 콘텐츠 필드와 document.tabs입니다.

document.batchUpdate

Request에는 업데이트를 적용할 탭을 지정하는 방법이 있습니다. 기본적으로 탭에 지정하면 Request이(가) 대부분 케이스가 문서의 첫 번째 탭에 적용됩니다 ReplaceAllTextRequest님, DeleteNamedRangeRequest, 및 ReplaceNamedRangeContentRequest 세 개의 특별 요청으로, 대신 모든 탭에 기본적으로 적용됩니다.

자세한 내용은 Request초 문서를 참조하세요.

사용자는 문서에 탭, 북마크, 제목으로 연결되는 내부 링크를 만들 수 있습니다. 탭 기능의 도입으로 link.bookmarkIdlink.headingId 필드 Link 리소스를 더 이상 사용할 수 없음 문서의 특정 탭에 있는 북마크나 제목을 나타냅니다.

개발자는 link.bookmark 및 읽기 및 쓰기 작업의 link.heading 내부 링크를 노출하기 위해 BookmarkLink 및 각각 HeadingLink 객체 포함된 탭의 ID와 북마크 또는 제목의 ID 포함 인치 또한 link.tabId는 탭에 내부 링크를 노출합니다.

documents.get의 콘텐츠 연결 응답은 includeTabsContent 매개변수에 따라서도 달라질 수 있습니다.

  • includeTabsContenttrue로 설정하면 모든 내부 링크가 노출됩니다. link.bookmarklink.heading으로. 기존 필드는 더 이상 사용되지 않습니다.
  • includeTabsContent가 제공되지 않으면 단일 탭, 단일 탭 내의 북마크 또는 제목으로 연결되는 내부 링크 계속해서 link.bookmarkIdlink.headingId로 노출됩니다. 문서 내 여러 탭이 포함된 경우 내부 링크는 link.bookmark으로 표시되며 link.heading입니다.

document.batchUpdate에서 기존 필드 중 하나를 사용하여 내부 링크를 만든 경우 북마크 또는 제목은 Request 탭이 없으면 문서의 첫 번째 탭에서 가져온 것으로 간주됩니다.

링크 JSON 표현은 확인할 수 있습니다.

탭의 일반적인 사용 패턴

다음 코드 샘플은 탭과 상호작용하는 다양한 방법을 설명합니다.

문서의 모든 탭에서 탭 콘텐츠 읽기

탭 기능이 도입되기 전에 이를 실행했던 기존 코드는 includeTabsContent 매개변수를 true로 설정하고, 탭 트리 계층 구조를 탐색하고, Document 대신 TabDocumentTab에서 getter 메서드를 호출하여 탭을 지원하도록 이전할 수 있습니다. 다음은 코드 샘플은 문서에서 텍스트를 추출합니다. 표시 문서의 모든 탭에서 모든 텍스트 내용을 인쇄하는 방법에 대해 알아보겠습니다. 현재 탭 순회 코드는 확인할 수 있습니다.

자바

/** Prints all text contents from all tabs in the document. */
static void printAllText(Docs service, String documentId) throws IOException {
  // Fetch the document with all of the tabs populated, including any nested
  // child tabs.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  List<Tab> allTabs = getAllTabs(doc);

  // Print the content from each tab in the document.
  for (Tab tab: allTabs) {
    // Get the DocumentTab from the generic Tab.
    DocumentTab documentTab = tab.getDocumentTab();
    System.out.println(
        readStructuralElements(documentTab.getBody().getContent()));
  }
}

/**
 * Returns a flat list of all tabs in the document in the order they would
 * appear in the UI (top-down ordering). Includes all child tabs.
 */
private List<Tab> getAllTabs(Document doc) {
  List<Tab> allTabs = new ArrayList<>();
  // Iterate over all tabs and recursively add any child tabs to generate a
  // flat list of Tabs.
  for (Tab tab: doc.getTabs()) {
    addCurrentAndChildTabs(tab, allTabs);
  }
  return allTabs;
}

/**
 * Adds the provided tab to the list of all tabs, and recurses through and
 * adds all child tabs.
 */
private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) {
  allTabs.add(tab);
  for (Tab tab: tab.getChildTabs()) {
    addCurrentAndChildTabs(tab, allTabs);
  }
}

/**
 * Recurses through a list of Structural Elements to read a document's text
 * where text may be in nested elements.
 *
 * <p>For a code sample, see
 * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract
 * the text from a document</a>.
 */
private static String readStructuralElements(List<StructuralElement> elements) {
  ...
}

문서의 첫 번째 탭에서 탭 콘텐츠 읽기

이는 모든 탭을 읽는 것과 비슷합니다.

자바

/** Prints all text contents from the first tab in the document. */
static void printAllText(Docs service, String documentId) throws IOException {
  // Fetch the document with all of the tabs populated, including any nested
  // child tabs.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  List<Tab> allTabs = getAllTabs(doc);

  // Print the content from the first tab in the document.
  Tab firstTab = allTabs.get(0);
  // Get the DocumentTab from the generic Tab.
  DocumentTab documentTab = firstTab.getDocumentTab();
  System.out.println(
      readStructuralElements(documentTab.getBody().getContent()));
}

첫 번째 탭 업데이트 요청하기

다음의 일부 코드 샘플은 Request에서 특정 탭을 타겟팅하는 방법을 보여줍니다. 이 코드 의 표본을 기반으로 하며 텍스트 삽입, 삭제, 이동 가이드.

자바

/** Inserts text into the first tab of the document. */
static void insertTextInFirstTab(Docs service, String documentId)
    throws IOException {
  // Get the first tab's ID.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  Tab firstTab = doc.getTabs().get(0);
  String tabId = firstTab.getTabProperties().getTabId();

  List<Request>requests = new ArrayList<>();
  requests.add(new Request().setInsertText(
      new InsertTextRequest().setText(text).setLocation(new Location()
                                                            // Set the tab ID.
                                                            .setTabId(tabId)
                                                            .setIndex(25))));

  BatchUpdateDocumentRequest body =
      new BatchUpdateDocumentRequest().setRequests(requests);
  BatchUpdateDocumentResponse response =
      docsService.documents().batchUpdate(DOCUMENT_ID, body).execute();
}