کار با سند Note Document

این راهنما توضیح می‌دهد چگونه فایل‌های Microsoft OneNote .one را در Python با استفاده از کلاس Document از Aspose.Note FOSS بارگذاری، پیمایش و صادر کنیم. کلاس Document ریشهٔ مدل شیء سند (DOM) است و هر عملیات خواندن، پیمایش یا خروجی‌گیری با یک نمونهٔ Document که نمایانگر یک فایل بخش .one است، آغاز می‌شود.

بارگذاری یک سند

بارگذاری از مسیر فایل

مسیر یک فایل .one را مستقیماً به سازندهٔ Document پاس دهید:

from aspose.note import Document

doc = Document("MyNotes.one")

بارگذاری از یک جریان باینری

از یک شیء شبیه‌به‌فایل استفاده کنید وقتی داده‌ها از پاسخ شبکه، بلوک ذخیره‌سازی ابری یا بافر در حافظه می‌آیند:

from pathlib import Path
from aspose.note import Document

with Path("MyNotes.one").open("rb") as f:
    doc = Document(f)

یک سند خالی ایجاد کنید

یک Document بدون آرگومان بسازید تا به‌صورت برنامه‌نویسی یک سند OneNote جدید ایجاد کنید:

from aspose.note import Document, Page

doc = Document()
doc.AppendChildLast(Page())

بارگذاری با گزینه‌ها

از LoadOptions برای تنظیم پارامترهای اختیاری مانند بارگذاری تاریخچه در زمان ساخت استفاده کنید:

from aspose.note import Document, LoadOptions

opts = LoadOptions()
opts.LoadHistory = True   # include page revision history in the DOM
doc = Document("MyNotes.one", opts)

تشخیص فرمت سند

خاصیت FileFormat شناسایی می‌کند که فایل از کدام نوع فرمت OneNote استفاده می‌کند:

from aspose.note import Document, FileFormat

doc = Document("MyNotes.one")

if doc.FileFormat == FileFormat.OneNote2010:
    print("OneNote 2010 format")
elif doc.FileFormat == FileFormat.OneNoteOnline:
    print("OneNote Online format")
elif doc.FileFormat == FileFormat.OneNote2007:
    print("OneNote 2007 format")
else:
    print("Format:", doc.FileFormat)

تکرار صفحات

صفحات فرزندان مستقیم Document هستند. از آنجا که Document یک شمارنده پیاده‌سازی می‌کند، می‌توانید با یک حلقه ساده for بر روی آن تکرار کنید:

from aspose.note import Document

doc = Document("MyNotes.one")

for page in doc:
    title_text = (
        page.Title.TitleText
        if page.Title and page.Title.TitleText
        else "(untitled)"
    )
    print(title_text)

اگر نیاز دارید تمام گره‌های فرزند از یک نوع خاص را یک‌باره بازیابی کنید، از متد GetChildNodes استفاده کنید و کلاس گره موردنظر را به عنوان آرگومان پاس دهید:

# Replace DesiredNodeType below with the specific node class you want to collect
nodes = doc.GetChildNodes(DesiredNodeType)
print(f"Total nodes: {len(nodes)}")

پیمایش درخت سند

Document از CompositeNode ارث می‌برد و به آن روش‌های کامل پیمایش درخت را می‌دهد:

from aspose.note import Document, RichText

doc = Document("MyNotes.one")

# Extract all plain text from the entire document
all_text = [rt.Text for rt in doc.GetChildNodes(RichText) if rt.Text]
print("\n".join(all_text))

سلسله‌مراتبی DOM:

Document
  └── Page (0..n)
        ├── Title
        │     ├── TitleText (RichText)
        │     ├── TitleDate (RichText)
        │     └── TitleTime (RichText)
        └── Outline (0..n)
              └── OutlineElement (0..n)
                    ├── RichText
                    ├── Image
                    ├── Table
                    │     └── TableRow → TableCell → RichText / Image
                    └── AttachedFile

روش‌های کلیدی پیمایش که از CompositeNode ارث برده شده‌اند:

تاریخچه صفحه

هنگامی که با LoadHistory=True بارگذاری می‌شود، Document.GetPageHistory تمام نسخه‌های ذخیره‌شده یک صفحه را باز می‌گرداند، به ترتیب از قدیمی‌ترین تا جدیدترین:

from aspose.note import Document, LoadOptions

opts = LoadOptions()
opts.LoadHistory = True
doc = Document("MyNotes.one")

for page in doc.GetChildNodes(None.__class__.__mro__[0]):  # iterate pages
    pass

# Get revisions for a specific page
import aspose.note as an

doc2 = Document("MyNotes.one", opts)
pages = doc2.GetChildNodes(an.Page)
if pages:
    history = doc2.GetPageHistory(pages[0])
    print(f"Revision count: {history.Count}")
    for rev in history:
        print(f"  Modified: {rev.LastModifiedTime}")

Note: GetPageHistory یک مقدار خالی برمی‌گرداند PageHistory object زمانی که LoadHistory is False (پیش‌فرض). همیشه تنظیم کنید opts.LoadHistory = True قبل از بارگذاری اگر به داده‌های بازنگری نیاز دارید.

ذخیره‌سازی و استخراج

از Document.Save برای خروجی به PDF استفاده کنید. PDF تنها فرمت خروجی پشتیبانی‌شده است.

در یک فایل ذخیره کنید

با مسیر فایل Document.Save() را فراخوانی کنید و از SaveFormat.Pdf برای نوشتن مستقیم خروجی بر روی دیسک استفاده کنید:

