Работа с Съдържание

Често ще работите с документи, съдържащи съдържание (TOC). Използване Aspose.Words можете да поставите своя собствена таблица със съдържание или напълно да възстановите съществуващото съдържание в документа само с няколко реда код.

Тази статия очертава как да работите с полето на съдържанието и показва:

• Как да поставите чисто нов TOC.
• Обновяване на нови или съществуващи TOS в документа.
• Посочете превключватели, за да контролира форматирането и цялостната структура на TOC.
• Как да промените стиловете и външния вид на съдържанието.
• Как да премахнете цяло TOC поле заедно с всички записи от документа.

Вмъкване на програмно съдържание

Можете да поставите TOC (таблица със съдържание) полето в документа на текущата позиция, като се нарича InsertTableOfContents метод.

Съдържанието в документ на Word може да бъде изградено по няколко начина и форматирано чрез различни варианти. Полето превключва към метода за управление на начина, по който масата е изградена и показана във вашия документ.

По подразбиране превключвателите, които се използват в a TOC вложено в Microsoft Word аз ". Описание на тези ключове, както и списък на поддържаните ключове могат да бъдат намерени по-късно в статията. Можете да използвате това ръководство, за да получите правилните ключове или ако вече имате документ, съдържащ подобни TOC че искате да покажете кода на полето (ALT+F9) и да копирате превключвателите директно от полето.

Следният пример за код показва как да се вмъкне полето за съдържание в документ:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table of contents at the beginning of the document.
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

// The newly inserted table of contents will be initially empty.
// It needs to be populated by updating the fields in the document.
doc.updateFields();

doc.save(dataDir + "InsertATableOfContentsField_out.docx");

Следният пример за код показва как да се въведе таблица със съдържание (TOC) в документ, като се използват стилове на заглавие като записи:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

// Create a document builder to insert content with into document.
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a table of contents at the beginning of the document.
builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");

// Start the actual document content on the second page.
builder.insertBreak(BreakType.PAGE_BREAK);

// Build a document with complex structure by applying different heading styles thus creating TOC entries.
builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);

builder.writeln("Heading 1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);

builder.writeln("Heading 1.1");
builder.writeln("Heading 1.2");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);

builder.writeln("Heading 2");
builder.writeln("Heading 3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);

builder.writeln("Heading 3.1");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);

builder.writeln("Heading 3.1.1");
builder.writeln("Heading 3.1.2");
builder.writeln("Heading 3.1.3");

builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);

builder.writeln("Heading 3.2");
builder.writeln("Heading 3.3");

// Call the method below to update the TOC.
doc.updateFields();

doc.save(dataDir + "InsertATableOfContentsUsingHeadingStyles_out.docx");

Кодът показва, че новата таблица със съдържание се вмъква в празен документ. На DocumentBuilder класът се използва за въвеждане на форматиране на съдържанието на пробата с подходящи стилове на заглавие, които се използват за отбелязване на съдържанието, което да бъде включено в TOC. Следващите редове след това населяват TOC чрез актуализиране на полетата и оформлението на страницата на документа.

Без използваните в примера методи, когато отворите изходния документ, ще откриете TOC поле, но без видимо съдържание. Това е защото TOC полето е вмъкнато, но все още не е населено, докато не бъде актуализирано в документа. Допълнителна информация за това се обсъжда в следващия раздел.

Обновяване на съдържанието

Aspose.Words Ви позволява да актуализирате напълно TOC само с няколко реда код. Това може да се направи, за да се населят нововъведени TOC или да актуализира съществуващо TOC след извършване на промени в документа.

Следните два метода трябва да се използват за актуализиране на TOC полета в документа:

1. Document.updateFields()
2. Document.updatePageLayout()

Моля, имайте предвид, че тези два метода за актуализация трябва да бъдат призовани в този ред. Ако бъде обърнато, съдържанието ще бъде населено, но няма да се показват номерата на страниците. Може да бъде актуализиран всеки брой различни ТОК. Тези методи автоматично ще обновят всички TOS намерени в документа.

