نظرة عامة على الميزات — Aspose.Note FOSS لـ Python

Aspose.Note FOSS for Python (package aspose-note, الإصدار 26.3.1) يوفر واجهة برمجة تطبيقات Python لقراءة Microsoft OneNote .one ملفات الأقسام وتصديرها إلى PDF. جميع الميزات المذكورة أدناه تم التحقق منها مقابل شفرة المصدر في المستودع، وملف README، وسكريبتات الأمثلة.

التثبيت والإعداد

التثبيت من PyPI:

pip install aspose-note

لدعم تصدير PDF (يتطلب ReportLab):

pip install "aspose-note[pdf]"

المتطلبات: Python 3.10 أو أحدث. لا يلزم تثبيت Microsoft Office.

الميزات والقدرات

.تحميل ملفات .one

حمّل ملفات أقسام Microsoft OneNote من مسار ملف أو أي تدفق ثنائي (مقبض ملف،, io.BytesIO,، جسم استجابة HTTP، تدفق تخزين سحابي).

• Document.FileFormat يوفر إشارة تقريبية لإصدار تنسيق ملف OneNote (OneNote2010، OneNoteOnline، أو OneNote2007)
• التحميل القائم على التدفق يلغي عمليات الإدخال/الإخراج على القرص لتدفقات العمل في الذاكرة أو عبر الشبكة
• LoadOptions.LoadHistory العلم يتحكم فيما إذا كان تاريخ الصفحة مشمولًا في DOM

from aspose.note import Document

##From a file path
doc = Document("notebook.one")

##From a binary stream
with open("notebook.one", "rb") as f:
    doc = Document(f)

التنقل في DOM المستند

يتم عرض مستند OneNote الكامل كشجرة من كائنات Python ذات نوع محدد. كل عقدة ترث من Node أو CompositeNode:

• Document: جذر؛ يكشف DisplayName, CreationTime, FileFormat
• Page: طفل مباشر لـ Document; يعرض Title, Author, CreationTime, LastModifiedTime, Level
• Title: يعرض TitleText, TitleDate, TitleTime (الكل RichText العقد)
• Outline: حاوية موضعية مع HorizontalOffset, VerticalOffset, MaxWidth, MaxHeight, MinWidth, ReservedWidth, IndentPosition
• OutlineElement: حاوية ورقية; يعرض NumberList

طرق التنقل على CompositeNode:

from aspose.note import Document, Page, Outline, OutlineElement, RichText

doc = Document("notebook.one")
for page in doc.GetChildNodes(Page):
    title_text = page.Title.TitleText.Text if page.Title and page.Title.TitleText else ""
    print(f"Page: {title_text}")
    for outline in page.GetChildNodes(Outline):
        for oe in outline.GetChildNodes(OutlineElement):
            for rt in oe.GetChildNodes(RichText):
                print(f"  {rt.Text}")

استخراج محتوى النص المنسق

RichText العُقَد تُظهر:

• Text: str: سلسلة نصية عادية كاملة
• TextRuns: list[TextRun]: قائمة من المقاطع المُنسقة
• Tags: list[NoteTag]: وسوم OneNote المرفقة بهذا الكتلة
• Append(text, style=None): إلحاق تشغيل نصي في الذاكرة
• Replace(old_value, new_value): استبدال سلسلة في الذاكرة

: كل TextRun : يحمل:

TextStyle : الخصائص:

from aspose.note import Document, RichText

doc = Document("notebook.one")
for rt in doc.GetChildNodes(RichText):
    for run in rt.TextRuns:
        if run.Style.IsHyperlink:
            print(f"Hyperlink: {run.Text} -> {run.Style.HyperlinkAddress}")
        if run.Style.IsBold:
            print(f"Bold text: {run.Text}")

استخراج الصور

Image العقد تعرض البايتات الخام والبيانات الوصفية لكل صورة مدمجة:

from aspose.note import Document, Image

doc = Document("notebook.one")
for i, img in enumerate(doc.GetChildNodes(Image), start=1):
    filename = img.FileName or f"image_{i}.bin"
    with open(filename, "wb") as f:
        f.write(img.Bytes)
    print(f"Saved: {filename}  ({img.Width} x {img.Height} pts)")

استخراج الملفات المرفقة

AttachedFile العقد تعرض مرفقات الملفات المدمجة:

from aspose.note import Document, AttachedFile

doc = Document("notebook.one")
for i, af in enumerate(doc.GetChildNodes(AttachedFile), start=1):
    filename = af.FileName or f"attachment_{i}.bin"
    with open(filename, "wb") as f:
        f.write(af.Bytes)

تحليل الجداول

Table, TableRow,، و TableCell اعرض بنية الجدول الكاملة:

from aspose.note import Document, Table, TableRow, TableCell, RichText

