Praca z właściwościami dokumentu

Praca z właściwościami dokumentu

Ten przewodnik pokazuje, jak odczytywać i zarządzać metadanymi dokumentu Word — właściwościami widocznymi w panelu Informacje/Właściwości programu Word, a także dowolnymi niestandardowymi wartościami definiowanymi przez aplikację. Document.BuiltInDocumentProperties i Document.CustomDocumentProperties udostępniają te dwie kategorie, które ostatecznie opierają się na tej samej podstawowej reprezentacji DocumentProperty.

Wbudowane właściwości dokumentu

Document.BuiltInDocumentProperties zwraca kolekcję BuiltInDocumentProperties obejmującą standardowe metadane, które Word śledzi dla każdego dokumentu: pola opisowe, takie jak Title, Subject, Author, Manager, Company, Category, Keywords i Comments; znaczniki czasu, takie jak CreatedTime, LastSavedTime i LastPrinted, wraz z LastSavedBy i RevisionNumber; oraz statystyki, takie jak Words, Characters, CharactersWithSpaces, Lines, Paragraphs i Pages. Security raportuje stan ochrony dokumentu jako wartość DocumentSecurity, a Template, NameOfApplication i TotalEditingTime opisują środowisko tworzenia. Ponieważ BuiltInDocumentProperties jest stałym, znanym zestawem właściwości, poszczególne wartości są odczytywane i zapisywane jako zwykłe właściwości (BuiltInDocumentProperties.Author = "..."), a nie wyszukiwane po nazwie.

Niestandardowe właściwości dokumentu

Document.CustomDocumentProperties zwraca kolekcję CustomDocumentProperties dla metadanych definiowanych przez aplikację, które nie są częścią wbudowanego zestawu Worda. Kilka przeciążeń Add(name, value) tworzy nową właściwość z nazwy i wartości typowanej (ciąg znaków, liczba, wartość logiczna lub data, w zależności od przeciążenia), a AddLinkToContent(name, linkSource) tworzy właściwość, której wartość jest powiązana i śledzi zakładkę zakresu treści w dokumencie zamiast przechowywać statyczną wartość. Indeksowanie po nazwie (np. properties[name]) i Contains(name) wyszukują właściwość, IndexOf(name) zwraca jej pozycję, a Remove(name)/RemoveAt(index) usuwają ją.

Obiekt DocumentProperty i współdzielona baza kolekcji

Oba BuiltInDocumentProperties i CustomDocumentProperties pochodzą z abstrakcyjnego DocumentPropertyCollection, który definiuje indeksator według nazwy, GetEnumerator(), Contains(name), IndexOf(name) i Count — tak więc dwie kolekcje są przeglądane w ten sam sposób, mimo że wbudowane właściwości są stałe, a własne właściwości są otwarte. Indywidualnie, DocumentProperty ma Name, nientypowany Value oraz Type (wartość wyliczeniowa PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray lub Other). IsLinkToContent i LinkSource informują, czy właściwość jest powiązana z treścią dokumentu, a nie przechowuje statyczną wartość (zobacz AddLinkToContent powyżej). Ponieważ Value jest nientypowany, DocumentProperty udostępnia typowane akcesory — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() i ToString() — aby odczytać go jako konkretny typ bez explicite’go rzutowania.

Zabezpieczenia dokumentu

BuiltInDocumentProperties.Security zgłasza wartość DocumentSecurity opisującą stan ochrony dokumentu: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced lub ReadOnlyExceptAnnotations. Odzwierciedla to przechowywane w dokumencie metadane ochrony odczytane z właściwości pliku.

Wskazówki i najlepsze praktyki

• Używaj typowanych akcesorów (ToInt(), ToDouble(), ToDateTime(), ToBool()) na DocumentProperty.Value zamiast bezpośrednio rzutować nientypowaną wartość object, ponieważ podstawowy typ przechowywania może się różnić w zależności od PropertyType.
• Sprawdź Contains(name) przed indeksowaniem dowolnej kolekcji właściwości po nazwie (np. properties[name]), gdy właściwość może nie istnieć, aby uniknąć obsługi sytuacji braku właściwości jako ścieżki wyjątkowej.
• Używaj CustomDocumentProperties.AddLinkToContent(name, linkSource), gdy wartość własnej właściwości powinna zawsze odzwierciedlać zakładkę w dokumencie, zamiast ręcznie synchronizować statyczną własną właściwość przy każdej zmianie tej treści.
• Traktuj statystyki BuiltInDocumentProperties (Words, Characters, Pages i podobne) jako wartości zapisane w metadanych pliku, a nie jako zawsze aktualne obliczone liczby — odśwież je explicite, jeśli dokument uległ zmianie od momentu ich ostatniego zapisu.
• Odczytaj BuiltInDocumentProperties.Security, aby sprawdzić zadeklarowany stan ochrony dokumentu, zanim zdecydujesz, czy potrzebne jest dalsze przetwarzanie związane z ochroną.

Typowe problemy

FAQ

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 wersja Add zostaje wybrana na podstawie typu wartości.

Jaka jest różnica między BuiltInDocumentProperties a CustomDocumentProperties?

BuiltInDocumentProperties to stały zestaw standardowych pól metadanych Worda (autor, tytuł, statystyki itd.), dostępnych jako nazwane właściwości. CustomDocumentProperties to otwarta, nazwana kolekcja wartości DocumentProperty dla metadanych definiowanych przez aplikację, dostępna po nazwie za pomocą indeksatora (np. properties[name]) i Contains.

Jak odczytać własną właściwość, nie znając jej dokładnego typu przechowywanego z góry?

Pobierz DocumentProperty indeksując kolekcję (np. properties[name]), sprawdź jej Type (wartość PropertyType), i użyj odpowiedniego typowanego akcesora, takiego jak ToInt(), ToDouble(), ToDateTime() lub ToBool(), na jej Value.

Jak sprawić, aby własna właściwość śledziła fragment treści dokumentu?

Użyj CustomDocumentProperties.AddLinkToContent(name, linkSource), przekazując nazwę zakładki jako linkSource; wartość właściwości będzie wtedy odzwierciedlać tę zakładkowaną treść, a nie statyczną wartość.

API Reference Podsumowanie

Zobacz także

• Aspose.Words for .NET — Enterprise Documentation