Следният пример за код показва как да се възстанови напълно TOC полета в документа като се позовава на актуализации на полето:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
doc.updateFields();

Първото обаждане Document.updateFields() ще изгради TOC Всички текстови записи са населени и TOC Изглежда почти завършен. Единственото нещо, което липсва, е номерата на страниците, които засега се показват с гол?.

Второто обаждане до Document.updatePageLayout() ще изгради оформлението на документа в памет. Това трябва да се направи, за да се съберат номерата на страниците на вписванията. Правилните номера на страниците, изчислени от това обаждане, след това се добавят в ТОН.

Използване на превключватели за контрол на съдържанието

Както при всяко друго поле, TOC полето може да приема превключватели, определени в кода на полето, които контролират начина на изграждане на съдържанието. Някои превключватели се използват за контрол кои записи са включени и на какво ниво, докато други се използват за контрол на външния вид на TOC. Превключвателите могат да се комбинират заедно, за да се даде възможност за производство на сложна таблица със съдържание.

По подразбиране тези превключватели са включени при поставяне по подразбиране TOC в документа. A TOC без превключватели ще включва съдържание от вградените стилове на заглавие (като че ли \O превключвател е настроен).

Наличните TOC превключватели, които се поддържат от Aspose.Words са изброени по-долу и тяхната употреба е описана подробно. Те могат да бъдат разделени на отделни секции въз основа на техния тип. Превключвателите в първия раздел определят какво съдържание да се включи в TOC и превключвателите във втория раздел контролират външния вид на TOC.

Ако превключвателят не е записан тук, в момента не се поддържа. Всички ключове ще бъдат поддържани в бъдещи версии. Добавяме допълнителна подкрепа към всяко освобождаване.

Превключватели

Превключване

Описание

Heading Styles *(\O Switch) *

Този превключвател определя, че TOC трябва да бъде изграден от вградените стилове. В Microsoft Word, Те се определят от No 1 год. 9. Aspose.Words Тези стилове са представени от съответния StyleIdentifier изброяване. Това изброяване представлява локален независим идентификатор на стил, например, StyleIdentifier.Heading1 представлява стила на функция 1. Чрез това форматирането и свойствата на стила могат да бъдат извлечени от колекцията стил на документа. Съответният клас стил може да бъде извлечен от Document.Styles събиране чрез използване на индексиран имот от тип StyleIdentifier.


Всяко съдържание, форматирано с тези стилове, е включено в съдържанието. Нивото на заглавието ще определи съответното йерархично ниво на вписването в TOC. Например параграф със стил "No 1" ще бъде третиран като първо ниво `TOC` като има предвид, че параграф с функция 2 ще се разглежда като следващото ниво в йерархията и така нататък.

| | **Outline Levels**
*(\U превключвател) *
|

Всеки параграф може да определи ниво на очертания съгласно опциите по параграф.


Тази настройка определя на кое ниво трябва да се разглежда този параграф в йерархията на документите. Това е често използвана практика, използвана за лесно структуриране на оформлението на документ. Тази йерархия може да се разглежда чрез промяна в Outline View в Microsoft Word. Подобно на заглавията стилове, може да има 1 по 9 очертания нива, в допълнение към нивото на Body текст. Outline нива 1 по 9 ще се появи в `TOC` на съответното ниво на йерархията
Всяко съдържание с ниво на очертания, определено в стила на параграфа или директно на самия параграф, е включено в ТОС. В Aspose.Words нивото на контура е представено от `ParagraphFormat.OutlineLevel` собственост на възела на §. Обосновката на стила на параграфа е представена по същия начин от `Style.ParagraphFormat` собственост.

Имайте предвид, че вградените стилове на заглавие като функция 1 имат задължително ниво на очертание в настройките на стила.

