Sekmelerle çalışma

Google Dokümanlar API'sı, dokümandaki herhangi bir sekmeden içeriğe erişmenize olanak tanır.

Sekme nedir?

Google Dokümanlar'da, sekmeler adında bir organizasyon katmanı bulunur. Dokümanlar, kullanıcıların tek bir sayfa içinde bir veya daha fazla sekme oluşturmasına olanak sağlar bugün E-Tablolar'da sekmelere benzer şekilde bir doküman oluşturabilirsiniz. Her sekmenin kendine ait başlık ve kimlik (URL'ye eklenir). Bir sekmede, alt sekmeler gibi alt sekmeler sekmeleri görebilirsiniz.

Alt sekmeler için API desteği şu anda sunulmaktadır ancak kullanıcı arayüzü desteği yakında sunulacaktır. Kodunuzdaki alt sekmeleri şu anda işleyebilirsiniz. Böylece, kullanıcı arayüzü desteği kullanıma sunulduğunda kod güncellemesi yapmanız gerekmez.

Doküman içeriğinin Doküman Kaynağında temsil edilme biçiminde yapılan yapısal değişiklikler

Eskiden dokümanlarda sekme kavramı yoktu. Bu yüzden Document Doğrudan kontrol edilen kaynak aşağıdaki alanları kullanarak tüm metin içeriklerini doldurur:

  • document.body
  • document.headers
  • document.footers
  • document.footnotes
  • document.documentStyle
  • document.suggestedDocumentStyleChanges
  • document.namedStyles
  • document.suggestedNamedStylesChanges
  • document.lists
  • document.namedRanges
  • document.inlineObjects
  • document.positionedObjects

Sekmelerin ek yapısal hiyerarşisi sayesinde, bu alanlar artık dokümanın tüm sekmelerindeki metin içeriğini anlamsal olarak temsil eder. İlgili içeriği oluşturmak için kullanılan metin tabanlı içerik artık farklı bir katmanda sunuluyor. Sekme özellikleri ve Google Dokümanlar'daki içeriğe bir liste olan documents.tabs ile erişilebilir Tabs. Her biri, yukarıda bahsedilen metin içeriği alanlarının tümünü içerir. Sonraki bölümlerde kısa bir genel bakış sunulmaktadır; "the" Sekme JSON gösterimi daha ayrıntılı bilgi sağlar.

Sekme özelliklerine erişme

Şu bilgileri içeren tab.tabProperties kullanarak sekme özelliklerine erişin: sekmenin kimliği, başlığı ve konumu olarak ayarlanır.

Sekme içindeki metin içeriğine erişme

Sekmedeki asıl doküman içeriği tab.documentTab olarak gösterilir. Tümü Söz konusu metin içeriği alanlarının tamamına tab.documentTab Örneğin, document.body yerine document.tabs[indexOfTab].documentTab.body.

Sekme hiyerarşisi

Alt sekmeler API'de Tab üzerinden bir tab.childTabs alanı olarak gösterilir. Bir dokümandaki tüm sekmelere erişmek için "ağaç"tan geçiş yapılması gerekir görebilirsiniz. Örneğin, aşağıdaki gibi bir sekme hiyerarşisi içeren bir dokümanı ele alalım:

Bazıları alt sekmelere sahip üç üst düzey sekme içeren sekme listesi kullanıcı arayüzü

body öğesini Sekme 3.1.2'den almak için document.tabs[2].childTabs[0].childTabs[1].documentTab.body. Örneğe göz atın yineleme için örnek kod sağlayan sonraki bölümde yer alan kod blokları bir dokümandaki tüm sekmelerde kullanılabilir.

Yöntemlerdeki değişiklikler

Sekmelerin kullanıma sunulmasıyla her doküman yönteminde birkaç değişiklik yapıldı. veya kodunuzu güncellemeniz gerekebilir.

documents.get

Varsayılan olarak tüm sekme içerikleri döndürülmez. Geliştiriciler, kodu kullanabilirsiniz. documents.get yöntemi, includeTabsContent parametresi, yanıtta tüm sekmeler sağlanır.

  • includeTabsContent, true olarak ayarlanırsa documents.get yöntemi, document.tabs alanı doldurulmuş bir Document kaynağı döndürür. Doğrudan document sayfasındaki tüm metin alanları (ör. document.body) boş olarak bırakılır.
  • includeTabsContent sağlanmazsa Document Kaynağındaki (ör. document.body) metin alanları yalnızca ilk sekmedeki içeriklerle doldurulur. document.tabs alanı boş olur ve diğer sekmelerdeki içerikler döndürülmez.

documents.create

documents.create yöntemi, Document doküman boş bırakılmış. Döndürülen Document Kaynak, hem dokümanın metin içeriği alanlarında hem de document.tabs.

document.batchUpdate

Her Request şunları içerir: güncellemelerin uygulanacağı sekmeleri belirtmenin bir yoludur. Bir sekmenin varsayılan olarak belirtildiğinde, Request, çoğunlukla destek kayıtları, dokümandaki ilk sekmeye uygulanır. ReplaceAllTextRequest, DeleteNamedRangeRequest, ve ReplaceNamedRangeContentRequest varsayılan olarak tüm sekmelere uygulanacak üç özel istektir.

Daha fazla bilgi için Request sn. dokümanlarına göz atabilirsiniz.

Kullanıcılar bir dokümandaki sekmelere, yer işaretlerine ve başlıklara dahili bağlantılar oluşturabilir. Kullanıma sunulan sekmeler özelliği sayesinde link.bookmarkId ve link.headingId alanları artık dokümandaki belirli bir sekme açılır.

Geliştiriciler, kodlarını link.bookmark ve Okuma ve yazma işlemlerinde link.heading. Dahili bağlantıları BookmarkLink ve Her biri HeadingLink nesne yer işareti veya başlığın kimliğini ve bulunduğu sekmenin kimliğini içeren inç Ayrıca link.tabId, sekmelere dahili bağlantılar gösterir.

documents.get yanıtının bağlantı içeriği de bağlı olarak değişiklik gösterebilir includeTabsContent parametresi:

  • includeTabsContent, true olarak ayarlanırsa tüm dahili bağlantılar gösterilir link.bookmark ve link.heading olarak. Eski alanlar (link.bookmarkId ve link.headingId) artık kullanılmayacak.
  • includeTabsContent sağlanmazsa tek bir sekme, o tek sekme içindeki yer işaretleri veya başlıkların dahili bağlantıları link.bookmarkId ve link.headingId olarak gösterilmeye devam eder. Dokümanlarda dahili bağlantılar link.bookmark olarak gösterilir ve link.heading.

document.batchUpdate ürününde, yer işareti veya başlığın sekme kimliğinden geldiği kabul edilir. Request Hiçbir sekme belirtilenden, dokümandaki ilk sekmeden olduğu kabul edilir.

İlgili içeriği oluşturmak için kullanılan Bağlantı JSON gösterimi, inceleyebilirsiniz.

Sekmelerin yaygın kullanım şekilleri

Aşağıdaki kod örneklerinde, sekmelerle etkileşimde bulunmanın çeşitli yolları açıklanmaktadır.

Dokümandaki tüm sekmelerden sekme içeriğini oku

Sekmeler özelliğinden önce bunu yapan mevcut kod destek ekibine taşınabilir IncludeTabsContent parametresini true değerine ayarlayarak ve sekme ağaç hiyerarşisi ve Tab ve DocumentTab dışı alıcı yöntemlerinin çağrılması yerine Document. Aşağıdaki kısmi kod örneği, Belgedeki metni çıkarın. Bir dokümanın her sekmesinde bulunan tüm metin içeriğinin nasıl yazdırılacağı gösterilir. Bu sekme geçiş kodu, tablodaki başka birçok kullanım alanına sekmelerin gerçek yapısına dikkat edin.

Java

/** 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) {
  ...
}

Dokümandaki ilk sekmeden sekme içeriğini oku

Bu işlem, tüm sekmeleri okumaya benzer.

Java

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

İlk sekmeyi güncelleme isteğinde bulunma

Aşağıdaki kısmi kod örneği, Request. Bu kod, Metin ekleme, silme ve taşıma Rehber.

Java

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