Insérer des champs

Il existe plusieurs manières d’insérer des champs dans un document:

• en utilisant DocumentBuilder
• en utilisant FieldBuilder
• en utilisant Aspose.Words Document Object Model (DOM)

Dans cet article, nous examinerons chaque méthode plus en détail et analyserons comment insérer certains champs à l’aide de ces options.

Insertion de champs dans un document à l’aide de DocumentBuilder

Dans Aspose.Words, la méthode InsertField est utilisée pour insérer de nouveaux champs dans un document. Le premier paramètre accepte le code de champ complet du champ à insérer. Le deuxième paramètre est facultatif et permet de définir manuellement le résultat du champ. Si celui-ci n’est pas renseigné, le champ est mis à jour automatiquement. Vous pouvez passer null ou vide à ce paramètre pour insérer un champ avec une valeur de champ vide. Si vous n’êtes pas sûr de la syntaxe particulière du code de champ, créez d’abord le champ en Microsoft Word et basculez pour voir son code de champ.

Si votre code de champ comporte un paramètre contenant un espace, il doit être entouré de marques vocales. Sinon, le champ dans Microsoft Word et Aspose.Words risque de ne pas fonctionner comme prévu car le paramètre est traité par les deux comme étant tronqué.

L’exemple de code suivant montre comment insérer un champ de fusion dans un document à l’aide de DocumentBuilder:

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

builder.InsertField(@"MERGEFIELD MyFieldName \* MERGEFORMAT");

doc.Save(ArtifactsDir + "WorkingWithFields.InsertField.docx");

La même technique est utilisée pour insérer des champs imbriqués dans d’autres champs.

L’exemple de code suivant montre comment insérer des champs imbriqués dans un autre champ à l’aide de DocumentBuilder:

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

for (int i = 0; i < 5; i++)
    builder.InsertBreak(BreakType.PageBreak);

builder.MoveToHeaderFooter(HeaderFooterType.FooterPrimary);

// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
Field field = builder.InsertField(@"IF ");
builder.MoveTo(field.Separator);
builder.InsertField("PAGE");
builder.Write(" <> ");
builder.InsertField("NUMPAGES");
builder.Write(" \"See Next Page\" \"Last Page\" ");

field.Update();

doc.Save(ArtifactsDir + "WorkingWithFields.InsertNestedFields.docx");

Spécifier les paramètres régionaux au niveau du champ

Un identifiant de langue est une abréviation numérique internationale standard pour la langue d’un pays ou d’une région géographique. Avec Aspose.Words, vous pouvez spécifier les paramètres régionaux au niveau du champ à l’aide de la propriété LocaleId, qui obtient ou définit l’ID de paramètres régionaux du champ.

L’exemple de code suivant montre comment utiliser cette option:

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

Field field = builder.InsertField(FieldType.FieldDate, true);
field.LocaleId = 1049;

builder.Document.Save(ArtifactsDir + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

Insérer un champ non typé/vide

Si vous souhaitez insérer des champs non typés/vides ({}) comme le permet Microsoft Word, vous pouvez utiliser la méthode InsertField avec le paramètre FieldType.FieldNone. Pour insérer un champ dans un document Word, vous pouvez appuyer sur la combinaison de touches “Ctrl + F9”.

L’exemple de code suivant montre comment insérer un champ vide dans le document:

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

FieldUnknown field = (FieldUnknown) builder.InsertField(FieldType.FieldNone, false);

doc.Save(ArtifactsDir + "WorkingWithFields.InsertFieldNone.docx");

Insertion de champs dans un document à l’aide de FieldBuilder

L’autre façon d’insérer des champs dans Aspose.Words est la classe FieldBuilder. Il fournit une interface fluide pour spécifier les commutateurs de champs et les valeurs d’arguments sous forme de texte, de nœuds ou même de champs imbriqués.

L’exemple de code suivant montre comment insérer un champ dans un document à l’aide de FieldBuilder:

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

// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FieldIf)
    .AddArgument("left expression")
    .AddArgument("=")
    .AddArgument("right expression")
    .AddArgument(
        new FieldArgumentBuilder()
            .AddText("Firstname: ")
            .AddField(new FieldBuilder(FieldType.FieldMergeField).AddArgument("firstname")))
    .AddArgument(
        new FieldArgumentBuilder()
            .AddText("Lastname: ")
            .AddField(new FieldBuilder(FieldType.FieldMergeField).AddArgument("lastname")));

// Insert IF field in exact location            
Field field = fieldBuilder.BuildAndInsert(doc.FirstSection.Body.FirstParagraph);
field.Update();

doc.Save(ArtifactsDir + "Field.InsertFieldUsingFieldBuilder.docx");

Insertion de champs à l’aide de DOM

Vous pouvez également insérer différents types de champs à l’aide de Aspose.Words Document Object Model (DOM). Dans cette section, nous examinerons quelques exemples.

Insertion d’un champ de fusion dans un document à l’aide de DOM

Le champ MERGEFIELD dans un document Word peut être représenté par la classe FieldMergeField. Vous pouvez utiliser la classe FieldMergeField pour effectuer les opérations suivantes:

• préciser le nom du champ de fusion
• spécifier le formatage du champ de fusion
• spécifiez le texte qui se trouve entre le séparateur de champ et la fin du champ de fusion
• préciser le texte à insérer après le champ de fusion si le champ n’est pas vide
• préciser le texte à insérer avant le champ de fusion si le champ n’est pas vide

Pour plus de détails, consultez la classe FieldMergeField API.

L’exemple de code suivant montre comment ajouter le champ MERGE à l’aide de DOM à un paragraphe d’un document:

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

Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];
builder.MoveTo(para);