| | **Custom Styles**
*(\T превключвател) *
|

Този превключвател ще позволи използването на потребителски стилове при събиране на записи, които да се използват в TOC. Това често се използва в комбинация с \O превключвател, за да включва потребителски стилове заедно с вградени заглавия стилове в TOC.
Параметрите на превключвателя трябва да бъдат затворени в говорните знаци. Много потребителски стилове могат да бъдат включени, за всеки стил, името трябва да бъде посочено следвано от запетая последвано от нивото, че стилът трябва да се появи в `TOC` Като. По-нататъшните стилове също са разделени от запетая, както добре.
Например

{ TOC \o "1-3" \t "CustomHeading1, 1,   CustomHeading2, 2"}

ще използва съдържание, стилирано с CustomHeading1 като съдържание от ниво 1 в `TOC` и Custom Heading2 като ниво 2.

| | Използване на TC полета
*(\F и \L превключватели) *
|

В по- стари версии на Microsoft Word, единственият начин да се изгради `TOC` е използването на TC полета. Тези полета се вкарват скрити в документа дори когато се показват кодовете на полетата. Те включват текста, който трябва да бъде показан във вписването и `TOC` е построен от тях. Тази функционалност сега не се използва много често, но все още може да бъде полезно в някои случаи да се включат записи в `TOC` които не се виждат в документа.
При въвеждането на тези полета се появяват скрити дори когато се показват кодове на полета. Те не могат да бъдат видени без да покажат скрито съдържание. За да видите тези полета, трябва да изберете форматиране на параграфа.


Тези полета могат да бъдат включени в документ на всяка позиция като всяко друго поле и са представени от `FieldType.FieldTOCEntry` Изброяване.
Превключвателят \F в a `TOC` се използва за уточняване, че полетата TC следва да се използват като вписвания. Самият превключвател без допълнителен идентификатор означава, че всяко поле на TC в документа ще бъде включено. Всеки допълнителен параметър, често една буква, ще посочи, че само TC полета, които имат съвпадение \f превключвател ще бъдат включени в TOC. Например *

{ TOC \f t }

ще включва само TC полета като

{ TC \f t }

На `TOC` полето също така има свързан превключвател, прекъсвача. .. .. ..


На `TC` Самите полета също могат да имат `{several, multiple, a few, many, numerous}` Включете прекъсвачите. Това са:

Обяснено по-горе. *

- \L го определя кое ниво в `TOC` Това поле ще се появи. A `TOC` който използва същия превключвател, ще включва това поле на TC само ако е в рамките на определения обхват.

- _\ N\ N\ Номерирането на страницата за това `TOC` записът не е показан. В следващия раздел може да бъде намерен примерен код за въвеждане на полетата TC.

|

Външни прекъсвачи

Превключване	Описание
Omit Page Numbers *(\N Switch) *	Този превключвател се използва за скриване на номерата на страниците за определени нива на TOC. Например, можете да определите

{TOC \o "1-4" \n "3-4" }

и номерата на страниците на влизанията на нива 3 и 4 ще бъдат скрити заедно с лидерските точки (ако има такива). За да се определи само едно ниво на диапазон все още трябва да се използва, например, да се изключат номера на страници само за първото ниво.
Доставянето на обхват на ниво няма да пропусне номерата на страниците за всички нива в TOC. Това е полезно за задаване при експортиране на документ в HTML или подобен формат. Това е така, защото HTML базирани формати не са никаква концепция страница и по този начин не се нуждаят от всяка страница номерация.


| | Вмъкване като хипервръзки
*(\H Switch) * |