doc = Document("notebook.one")
for table in doc.GetChildNodes(Table):
    print("Column widths:", [col.Width for col in table.Columns])
    for r, row in enumerate(table.GetChildNodes(TableRow), start=1):
        cells = row.GetChildNodes(TableCell)
        values = [
            " ".join(rt.Text for rt in cell.GetChildNodes(RichText)).strip()
            for cell in cells
        ]
        print(f"Row {r}:", values)

فحص وسوم OneNote

NoteTag يظهر على RichText, Image, AttachedFile,، و Table العُقَد عبر .Tags الخاصية. OutlineElement ليس لديها .Tags خاصية. NoteTag الخصائص:

طريقة المصنع: NoteTag.CreateYellowStar() ينشئ عقدة وسم نجمة صفراء قياسية.

from aspose.note import Document, RichText

doc = Document("notebook.one")
for rt in doc.GetChildNodes(RichText):
    for tag in rt.Tags:
        print(f"Tag: {tag.Label} (icon={tag.Icon}, completed={tag.CompletedTime})")

دعم القوائم المرقمة

OutlineElement.NumberList يكشف عن:

from aspose.note import Document, OutlineElement

doc = Document("notebook.one")
for oe in doc.GetChildNodes(OutlineElement):
    nl = oe.NumberList
    if nl:
        print(f"format={nl.Format!r}")

تجوال DocumentVisitor

DocumentVisitor يوفر نمط الزائر لتجوال هيكلي كامل للمستند. تجاوز أي VisitXxxStart / VisitXxxEnd طريقة لاعتراض أنواع العقد المحددة:

• VisitDocumentStart(doc) / VisitDocumentEnd(doc)
• VisitPageStart(page) / VisitPageEnd(page)
• VisitTitleStart(title) / VisitTitleEnd(title)
• VisitOutlineStart(outline) / VisitOutlineEnd(outline)
• VisitOutlineElementStart(oe) / VisitOutlineElementEnd(oe)
• VisitRichTextStart(rt) / VisitRichTextEnd(rt)
• VisitImageStart(img) / VisitImageEnd(img)

from aspose.note import Document, DocumentVisitor, Page, RichText, Image

class MySummaryVisitor(DocumentVisitor):
    def __init__(self):
        self.pages, self.texts, self.images = 0, 0, 0

    def VisitPageStart(self, page: Page) -> None:
        self.pages += 1

    def VisitRichTextStart(self, rt: RichText) -> None:
        self.texts += 1

    def VisitImageStart(self, img: Image) -> None:
        self.images += 1

doc = Document("notebook.one")
v = MySummaryVisitor()
doc.Accept(v)
print(f"Pages={v.pages}  RichText={v.texts}  Images={v.images}")

تصدير PDF

احفظ مستندًا محمَّلاً إلى PDF باستخدام Document.Save(). مدعوم عبر الواجهة الخلفية الاختيارية ReportLab.

from aspose.note import Document, SaveFormat

doc = Document("notebook.one")
doc.Save("output.pdf", SaveFormat.Pdf)

PdfSaveOptions

import io
from aspose.note import Document, SaveFormat
from aspose.note.saving import PdfSaveOptions

doc = Document("notebook.one")

##Save to file
doc.Save("output.pdf", SaveFormat.Pdf)

##Save to in-memory stream
buf = io.BytesIO()
doc.Save(buf, PdfSaveOptions())
pdf_bytes = buf.getvalue()

مرجع الصيغ والعدادات

SaveFormat

FileFormat

Document.FileFormat يوفر إشارة تقريبية لإصدار تنسيق ملف OneNote. يعلن الـ enum عن ثلاث قيم:

NodeType

NodeType.Document, NodeType.Page, NodeType.Outline, NodeType.OutlineElement, NodeType.RichText, NodeType.Image, NodeType.Table, NodeType.AttachedFile

HorizontalAlignment

HorizontalAlignment.Left, HorizontalAlignment.Center, HorizontalAlignment.Right

القيود الحالية

نصائح وأفضل الممارسات

• تحقق من None: Page.Title, Title.TitleText, OutlineElement.NumberList, ويمكن أن تكون معظم حقول البيانات الوصفية None. احرص دائمًا على الحماية بـ if x is not None أو if x قبل الوصول إلى الخصائص.
• استخدم GetChildNodes(Type) للبحث المتكرر بدلاً من تكرار الشجرة يدويًا. يبحث في الشجرة الفرعية بأكملها.
• تكرار الأطفال المباشرين مع for child in node عندما تحتاج فقط إلى الأطفال الفوريين.
• معالجة الترميز على Windows: على Windows،, sys.stdout قد يستخدم صفحة ترميز قديمة. أضف sys.stdout.reconfigure(encoding="utf-8", errors="replace") عند بدء التشغيل عند طباعة نص Unicode.
• تثبيت [pdf] إضافي: لا تستورد SaveFormat.Pdf الوظيفة دون تثبيت أولاً pip install "aspose-note[pdf]". بدون ReportLab، سيؤدي حفظ إلى PDF إلى رفع خطأ استيراد أثناء التشغيل.