from aspose.note import Document, SaveFormat

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

در یک جریان در-حافظه ذخیره کنید

به‌جای مسیر، یک بافر io.BytesIO قابل نوشتن را برای ضبط بایت‌های PDF در حافظه پاس کنید:

import io
from aspose.note import Document, SaveFormat

doc = Document("MyNotes.one")
buf = io.BytesIO()
doc.Save(buf, SaveFormat.Pdf)
pdf_bytes = buf.getvalue()

با گزینه‌ها ذخیره کنید

از PdfSaveOptions در aspose.note.saving استفاده کنید تا صفحات گنجانده‌شده در خروجی PDF صادر شده را کنترل کنید:

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

doc = Document("MyNotes.one")

# Export pages 2 and 3 only (zero-based index)
opts = PdfSaveOptions(PageIndex=1, PageCount=2)
buf = io.BytesIO()
doc.Save(buf, opts)
pdf_bytes = buf.getvalue()

Important: خروجی PDF به وابستگی اختیاری ReportLab نیاز دارد. نصب کنید [pdf] افزونه برای فعال‌سازی آن.

تشخیص تغییرات طرح‌بندی

پس از تغییر سند، DetectLayoutChanges را فراخوانی کنید تا معیارهای طرح‌بندی را قبل از ذخیره‌سازی دوباره محاسبه کنید:

from aspose.note import Document, Page

doc = Document()
page = Page()
doc.AppendChildLast(page)

# ... add content to page ...

doc.DetectLayoutChanges()
doc.Save("output.pdf")

نکات و بهترین روش‌ها

• یک بار بارگذاری، بارها پرس‌وجو: Document تمامی را بارگذاری می‌کند .one فایل را هنگام ساخت در حافظه بارگذاری می‌کند. یک مورد نگه دارید Document نمونه و فراخوانی کنید GetChildNodes به‌طور مکرر به‌جای بارگذاری دوبارهٔ فایل برای هر پرس‌وجو.
• Check IsConflictPage: OneNote sync می‌تواند صفحات تعارضی تولید کند. فیلتر کنید با [p for p in doc if not p.IsConflictPage] قبل از پردازش محتوا.
• استفاده کنید LoadHistory=False (پیش‌فرض) برای سرعت: تاریخچهٔ صفحه حافظه و هزینهٔ تجزیهٔ قابل‌توجهی اضافه می‌کند. فقط تنظیم کنید LoadHistory=True وقتی که به‌طور صریح به داده‌های بازبینی نیاز دارید.
• استریم برای فایل‌های بزرگ: به جای رشتهٔ مسیر، یک شیء فایل باز را هنگام خواندن بزرگ .one فایل‌ها برای جلوگیری از باز نگه داشتن فایل پس از اتمام تجزیه.
• Call DetectLayoutChanges before Save: هنگام ساخت یک سند به‌صورت برنامه‌نویسی و افزودن گره‌ها، فراخوانی کنید DetectLayoutChanges() تا اطمینان حاصل شود که مختصات چیدمان قبل از صادر کردن به PDF سازگار هستند.

مسائل رایج

FAQ

چه فرمت‌های OneNote می‌تواند Aspose.Note بخواند؟

هر سه فرمت بخش OneNote: OneNote2007، OneNote2010 و OneNoteOnline. برای شناسایی اینکه کدام نسخه بارگذاری شده است از doc.FileFormat استفاده کنید.

آیا می‌توانم پس از خواندن، به یک فایل .one بازنویسی کنم؟

Aspose.Note برای Python یک کتابخانه‌ی خواندن و استخراج است. برای تولید خروجی PDF از Document.Save استفاده کنید. فرمت باینری OneNote در این نسخه‌ی متن‌باز فقط-خواندنی است.

چگونه می‌توانم صفحه‌ای خاص را بر اساس عنوان بخوانم؟

صفحات را با یک عبارت ژنراتور تکرار کنید و ویژگی متن عنوان را با رشته هدف خود مقایسه کنید:

from aspose.note import Document

doc = Document("MyNotes.one")
target = next(
    (p for p in doc
     if p.Title and p.Title.TitleText and p.Title.TitleText.Text == "My Page"),
    None,
)

چگونه می‌توانم صفحات فرعی را جدا از صفحات سطح بالا بشمارم؟

از page.Level استفاده کنید: سطح ۱ صفحهٔ سطح بالا است، سطح ۲ یک صفحهٔ فرعی است، و به همین ترتیب.

from aspose.note import Document

doc = Document("MyNotes.one")
top_level = [p for p in doc if (p.Level or 1) == 1]
sub_pages  = [p for p in doc if (p.Level or 1) > 1]
print(f"Top-level: {len(top_level)}, Sub-pages: {len(sub_pages)}")

آیا Aspose.Note از فایل‌های فهرست مطالب .onetoc2 پشتیبانی می‌کند؟

نه. فقط فایل‌های بخش .one پشتیبانی می‌شوند. دفترچه‌های .onetoc2 باعث بروز FileCorruptedException می‌شوند.

API Reference خلاصه

همچنین ببینید:

• استخراج متن: استخراج متن ساده و بخش‌های قالب‌بندی‌شده
• صدور PDF: گزینه‌های صادرات، انتخاب صفحه، و خروجی جریان
• تصاویر و پیوست‌ها: استخراج تصاویر جاسازی‌شده و فایل‌های پیوست‌شده
• Tables: تجزیه ساختار جدول و محتوای سلول‌ها
• API Reference: سند
• Aspose.Note — Enterprise Documentation