Този ключ посочва, че `TOC` вписванията се вмъкват като хипервръзки. При разглеждане на документ в Microsoft Word Тези записи все още ще се появяват като нормален текст вътре в `TOC` но са хипервръзки и по този начин може да се използва за навигация към позицията на оригиналния запис в документа, като се използва *Ctrl + Left Click* in Microsoft Word. Когато този превключвател е включен, тези връзки се запазват и в други формати. Например, в HTML базирани формати, включително EPUB и превърнати формати като PDF и XPS, те ще бъдат изнесени като работни връзки.
Без този ключ, `TOC` във всички тези изходи ще бъдат изнесени като обикновен текст и няма да демонстрират това поведение. Ако документът е отворен в MS Word, текстът на вписванията също няма да може да бъде натиснат по този начин, но номерата на страниците все още могат да бъдат използвани за навигация към оригиналния запис.


| | **Set Separator Character**
*(\P Switch) *
|

Този превключвател позволява лесно да се промени съдържанието, разделящо заглавието на входната и страница. Сепараторът, който трябва да се използва, трябва да се посочи след този превключвател и да се постави в говорни знаци.
Противно на това, което е документирано в Office документация, може да се използва само един символ вместо до пет. Това важи както за MS Word, така и Aspose.Words.
Използването на този превключвател не се препоръчва, тъй като не позволява много контрол върху това, което използва за разделяне на записи и номера на страници в TOC. Вместо това се препоръчва да се редактира подходящо `TOC` стил като `StyleIdentifier.TOC1` и от там редактирайте стила на лидера с достъп до конкретни членове на шрифта и др. Повече подробности за това как да направите това може да се намери по-късно в статията.


| | **Preserve Tab Entries**
*(\W Switch) * |

Използването на този превключвател ще уточни, че всички записи, които имат символ подпрозорец, например заглавие, което има подпрозорец в края на линията, ще бъдат запазени като подходящ символ подпрозорец при населяването на TOC. Това означава, че функцията на символа подпрозорец ще присъства в `TOC` и може да се използва за форматиране на текста. Например, някои записи могат да използват спирания на подпрозорците и таб символите, за да разгърнат равномерно текста. Докато съответният `TOC` ниво определя еквивалентния раздел спира след това генерираното `TOC` Записите ще се появят с подобно разстояние.

В същата ситуация, ако този превключвател не е определен, символите на раздела ще бъдат преобразувани в еквивалент на бяло пространство като нефункциониращи раздели. Изходът тогава няма да изглежда както се очакваше.


| | **Preserve New Line Entries**
*(\X Switch) *
|

Подобно на превключвателя по-горе, този превключвател посочва, че позиции, простиращи се по няколко линии (с използване на нови символи, а не на отделни точки) ще бъдат запазени, тъй като те са в генерираната TOS. Например позиция, която трябва да се разпространи по няколко линии, може да използва новия символ на линия (Ctrl + Enter или `ControlChar.LineBreak`) да разделят съдържанието през различни линии. С този ключ, посочен, записът в `TOC` ще запази тези нови символи линия, както е показано по-долу.

В тази ситуация, ако превключвателят не е определен, тогава новите символи на линия се преобразуват в едно бяло пространство.


|

Вмъкване на полета TC

Можете да поставите ново TC поле на текущата позиция на DocumentBuilder като се обадя на DocumentBuilder.InsertField метод и определяне на името на полето като .TC.. заедно с всички ключове, които са необходими.

Следният пример с код показва как да поставите a TC поле в документа, като се използва DocumentBuilder.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
Document doc = new Document();

// Create a document builder to insert content with.
DocumentBuilder builder = new DocumentBuilder(doc);

// Insert a TC field at the current document builder position.
builder.insertField("TC \"Entry Text\" \\f t");

Често определен ред от текста е определен за TOC и е маркиран с TC Поле. Лесният начин да направите това в MS Word е да подчертаете текста и натиснете ALT+SHIFT+O. Това автоматично създава TC поле с помощта на избрания текст. Същата техника може да се постигне чрез код. Кодът по-долу ще намерите текст, съответстващ на входа и вмъкване на TC поле в същата позиция като текста. Кодът се основава на същата техника, използвана в статията. Следният пример с код показва как да намерите и въведете TC поле в текста в документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
class InsertTCFieldHandler implements IReplacingCallback {
    // Store the text and switches to be used for the TC fields.
    private String mFieldText;
    private String mFieldSwitches;