// We want to insert a merge field like this:
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
FieldMergeField field = (FieldMergeField) builder.InsertField(FieldType.FieldMergeField, false);

// { " MERGEFIELD Test1" }
field.FieldName = "Test1";
// { " MERGEFIELD Test1 \\b Test2" }
field.TextBefore = "Test2";
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field.TextAfter = "Test3";
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" }
field.IsMapped = true;
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
field.IsVerticalFormatting = true;

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertMergeFieldUsingDOM.docx");

Insertion du champ Mail Merge ADDRESSBLOCK dans un document à l’aide de DOM

Le champ ADDRESSBLOCK est utilisé pour insérer un bloc d’adresse Mail Merge dans un document Word. Le champ ADDRESSBLOCK dans un document Word peut être représenté par la classe FieldAddressBlock. Vous pouvez utiliser la classe FieldAddressBlock pour effectuer les opérations suivantes:

• préciser s’il faut inclure le nom du pays/de la région dans le champ
• préciser s’il faut formater l’adresse en fonction du pays/région du destinataire tel que défini par POST*CODE (Union postale universelle 2006)
• précisez le nom du pays/de la région exclu
• préciser le format du nom et de l’adresse
• spécifier l’ID de langue utilisé pour formater l’adresse

Pour plus de détails, consultez la classe FieldAddressBlock API.

L’exemple de code suivant montre comment ajouter le champ ADDRESSBLOCK Mail Merge à l’aide de DOM à un paragraphe d’un document:

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

Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];
builder.MoveTo(para);

// We want to insert a mail merge address block like this:
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
FieldAddressBlock field = (FieldAddressBlock) builder.InsertField(FieldType.FieldAddressBlock, false);

// { ADDRESSBLOCK \\c 1" }
field.IncludeCountryOrRegionName = "1";
// { ADDRESSBLOCK \\c 1 \\d" }
field.FormatAddressOnCountryOrRegion = true;
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field.ExcludedCountryOrRegionName = "Test2";
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field.NameAndAddressFormat = "Test3";
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field.LanguageId = "Test 4";

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

Insertion d’un champ ADVANCE dans un document sans utiliser DocumentBuilder

Le champ ADVANCE est utilisé pour décaler le texte suivant dans une ligne vers la gauche, la droite, le haut ou le bas. Le champ ADVANCE dans un document Word peut être représenté par la classe FieldAdvance. Vous pouvez utiliser la classe FieldAdvance pour effectuer les opérations suivantes:

• préciser le nombre de points dont le texte qui suit le champ doit être déplacé verticalement à partir du bord supérieur de la page
• spécifiez le nombre de points dont le texte qui suit le champ doit être déplacé horizontalement depuis le bord gauche de la colonne, du cadre ou de la zone de texte
• préciser le nombre de points dont le texte qui suit le champ doit être déplacé vers la gauche, la droite, le haut ou le bas

Pour plus de détails, consultez la classe FieldAdvance API.

L’exemple de code suivant montre comment ajouter le champ ADVANCE à l’aide de DOM à un paragraphe d’un document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an Advance field like this:
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
FieldAdvance field = (FieldAdvance) para.AppendField(FieldType.FieldAdvance, false);

// { ADVANCE \\d 10 " }
field.DownOffset = "10";
// { ADVANCE \\d 10 \\l 10 }
field.LeftOffset = "10";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field.RightOffset = "-3.3";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field.UpOffset = "0";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field.HorizontalPosition = "100";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field.VerticalPosition = "100";

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.docx");

