کار با جداول
کار با جدول‌ها
جداول در Aspose.Words FOSS برای .NET به وسیلهٔ Aspose.Words.Tables فضای‌نام: Table, Row، و Cell یک سلسله‌مراتبی سه‌سطحی ترکیبی از نودها تشکیل می‌دهند که در درخت سند همراه با پاراگراف‌ها قرار می‌گیرد. این صفحه ساخت جداول با DocumentBuilder، قالب‌بندی ردیف‌ها و سلول‌ها، کنترل چیدمان کلی جدول، و ادغام سلول‌ها.
مدل شیء جدول
یک Table یک CompositeNode است که شامل گره‌های Row می‌شود، و هر Row یک CompositeNode است که شامل گره‌های Cell می‌شود؛ یک Cell به نوبه خود شامل پاراگراف‌ها و، در صورت امکان، جدول‌های تو در تو است. Table.Rows یک RowCollection برمی‌گرداند، Row.Cells یک CellCollection برمی‌گرداند، و یک Body یا سایر Story هر جدول سطح-بالای موجود در آن را از طریق ویژگی Tables خود، که یک TableCollection است، نشان می‌دهد. هر سه مجموعه از Add()، Insert()، Remove()، RemoveAt()، Contains() و IndexOf() پشتیبانی می‌کنند. Table.EnsureMinimum()، Row.EnsureMinimum() و Cell.EnsureMinimum() به ترتیب کوچک‌ترین محتوای معتبر مورد نیاز یک گره از آن نوع (یک ردیف خالی، یک سلول خالی یا یک پاراگراف خالی) را پس از ویرایش‌های برنامه‌نویسی که یکی از آنها را بدون این محتوا می‌گذارد، پر می‌کنند.
ساخت جدول‌ها با DocumentBuilder
DocumentBuilder.StartTable() یک جدول جدید را در مکان‌نما آغاز می‌کند، InsertCell() یک سلول به ردیف جاری اضافه می‌کند، EndRow() ردیف جاری را می‌بندد و EndTable() جدول را می‌بندد. قبل از فراخوانی InsertCell() یا EndRow()، DocumentBuilder.CellFormat و DocumentBuilder.RowFormat را تنظیم کنید تا قالب‌بندی پیش‌فرض به سلول‌ها و ردیف‌ها هنگام ایجاد آنها اعمال شود – این خصوصیات به‌عنوان قالبی برای محتوایی که سازنده بعداً وارد می‌کند عمل می‌کنند، نه تغییری پس‌زمینه‌ای برای سلول‌های موجود در سند.
قالب‌بندی سلول و ردیف
Cell.CellFormat یک نمونه CellFormat است (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) که دارای ClearFormatting() برای بازنشانی آن و SetPaddings() برای تنظیم همزمان چهار پد سلول است. Row.RowFormat یک نمونه RowFormat است (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) که ClearFormatting() خود را دارد.
قالب‌بندی سراسری جدول و AutoFit
Table خود ویژگی‌های چیدمان را افشا می‌کند – Alignment (TableAlignment)، Bidi، LeftIndent، PreferredWidth، Style، StyleIdentifier، StyleName، StyleOptions (TableStyleOptions)، TextWrapping، و فراداده‌های دسترسی از طریق Title و Description. Table.AutoFit(AutoFitBehavior) اندازه جدول و سلول‌های آن را بر اساس رفتار داده‌شده تغییر اندازه می‌دهد. SetBorder() یک طرف حاشیه را تنظیم می‌کند و SetBorders() تمام حاشیه‌ها را به یک سبک خط، عرض و رنگ یکسان در کل جدول تنظیم می‌کند؛ ClearBorders() و ClearShading() آنها را بازنشانی می‌کنند. ConvertToHorizontallyMergedCells() سلول‌هایی که با تطبیق عرض ادغام شده بودند را به سلول‌هایی تبدیل می‌کند که به‌صورت صریح با HorizontalMerge علامت‌گذاری شده‌اند.
عرض‌های ترجیحی و سلول
PreferredWidth نمایانگر یک عرض و واحد آن است که با متدهای کارخانه ایستا PreferredWidth.FromPercent() یا PreferredWidth.FromPoints() ساخته می‌شود؛ PreferredWidthType تعیین می‌کند که چه نوع مقداری (Auto، Percent یا Points) یک PreferredWidth داده‌شده نگه می‌دارد. هر دو Table.PreferredWidth و CellFormat.PreferredWidth این مقادیر را می‌پذیرند.
سلول‌های ادغام‌شده
CellFormat.HorizontalMerge و CellFormat.VerticalMerge (CellMerge) مشخص می‌کنند که یک سلول چگونه در یک ادغام افقی یا عمودی با همسایه‌های خود مشارکت می‌کند. CellVerticalAlignment نحوه توزیع محتوا در داخل سلول را به صورت عمودی کنترل می‌کند، بدون در نظر گرفتن هر وضعیت ادغام.
نکات و بهترین روش‌ها
- هر
StartTable()را با یکEndRow()متناظر در هر ردیف و یکEndTable()نهایی ببندید – یک ردیف یا جدول بدون بسته شدن، وضعیت داخلی سازنده (و درخت سند تولید‌شده) را خراب می‌کند. - قبل از هر فراخوانی
InsertCell()یاEndRow()،DocumentBuilder.CellFormatوDocumentBuilder.RowFormatرا تنظیم کنید اگر ردیف‌ها یا سلول‌های مختلف در همان جدول نیاز به قالب‌بندی متفاوت دارند؛ سازنده هر آنچه در لحظهٔ درج تنظیم شده باشد را اعمال می‌کند. - پس از حذف محتوا به‌صورت برنامه‌نویسی،
Table.EnsureMinimum()،Row.EnsureMinimum()یاCell.EnsureMinimum()را فراخوانی کنید تا گره حداقل ساختار معتبر مورد انتظار Word را حفظ کند. - از
PreferredWidth.FromPercent()برای جدول‌هایی که باید با عرض صفحهٔ موجود سازگار شوند استفاده کنید، و برای عرض ثابت طرح ازPreferredWidth.FromPoints()بهره ببرید. AutoFitBehaviorزمانی کهTable.AutoFit()را صدا می‌زنید اعمال می‌شود – به‌صورت مداوم هنگام افزودن یا حذف محتوا دوباره اجرا نمی‌شود، بنابراین پس از ویرایش‌های قابل توجه دوباره آن را فراخوانی کنید اگر نیاز به تنظیم مجدد جدول دارید.
مسائل رایج
| مسئله | دلیل | رفع |
|---|---|---|
| جدول به‌نظر خراب می‌رسد یا هنگام ذخیره‌سازی خطا می‌دهد | یک ردیف یا جدول هرگز با EndRow() / EndTable() بسته نشده است | همیشه StartTable() را با یک EndTable() نهایی جفت کنید و هر ردیف را با EndRow() ببندید |
| سلول‌های جدید قالب‌بندی‌ای که تنظیم کرده‌ام را دریافت نمی‌کنند | CellFormat / RowFormat پس از اینکه سلول‌ها وارد شده بودند، در سازنده تغییر یافتند | DocumentBuilder.CellFormat / RowFormat را قبل از فراخوانی InsertCell() / EndRow() برای آن محتوا تنظیم کنید |
| جدول پس از ویرایش‌ها به‌گونه‌ای که انتظار دارم تغییر اندازه نمی‌دهد | AutoFit() وضعیت جدول را در لحظه‌ای که فراخوانی می‌شود منعکس می‌کند، نه به‌صورت پیوسته | پس از ویرایش‌های ساختاری، Table.AutoFit(AutoFitBehavior) را دوباره فراخوانی کنید |
| سلول‌های مجاور که به‌نظر می‌رسد ترکیب شده‌اند، به‌عنوان سلول‌های جداگانه رفتار می‌کنند | سلول‌ها فقط بر اساس عرض مطابقت داده شدند و با CellMerge علامت‌گذاری نشدند | متد Table.ConvertToHorizontallyMergedCells() را فراخوانی کنید یا CellFormat.HorizontalMerge / VerticalMerge را به‌طور صریح تنظیم کنید |
FAQ
چگونه می‌توانم یک جدول را از ابتدا با DocumentBuilder بسازم؟
متد StartTable() را فراخوانی کنید، سپس برای هر سلول در یک ردیف InsertCell()، EndRow() برای بستن ردیف، برای ردیف‌های اضافه تکرار کنید، و در نهایت EndTable() برای بستن جدول.
چگونه عرض جدول را به‌جای عرض ثابت، به‌صورت درصدی تنظیم کنم؟
Table.PreferredWidth = PreferredWidth.FromPercent(value) را به‌جای PreferredWidth.FromPoints(value) اختصاص دهید.
چگونه تمام قالب‌بندی‌ها را در یک سلول یا ردیف بازنشانی کنم؟
متد CellFormat.ClearFormatting() را بر روی CellFormat یک سلول فراخوانی کنید، یا RowFormat.ClearFormatting() را بر روی RowFormat یک ردیف.
چگونه حاشیه‌ها و سایه‌گذاری را برای کل جدول به‌صورت یکجا تنظیم کنم؟
از Table.SetBorders() برای حاشیه یکنواخت در همه طرف‌ها، از Table.SetBorder() برای یک طرف به‌صورت جداگانه، و از Table.SetShading() برای سایه‌گذاری یکنواخت استفاده کنید؛ ClearBorders() و ClearShading() برای بازنشانی آنها استفاده می‌شوند.
خلاصه API Reference
| کلاس / شمارش | توضیح |
|---|---|
Table | گره جدول؛ Rows, AutoFit(), SetBorders(), SetShading(), PreferredWidth |
Row | گره ردیف جدول؛ Cells, RowFormat, EnsureMinimum() |
Cell | گرهٔ سلول جدول؛ CellFormat, EnsureMinimum() |
TableCollection / RowCollection / CellCollection | مجموعه‌های نوعی از گره‌های Table / Row / Cell |
CellFormat | قالب‌بندی به ازای هر سلول: حاشیه‌ها، سایه‌گذاری، پدینگ، وضعیت ادغام، تراز عمودی |
RowFormat | قالب‌بندی به ازای هر ردیف: حاشیه‌ها، ارتفاع، رفتار شکست صفحه |
PreferredWidth / PreferredWidthType | مقدار عرض جدول یا سلول و واحد آن (auto, percent, points) |
AutoFitBehavior | چگونه Table.AutoFit() یک جدول و سلول‌های آن را تغییر اندازه می‌دهد |
CellMerge / CellVerticalAlignment | وضعیت ادغام سلول افقی/عمودی و تراز عمودی محتوا |
TableAlignment / TableStyleOptions / TextWrapping | تراز سراسری جدول، اعمال سبک، و رفتار پیچش متن |
DocumentBuilder.StartTable / InsertCell / EndRow / EndTable | ساخت جدول مبتنی بر مکان‌نما |