    /**
     * The switches to use for each TC field. Can be an empty string or null.
     */
    public InsertTCFieldHandler(String switches) throws Exception {
        this(null, switches);
    }

    /**
     * The display text and the switches to use for each TC field. Display text
     * Can be an empty string or null.
     */
    public InsertTCFieldHandler(String text, String switches) throws Exception {
        mFieldText = text;
        mFieldSwitches = switches;
    }

    public int replacing(ReplacingArgs args) throws Exception {
        // Create a builder to insert the field.
        DocumentBuilder builder = new DocumentBuilder((Document) args.getMatchNode().getDocument());
        // Move to the first node of the match.
        builder.moveTo(args.getMatchNode());

        // If the user specified text to be used in the field as display text then use that, otherwise use the
        // match string as the display text.
        String insertText;

        if (!(mFieldText == null || "".equals(mFieldText)))
            insertText = mFieldText;
        else
            insertText = args.getMatch().group();

        // Insert the TC field before this node using the specified string as the display text and user defined switches.
        builder.insertField(java.text.MessageFormat.format("TC \"{0}\" {1}", insertText, mFieldSwitches));

        // We have done what we want so skip replacement.
        return ReplaceAction.SKIP;
    }

}

Промяна на съдържанието

Промяна формата на стиловете

Форматиране на записите в TOC не използва оригиналните стилове на маркираните вписвания, вместо това всяко ниво се форматира с еквивалентен TOC стил. Например, първото ниво в TOC е форматиран с TOC1 стил, на второ ниво, форматиран с TOS2 стил и така нататък. Това означава, че за да промените външния вид на TOC Тези стилове трябва да бъдат променени. В Aspose.Words Тези стилове са представени от местното-независимо StyleIdentifier.TOC1 през до StyleIdentifier.TOC9 и могат да бъдат извлечени от Document.Styles събиране с помощта на тези идентификатори.

След като подходящият стил на документа е възстановен форматирането за този стил може да бъде променено. Всички промени в тези стилове автоматично ще бъдат отразени в TOCs в документа.

Следният пример за код променя форматиращ имот, използван на първо ниво TOC стил.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
public static void changeAFormattingPropertyUsedInFirstLevelTOCStyle() throws Exception {
    Document doc = new Document();
    // Retrieve the style used for the first level of the TOC and change the formatting of the style.
    doc.getStyles().getByStyleIdentifier(StyleIdentifier.TOC_1).getFont().setBold(true);
}

Също така е полезно да се отбележи, че всяко пряко форматиране на параграф (определено на самия параграф, а не в стила), което трябва да бъде включено в TOC ще бъде копирано във вписването в TOC. Например, ако стилът “No 1” се използва за отбелязване на съдържанието TOC и този стил има смел форматиране, докато параграфът също има италиански формат, директно приложен към него. Резултатът TOC Влизането няма да бъде смело, тъй като това е част от форматирането на стила, но ще бъде италитично, тъй като това е директно форматирано на параграфа.

Можете също така да контролирате форматирането на използваните разделители между всеки запис и номера на страницата. По подразбиране, това е пунктирана линия, която се разпространява в страницата номериране с помощта на символ подпрозорец и десен раздел стоп подредени в близост до десния марж.

Използване на Style клас, получен за конкретния случай TOC ниво, което искате да промените, можете също така да промените начина, по който те се появяват в документа.

Да се промени как това се появява първо Style.ParagraphFormat трябва да бъдат призовани да възстановят формата на параграфа за стила. От това, табът спира, като се обажда ParagraphFormat.TabStops и съответната таблица стоп променени. Използването на същата техника самата таб може да се премести или премахне напълно.