Insertion d’un champ ASK dans un document sans utiliser DocumentBuilder

Le champ ASK est utilisé pour demander à l’utilisateur le texte à attribuer à un signet dans un document Word. Le champ ASK dans un document Word peut être représenté par la classe FieldAsk. Vous pouvez utiliser la classe FieldAsk pour effectuer les opérations suivantes:

• préciser le nom du signet
• spécifier la réponse utilisateur par défaut (valeur initiale contenue dans la fenêtre d’invite)
• spécifier si la réponse de l’utilisateur doit être reçue une fois par opération mail merge
• spécifiez le texte de l’invite (le titre de la fenêtre d’invite)

Pour plus de détails, consultez la classe FieldAsk API.

L’exemple de code suivant montre comment ajouter le champ ASK à l’aide de DOM à un paragraphe d’un document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an Ask field like this:
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
FieldAsk field = (FieldAsk) para.AppendField(FieldType.FieldAsk, false);
// { ASK \"Test 1\" " }
field.BookmarkName = "Test 1";
// { ASK \"Test 1\" Test2 }
field.PromptText = "Test2";
// { ASK \"Test 1\" Test2 \\d Test3 }
field.DefaultResponse = "Test3";
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field.PromptOnceOnMailMerge = true;

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.docx");

Insertion d’un champ AUTHOR dans un document sans utiliser DocumentBuilder

Le champ AUTHOR permet de préciser le nom de l’auteur du document à partir des propriétés Document. Le champ AUTHOR dans un document Word peut être représenté par la classe FieldAuthor. Vous pouvez utiliser la classe FieldAuthor pour effectuer les opérations suivantes:

• préciser le nom de l’auteur du document

Pour plus de détails, consultez la classe FieldAuthor API.

L’exemple de code suivant montre comment ajouter le champ AUTHOR à l’aide de DOM à un paragraphe d’un document:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an AUTHOR field like this:
// { AUTHOR Test1 }
FieldAuthor field = (FieldAuthor) para.AppendField(FieldType.FieldAuthor, false);            
field.AuthorName = "Test1"; // { AUTHOR Test1 }

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertAuthorField.docx");

Insertion d’un champ INCLUDETEXT dans un document sans utiliser DocumentBuilder

Le champ INCLUDETEXT insère le texte et les graphiques contenus dans le document nommé dans le code du champ. Vous pouvez insérer l’intégralité du document ou une partie du document référencé par un signet. Ce champ dans le document Word est représenté par INCLUDETEXT. Vous pouvez utiliser la classe FieldIncludeText pour effectuer les opérations suivantes:

• précisez le nom du signet du document inclus
• préciser l’emplacement du document

Pour plus de détails, consultez la classe FieldIncludeText API.

L’exemple de code suivant montre comment ajouter le champ INCLUDETEXT à l’aide de DOM à un paragraphe d’un document:

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

// We want to insert an INCLUDETEXT field like this:
// { INCLUDETEXT  "file path" }
FieldIncludeText fieldIncludeText = (FieldIncludeText) para.AppendField(FieldType.FieldIncludeText, false);
fieldIncludeText.BookmarkName = "bookmark";
fieldIncludeText.SourceFullName = MyDir + "IncludeText.docx";

doc.FirstSection.Body.AppendChild(para);

fieldIncludeText.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

Insertion d’un champ TOA dans un document sans utiliser DocumentBuilder

Le champ TOA (Table of Authorities) construit et insère une table d’autorités. Le champ TOA collecte les entrées marquées par les champs TA (Table of Authorities Entry). Microsoft Office Word insère le champ TOA lorsque vous cliquez sur Insérer une table d’autorités dans le groupe Tableau des autorités de l’onglet References. Lorsque vous affichez le champ TOA dans votre document, la syntaxe ressemble à ceci:

{ TOA [Switches ] }

Pour plus de détails, consultez la classe FieldToa API.

L’exemple de code suivant montre comment ajouter le champ TOA à l’aide de DOM à un paragraphe d’un document:

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

// We want to insert TA and TOA fields like this:
// { TA  \c 1 \l "Value 0" }
// { TOA  \c 1 }
FieldTA fieldTA = (FieldTA) para.AppendField(FieldType.FieldTOAEntry, false);
fieldTA.EntryCategory = "1";
fieldTA.LongCitation = "Value 0";

doc.FirstSection.Body.AppendChild(para);

para = new Paragraph(doc);

FieldToa fieldToa = (FieldToa) para.AppendField(FieldType.FieldTOA, false);
fieldToa.EntryCategory = "1";
doc.FirstSection.Body.AppendChild(para);

fieldToa.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");