Erstellen und Hinzufügen einer Zeichenformatvorlage zu einem Textverarbeitungsdokument
In diesem Thema wird gezeigt, wie Sie die Klassen im Open XML SDK für Office zum programmgesteuerten Erstellen und Hinzufügen einer Zeichenformatvorlage zu einem Textverarbeitungsdokument verwenden. Sie enthält eine CreateAndAddCharacterStyle-Beispielmethode zur Veranschaulichung dieser Aufgabe sowie eine ergänzende Beispielmethode zum Hinzufügen des Formatvorlagenteils, wenn dies erforderlich ist.
CreateAndAddCharacterStyle-Methode
Die CreateAndAddCharacterStyle-Beispielmethode kann verwendet werden, um einem Textverarbeitungsdokument eine Formatvorlage hinzuzufügen. Sie müssen zunächst einen Verweis auf den Teil der Formatvorlagendefinitionen in dem Dokument abrufen, dem Sie die Formatvorlage hinzufügen möchten. Im Abschnitt Aufrufen der Beispielmethode finden Sie ein Beispiel, das dies veranschaulicht.
Die -Methode akzeptiert vier Parameter, die angeben: einen Verweis auf den Teil der Formatdefinitionen, die Formatvorlagen-ID (ein interner Bezeichner), den Namen der Formatvorlage (für die externe Verwendung in der Benutzeroberfläche) und optional alle Formataliase (alternative Namen für die Verwendung in der Benutzeroberfläche).
public static void CreateAndAddCharacterStyle(StyleDefinitionsPart styleDefinitionsPart,
string styleid, string stylename, string aliases="")
Den vollständigen Codeeintrag für die Methode finden Sie im Abschnitt Beispielcode.
Informationen zu Format-IDs, Formatvorlagennamen und Aliasen
Die Formatvorlagen-ID wird vom Dokument verwendet, um auf die Formatvorlage zu verweisen, und kann als primärer Bezeichner betrachtet werden. In der Regel verwenden Sie die Formatvorlagen-ID, um eine Formatvorlage im Code zu identifizieren. Eine Formatvorlage kann auch einen separaten Anzeigenamen aufweisen, der auf der Benutzeroberfläche angezeigt wird. Häufig wird der Formatvorlagenname daher in richtiger Groß-/Kleinschreibung und mit Abstand (z. B. Überschrift 1) angezeigt, während die Formatvorlagen-ID prägnanter ist (z. B. überschrift1) und für die interne Verwendung vorgesehen ist. Aliase geben alternative Formatnamen an, die in der Benutzeroberfläche einer Anwendung verwendet werden können.
Betrachten Sie beispielsweise das folgende XML-Codebeispiel aus einer Formatdefinition.
<w:style w:type="character" w:styleId="OverdueAmountChar" . . .
<w:aliases w:val="Late Due, Late Amount" />
<w:name w:val="Overdue Amount Char" />
. . .
</w:style>
Das style-Element styleId-Attribut definiert den Standard internen Bezeichner des Stils, die Formatvorlagen-ID (OverdueAmountChar). Das Aliases-Element gibt zwei alternative Formatvorlagennamen an, Late Due und Late Amount, die durch Trennzeichen getrennt sind. Jeder Name muss durch ein oder mehrere Kommas getrennt werden. Schließlich gibt das Name-Element den primären Stilnamen an, der in der Regel auf der Benutzeroberfläche einer Anwendung angezeigt wird.
Aufrufen der Beispielmethode
Sie können die CreateAndAddCharacterStyle-Beispielmethode verwenden, um mithilfe des Open XML SDK eine benannte Formatvorlage zu erstellen und einem Textverarbeitungsdokument hinzuzufügen. Im folgenden Codebeispiel wird gezeigt, wie Sie einen Verweis auf ein Textverarbeitungsdokument öffnen und abrufen, einen Verweis auf den Formatvorlagendefinitionsteil des Dokuments abrufen und dann die CreateAndAddCharacterStyle-Methode aufrufen.
Um die -Methode aufzurufen, übergeben Sie einen Verweis auf den Stildefinitionsteil als ersten Parameter, die Formatvorlagen-ID der Formatvorlage als zweiten Parameter, den Namen der Formatvorlage als dritten Parameter und optional alle Formatvorlagenaliase als vierten Parameter. Im folgenden Codebeispiel wird beispielsweise das Zeichenformat "Überfälliger Betrag Char" in einer Beispieldatei mit dem Namen CreateAndAddCharacterStyle.docx erstellt. Außerdem werden drei Textläufe in einem Absatz erstellt und die Formatvorlage auf die zweite Ausführung angewendet.
string strDoc = @"C:\Users\Public\Documents\CreateAndAddCharacterStyle.docx";
using (WordprocessingDocument doc =
WordprocessingDocument.Open(strDoc, true))
{
// Get the Styles part for this document.
StyleDefinitionsPart part =
doc.MainDocumentPart.StyleDefinitionsPart;
// If the Styles part does not exist, add it.
if (part == null)
{
part = AddStylesPartToPackage(doc);
}
// Create and add the character style with the style id, style name, and
// aliases specified.
CreateAndAddCharacterStyle(part,
"OverdueAmountChar",
"Overdue Amount Char",
"Late Due, Late Amount");
// Add a paragraph with a run with some text.
Paragraph p =
new Paragraph(
new Run(
new Text("this is some text "){Space = SpaceProcessingModeValues.Preserve}));
// Add another run with some text.
p.AppendChild<Run>(new Run(new Text("in a run "){Space = SpaceProcessingModeValues.Preserve}));
// Add another run with some text.
p.AppendChild<Run>(new Run(new Text("in a paragraph."){Space = SpaceProcessingModeValues.Preserve}));
// Add the paragraph as a child element of the w:body.
doc.MainDocumentPart.Document.Body.AppendChild(p);
// Get a reference to the second run (indexed starting with 0).
Run r = p.Descendants<Run>().ElementAtOrDefault(1);
// If the Run has no RunProperties object, create one.
if (r.Elements<RunProperties>().Count() == 0)
{
r.PrependChild<RunProperties>(new RunProperties());
}
// Get a reference to the RunProperties.
RunProperties rPr = r.RunProperties;
// Set the character style of the run.
if (rPr.RunStyle == null)
rPr.RunStyle = new RunStyle();
rPr.RunStyle.Val = "OverdueAmountChar";
Formatvorlagentypen
WordprocessingML unterstützt sechs Formatvorlagentypen, von denen vier mithilfe des type-Attributs für das Style-Element angegeben werden können. In den folgenden Informationen aus Abschnitt 17.7.4.17 in der SPEZIFIKATION ISO/IEC 29500 werden Stiltypen vorgestellt.
Formatvorlagentypen bezieht sich auf die -Eigenschaft einer Formatvorlage, die den Typ der mit dieser Formatvorlagendefinition erstellten Formatvorlage definiert. WordprocessingML unterstützt sechs Typen von Formatdefinitionen anhand der Werte für das Typattribut der Formatvorlagendefinition:
- Absatzformatvorlagen
- Zeichenstile
- Verknüpfte Formatvorlagen (Absatz + Zeichen) Erreicht über das Linkelement (§17.7.4.6).
- Tabellenformate
- Nummerierungsformate
- Standardeigenschaften für Absatz und Zeichen
Betrachten Sie eine Formatvorlage namens Überschrift 1 in einem Dokument, wie im folgenden Codebeispiel gezeigt.
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="heading 1"/>
<w:basedOn w:val="Normal"/>
<w:next w:val="Normal"/>
<w:link w:val="Heading1Char"/>
<w:uiPriority w:val="1"/>
<w:qformat/>
<w:rsid w:val="00F303CE"/>
…
</w:style>
Das Type-Attribut weist den Wert paragraph auf, der angibt, dass die folgende Formatvorlagendefinition eine Absatzformatvorlage ist.
Sie können die Typen von Absatz-, Zeichen-, Tabellen- und Nummerierungsformatvorlagen festlegen, indem Sie den entsprechenden Wert im Type-Attribut des Stilelements angeben.
Zeichenformattyp
Sie geben zeichen als Stiltyp an, indem Sie den Wert des Type-Attributs für das Formatelement auf "character" festlegen.
In den folgenden Informationen aus Abschnitt 17.7.9 der ISO/IEC 29500-Spezifikation werden Zeichenstile erläutert. Beachten Sie, dass Abschnittsnummern, denen § vorangestellt ist, Abschnitte in der ISO-Spezifikation angeben.
17.7.9 Ausführungsstile (Zeichen)
Zeichenformatvorlagen sind Formatvorlagen, die auf den Inhalt einer oder mehrerer Textläufe innerhalb des Inhalts eines Dokuments angewendet werden. Diese Definition impliziert, dass die Formatvorlage nur Zeicheneigenschaften definieren kann (Eigenschaften, die für Text innerhalb eines Absatzes gelten), da sie nicht auf Absätze angewendet werden können. Zeichenstile können nur von Ausführungen innerhalb eines Dokuments referenziert werden, und auf sie muss vom rStyle-Element innerhalb des Ausführungseigenschaftenelements einer Ausführung verwiesen werden.
Eine Zeichenformatvorlage verfügt über zwei formattypspezifische Merkmale:
Das type-Attribut für die Formatvorlage weist den Wert character auf, der angibt, dass die folgende Formatvorlagendefinition eine Zeichenformatvorlage ist.
Die Formatvorlage gibt nur Eigenschaften auf Zeichenebene an, die das rPr-Element verwenden. In diesem Fall sind die Ausführungseigenschaften der Satz von Eigenschaften, die auf jede Ausführung dieses Stils angewendet werden.
Die Zeichenformatvorlage wird dann auf Ausführungen angewendet, indem auf den styleId-Attributwert für diese Formatvorlage im rStyle-Element der Ausführungseigenschaften verwiesen wird.
Die folgende Abbildung zeigt Text, auf den ein Zeichenformat angewendet wurde. Eine Zeichenformatvorlage kann nur auf einen Textbereich auf Unterabsatzebene angewendet werden.
Abbildung 1: Text mit angewendeter Zeichenformatvorlage
Funktionsweise des Codes
Die CreateAndAddCharacterStyle-Methode beginnt mit dem Abrufen eines Verweises auf das styles-Element im Formatvorlagenteil. Das Styles-Element ist das Stammelement des Teils und enthält alle einzelnen Stilelemente. Wenn der Verweis NULL ist, wird das Styles-Element erstellt und im Teil gespeichert.
// Get access to the root element of the styles part.
Styles styles = styleDefinitionsPart.Styles;
if (styles == null)
{
styleDefinitionsPart.Styles = new Styles();
styleDefinitionsPart.Styles.Save();
}
Erstellen des Stils
Um die Formatvorlage zu erstellen, instanziiert der Code die Style-Klasse und legt bestimmte Eigenschaften fest, z . B. den Typ der Formatvorlage (Absatz), die StyleId und ob die Formatvorlage ein CustomStyle ist.
// Create a new character style and specify some of the attributes.
Style style = new Style()
{
Type = StyleValues.Character,
StyleId = styleid,
CustomStyle = true
};
Der Code ergibt den folgenden XML-Code.
<w:style w:type="character" w:styleId="OverdueAmountChar" w:customStyle="true" xmlns:w="https://schemas.openxmlformats.org/wordprocessingml/2006/main">
</w:style>
Der Code erstellt als Nächstes die untergeordneten Elemente des Stils, die die Eigenschaften der Formatvorlage definieren. Um ein Element zu erstellen, instanziieren Sie die entsprechende Klasse und rufen dann die Append([])- Methode auf, um das untergeordnete Element zur Formatvorlage hinzuzufügen. Weitere Informationen zu diesen Eigenschaften finden Sie in Abschnitt 17.7 der ISO/IEC 29500-Spezifikation .
// Create and add the child elements (properties of the style).
Aliases aliases1 = new Aliases() { Val = aliases };
StyleName styleName1 = new StyleName() { Val = stylename };
LinkedStyle linkedStyle1 = new LinkedStyle() { Val = "OverdueAmountPara" };
if (aliases != "")
style.Append(aliases1);
style.Append(styleName1);
style.Append(linkedStyle1);
Als Nächstes instanziiert der Code ein StyleRunProperties-Objekt , um ein rPr-Element (Run Properties) zu erstellen. In diesem Element geben Sie die Zeicheneigenschaften an, die für die Formatvorlage gelten, z. B. Schriftart und Farbe. Die Eigenschaften werden dann als untergeordnete Elemente des rPr-Elements angefügt.
Wenn die Ausführungseigenschaften erstellt werden, fügt der Code das rPr-Element an den Style und das style-Element an das Stammelement styles im Formatvorlagenteil an.
// Create the StyleRunProperties object and specify some of the run properties.
StyleRunProperties styleRunProperties1 = new StyleRunProperties();
Bold bold1 = new Bold();
Color color1 = new Color() { ThemeColor = ThemeColorValues.Accent2 };
RunFonts font1 = new RunFonts() { Ascii = "Tahoma" };
Italic italic1 = new Italic();
// Specify a 24 point size.
FontSize fontSize1 = new FontSize() { Val = "48" };
styleRunProperties1.Append(font1);
styleRunProperties1.Append(fontSize1);
styleRunProperties1.Append(color1);
styleRunProperties1.Append(bold1);
styleRunProperties1.Append(italic1);
// Add the run properties to the style.
style.Append(styleRunProperties1);
// Add the style to the styles part.
styles.Append(style);
Der folgende XML-Code zeigt den endgültigen Stil, der durch den hier gezeigten Code generiert wurde.
<w:style w:type="character" w:styleId="OverdueAmountChar" w:customStyle="true" xmlns:w="https://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:aliases w:val="Late Due, Late Amount" />
<w:name w:val="Overdue Amount Char" />
<w:link w:val="OverdueAmountPara" />
<w:rPr>
<w:rFonts w:ascii="Tahoma" />
<w:sz w:val="48" />
<w:color w:themeColor="accent2" />
<w:b />
<w:i />
</w:rPr>
</w:style>
Anwenden des Zeichenformats
Nachdem Sie die Formatvorlage erstellt haben, können Sie sie auf eine Ausführung anwenden, indem Sie auf den styleId-Attributwert für diese Formatvorlage im rStyle-Element der Ausführungseigenschaften verweisen. Das folgende Codebeispiel zeigt, wie Sie eine Formatvorlage auf eine Ausführung anwenden, auf die die Variable r verweist. Die Formatvorlagen-ID des anzuwendenden Stils, OverdueAmountChar in diesem Beispiel, wird in der RunStyle-Eigenschaft des rPr-Objekts gespeichert. Diese Eigenschaft stellt das rStyle-Element der Ausführungseigenschaften dar.
// If the Run has no RunProperties object, create one.
if (r.Elements<RunProperties>().Count() == 0)
{
r.PrependChild<RunProperties>(new RunProperties());
}
// Get a reference to the RunProperties.
RunProperties rPr = r.RunProperties;
// Set the character style of the run.
if (rPr.RunStyle == null)
rPr.RunStyle = new RunStyle();
rPr.RunStyle.Val = "OverdueAmountChar";
Beispielcode
Im Folgenden finden Sie das vollständige CreateAndAddCharacterStyle-Codebeispiel in C# und Visual Basic.
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
using System;
CreateAndAddCharacterStyle(args[0], args[1], args[2], args[3]);
// Create a new character style with the specified style id, style name and aliases and
// add it to the specified style definitions part.
static void CreateAndAddCharacterStyle(string filePath, string styleid, string stylename, string aliases = "")
{
using (WordprocessingDocument wordprocessingDocument = WordprocessingDocument.Open(filePath, true))
{
// Get access to the root element of the styles part.
Styles? styles = wordprocessingDocument?.MainDocumentPart?.StyleDefinitionsPart?.Styles ?? AddStylesPartToPackage(wordprocessingDocument).Styles;
if (styles is not null)
{
// Create a new character style and specify some of the attributes.
Style style = new Style()
{
Type = StyleValues.Character,
StyleId = styleid,
CustomStyle = true
};
// Create and add the child elements (properties of the style).
Aliases aliases1 = new Aliases() { Val = aliases };
StyleName styleName1 = new StyleName() { Val = stylename };
LinkedStyle linkedStyle1 = new LinkedStyle() { Val = "OverdueAmountPara" };
if (aliases != "")
style.Append(aliases1);
style.Append(styleName1);
style.Append(linkedStyle1);
// Create the StyleRunProperties object and specify some of the run properties.
StyleRunProperties styleRunProperties1 = new StyleRunProperties();
Bold bold1 = new Bold();
Color color1 = new Color() { ThemeColor = ThemeColorValues.Accent2 };
RunFonts font1 = new RunFonts() { Ascii = "Tahoma" };
Italic italic1 = new Italic();
// Specify a 24 point size.
FontSize fontSize1 = new FontSize() { Val = "48" };
styleRunProperties1.Append(font1);
styleRunProperties1.Append(fontSize1);
styleRunProperties1.Append(color1);
styleRunProperties1.Append(bold1);
styleRunProperties1.Append(italic1);
// Add the run properties to the style.
style.Append(styleRunProperties1);
// Add the style to the styles part.
styles.Append(style);
}
}
}
// Add a StylesDefinitionsPart to the document. Returns a reference to it.
static StyleDefinitionsPart AddStylesPartToPackage(WordprocessingDocument? doc)
{
StyleDefinitionsPart part;
if (doc?.MainDocumentPart is null)
{
throw new ArgumentNullException("MainDocumentPart is null.");
}
part = doc.MainDocumentPart.AddNewPart<StyleDefinitionsPart>();
Styles root = new Styles();
root.Save(part);
return part;
}