Следният пример за код показва как да се промени позицията на десния раздел стоп в TOC свързаните параграфи.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
public static void modifyPositionOfRightTabStopInTOC() throws Exception {
    Document doc = new Document(dataDir + "Field.TableOfContents.doc");

    // Iterate through all paragraphs in the document
    for (Paragraph para : (Iterable<Paragraph>) doc.getChildNodes(NodeType.PARAGRAPH, true)) {
        // Check if this paragraph is formatted using the TOC result based styles. This is any style between TOC and TOC9.
        if (para.getParagraphFormat().getStyle().getStyleIdentifier() >= StyleIdentifier.TOC_1 && para.getParagraphFormat().getStyle().getStyleIdentifier() <= StyleIdentifier.TOC_9) {
            // Get the first tab used in this paragraph, this should be the tab used to align the page numbers.
            TabStop tab = para.getParagraphFormat().getTabStops().get(0);
            // Remove the old tab from the collection.
            para.getParagraphFormat().getTabStops().removeByPosition(tab.getPosition());
            // Insert a new tab using the same properties but at a modified position.
            // We could also change the separators used (dots) by passing a different Leader type
            para.getParagraphFormat().getTabStops().add(tab.getPosition() - 50, tab.getAlignment(), tab.getLeader());
        }
    }

    doc.save(dataDir + "Field.TableOfContentsTabStops_Out.doc");
}

Премахване на съдържанието от документа

Съдържанието може да бъде премахнато от документа чрез премахване на всички намерени възли между FieldStart и Field End възел на TOC Поле.

Кодът по-долу показва това. Премахване на TOC Полето е по-просто от обикновено поле, тъй като не следим гнездата на полетата. Вместо това, ние проверяваме FieldEnd Възелът е от тип FieldType.FieldTOC Което означава, че сме се сблъскали с края на сегашния TOC. Тази техника може да се използва в този случай, без да се притеснявате за всяко гнездо полета, тъй като ние можем да приемем, че всеки правилно формиран документ няма да има напълно гнездо TOC поле вътре в друго TOC Поле.

Първо, FieldStart възли от всяка TOC се събират и съхраняват. Посоченият TOC След това се изброява, така че всички възли в полето се посещават и съхраняват. След това възлите се отстраняват от документа. Следният пример за код показва как да премахнете определен код TOC от документ.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// Open a document which contains a TOC.
Document doc = new Document(dataDir + "Document.TableOfContents.doc");

// Remove the first table of contents from the document.
removeTableOfContents(doc, 0);

// Save the output.
doc.save(dataDir + "Document.TableOfContentsRemoveToc_Out.doc");

Съдържание на екстракт

Ако искате да извлечете съдържание от Word документ, може да се използва следната проба код.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
// The path to the documents directory.
      String dataDir = Utils.getSharedDataDir(ExtractTableOfContents.class) + "TableOfContents/";

      String fileName = "TOC.doc";
      Document doc = new Document(dataDir + fileName);
      
      for (Field field : (Iterable<Field>)doc.getRange().getFields())
      {
          if (field.getType() == FieldType.FIELD_HYPERLINK)
          {
              FieldHyperlink hyperlink = (FieldHyperlink)field;
              if (hyperlink.getSubAddress() != null && hyperlink.getSubAddress().startsWith("_Toc"))
              {
                  Paragraph tocItem = (Paragraph)field.getStart().getAncestor(NodeType.PARAGRAPH);
                  System.out.println(tocItem.toString(SaveFormat.TEXT).trim());
                  System.out.println("------------------");
                  if (tocItem != null)
                  {
                      Bookmark bm = doc.getRange().getBookmarks().get(hyperlink.getSubAddress());
                      // Get the location this TOC Item is pointing to
                      Paragraph pointer = (Paragraph)bm.getBookmarkStart().getAncestor(NodeType.PARAGRAPH);
                      System.out.println(pointer.toString(SaveFormat.TEXT));
                  }
              } // End If
          }// End If
      }// End Foreach