Jak pracować z właściwościami dokumentu w .NET
Jak pracować z właściwościami dokumentu w .NET
Każdy dokument Word zawiera dwie kategorie metadanych — standardowe pola, które Word śledzi dla każdego pliku, oraz wszelkie wartości zdefiniowane przez aplikację, które program dodał. Ten przewodnik pokazuje, jak odczytywać i ustawiać oba rodzaje przy użyciu Aspose.Words FOSS dla .NET, wykorzystując Document.BuiltInDocumentProperties i Document.CustomDocumentProperties, które ostatecznie opierają się na tej samej reprezentacji DocumentProperty.
Przewodnik krok po kroku
Krok 1: Odczyt i ustawianie wbudowanych właściwości dokumentu
Document.BuiltInDocumentProperties zwraca kolekcję BuiltInDocumentProperties. Ponieważ jest to stały, znany zestaw właściwości, wartości są odczytywane i zapisywane jako zwykłe elementy, a nie wyszukiwane po nazwie — na przykład BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords i .Comments dla pól opisowych, lub .CreatedTime, .LastSavedTime, .LastPrinted i .LastSavedBy dla znaczników czasu. Statystyki takie jak .Characters, .CharactersWithSpaces, .Lines i .Bytes są również udostępniane w ten sposób, obok .Template i .HyperlinkBase.
Krok 2: Dodaj niestandardową właściwość dokumentu
Document.CustomDocumentProperties zwraca CustomDocumentProperties kolekcję dla metadanych definiowanych przez aplikację, które nie są częścią wbudowanego zestawu Worda. Wywołaj jedną z przeciążeń Add(name, value) z nazwą i typowaną wartością — string, number, boolean lub date, w zależności od tego, które przeciążenie pasuje do typu wartości — aby utworzyć nową właściwość.
Krok 3: Połącz własność niestandardową z treścią dokumentu
Zamiast statycznej wartości, własność niestandardowa może śledzić zakreślony zakres treści, aby jej wartość pozostawała zsynchronizowana z tą treścią. Wywołaj CustomDocumentProperties.AddLinkToContent(name, linkSource), przekazując nazwę zakładki jako linkSource, zamiast ręcznie ponownie synchronizować statyczną własność za każdym razem, gdy zmieni się połączona treść.
Krok 4: Wyszukaj, sprawdź i usuń właściwości
Zarówno BuiltInDocumentProperties, jak i CustomDocumentProperties dziedziczą po abstrakcyjnym DocumentPropertyCollection, więc są sprawdzane w ten sam sposób: indeksowanie po nazwie (np. properties[name]) zwraca właściwość, Contains(name) sprawdza, czy istnieje, IndexOf(name) zwraca jej pozycję, a Count podaje, ile właściwości znajduje się w kolekcji. Wywołaj Contains(name) przed indeksowaniem po nazwie, gdy własność niestandardowa może nie istnieć, aby uniknąć obsługi brakującej własności jako ścieżki wyjątkowej. Usuń własność za pomocą Remove(name) lub RemoveAt(index), lub wyczyść wszystkie własności w kolekcji przy pomocy Clear().
Krok 5: Odczytaj wartość własności niestandardowej bez znajomości jej typu z góry
Obiekt DocumentProperty posiada Name, nietypowany Value oraz Type — wartość wyliczeniową PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray lub Other. Ponieważ Value jest nietypowany, użyj odpowiedniego typowanego akcesora zamiast rzutowania bezpośredniego: ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() lub ToString(). Sprawdź IsLinkToContent i LinkSource, aby dowiedzieć się, czy własność jest połączona z treścią dokumentu (zobacz Krok 3), a nie przechowuje statycznej wartości.
Krok 6: Sprawdź stan ochrony dokumentu
BuiltInDocumentProperties.Security zgłasza wartość DocumentSecurity opisującą przechowywane metadane ochrony dokumentu: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced lub ReadOnlyExceptAnnotations. Przeczytaj tę właściwość przed podjęciem decyzji, czy dalsze przetwarzanie związane z ochroną jest potrzebne w załadowanym dokumencie.
Typowe problemy i rozwiązania
Indeksowanie CustomDocumentProperties kolekcja według nazwy nie zwraca nic użytecznego. Właściwość nie istnieje w tym dokumencie. Wywołaj Contains(name) najpierw, lub dodaj właściwość z odpowiednim Add(name, value) przeciążeniem.
Odczytanie wartości własnej właściwości zwraca niewłaściwy typ. DocumentProperty.Value jest nieokreślony object; wywołujący założył typ, który nie pasuje Type. Użyj odpowiedniego typowanego akcesora (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) na podstawie DocumentProperty.Type.
Wartość powiązanej własnej własności wygląda na przestarzałą. Własność jest powiązana przez AddLinkToContent, a zawartość oznaczona zakładką została zmieniona. Potwierdź, że linkSource zakładka nadal oznacza zakres, który powinien dostarczyć wartość własności.
Statystyki słów, takie jak Characters or Lines nie pasują do aktualnej rzeczywistej zawartości dokumentu. Wbudowane statystyki odzwierciedlają zapisane metadane, a nie bieżące przeliczenie. Przelicz ponownie i zaktualizuj odpowiednie BuiltInDocumentProperties wartości, jeśli wymagane jest aktualne zliczenie.
Najczęściej zadawane pytania
Jak odczytać lub ustawić autora i tytuł dokumentu?
Użyj Document.BuiltInDocumentProperties.Author i .Title bezpośrednio — są to zwykłe właściwości typu string w kolekcji BuiltInDocumentProperties dostępnej z Document.BuiltInDocumentProperties.
Jak dodać metadane specyficzne dla aplikacji, które nie są standardową właściwością Worda?
Użyj Document.CustomDocumentProperties.Add(name, value) z nazwą i wartością właściwości; odpowiednia przeciążona metoda Add zostaje wybrana w zależności od typu wartości.
Jaka jest różnica między BuiltInDocumentProperties a CustomDocumentProperties?
BuiltInDocumentProperties to stały zestaw standardowych pól metadanych Worda, dostępny jako nazwane członki. CustomDocumentProperties to otwarta, nazwana kolekcja wartości DocumentProperty dla metadanych definiowanych przez aplikację, dostępna po nazwie za pomocą indeksatora (np. properties[name]) oraz Contains.
Jak sprawić, aby własność niestandardowa śledziła fragment treści dokumentu zamiast statycznej wartości?
Użyj CustomDocumentProperties.AddLinkToContent(name, linkSource), przekazując nazwę zakładki jako linkSource; wartość własności będzie wtedy odzwierciedlać zawartość tej zakładki.
Jak sprawdzić, czy dokument jest zabezpieczony hasłem?
Odczytaj Document.BuiltInDocumentProperties.Security, wartość DocumentSecurity; PasswordProtected wskazuje, że przechowywane metadane dokumentu deklarują ochronę hasłem.
