نحوه کار با جداول در .NET
این راهنما نشان می‌دهد چگونه جداول را به‌صورت برنامه‌نویسی ساخته، قالب‌بندی و خوانده شود در Aspose.Words FOSS برای .NET، با استفاده از Table, Row، و Cell کلاس‌ها در Aspose.Words.Tables فضای‌نامی همراه با DocumentBuilder. این راهنما شامل ساخت جدول از ابتدا، قالب‌بندی سلول‌ها و ردیف‌ها هنگام ساخت، کنترل چیدمان سراسری جدول و AutoFit، تنظیم عرض‌های دلخواه، ترکیب سلول‌ها و خواندن جدول‌هایی که از پیش در سند بارگذاری شده وجود دارند، می‌شود.
راهنمای گام‌به‌گام
مرحله ۱: نصب بسته
Aspose.Words FOSS for .NET هنوز بستهٔ NuGet را منتشر نکرده است – به‌جای آن کتابخانه را از سورس بسازید. https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git را کلون کنید، سپس Aspose.Words.sln را در حالت Release با SDK .NET بسازید و اسمبلی Aspose.Words حاصل را در پروژه خود ارجاع دهید. این کتابخانه هدف .NET Standard 2.0 را دارد، بنابراین بر روی .NET Framework 4.6.2+ و .NET 6/8/10 اجرا می‌شود.
مرحله ۲: وارد کردن کلاس‌های مورد نیاز
یک دستور using Aspose.Words; برای کلاس‌های اصلی سند (Document، DocumentBuilder) اضافه کنید، و یک دستور using Aspose.Words.Tables; برای کلاس‌های خاص جدول که این راهنما پوشش می‌دهد – Table، Row، Cell، CellFormat، RowFormat، PreferredWidth و enumهای مرتبط.
مرحله ۳: ساخت یک جدول جدید با DocumentBuilder
یک Document و یک DocumentBuilder که به آن متصل است ایجاد کنید، سپس DocumentBuilder.StartTable() را فراخوانی کنید تا یک جدول در مکان‌نما آغاز شود. برای هر سلول در یک ردیف، DocumentBuilder.InsertCell() را فراخوانی کنید، سپس ردیف را با DocumentBuilder.EndRow() ببندید. این کار را برای همان تعداد ردیف‌هایی که جدول نیاز دارد تکرار کنید و کل جدول را با DocumentBuilder.EndTable() ببندید. هر StartTable() نیاز به یک EndTable() متناظر دارد و هر ردیف نیاز به یک EndRow() متناظر دارد، وگرنه وضعیت داخلی سازنده – و درخت سند حاصل – خراب می‌شود.
مرحله ۴: قالب‌بندی سلول‌ها و ردیف‌ها هنگام ساخت
قبل از فراخوانی InsertCell() یا EndRow()، DocumentBuilder.CellFormat و DocumentBuilder.RowFormat را تنظیم کنید تا قالب‌بندی را بر روی سلول‌ها و ردیف‌هایی که سازنده قرار است ایجاد کند اعمال کنید – این دو ویژگی به عنوان قالب برای محتوای جدید عمل می‌کنند، نه تغییر پس‌نگری بر سلول‌های پیش از این وارد شده. CellFormat Borders، Shading، Width، WrapText، FitText، HorizontalMerge، VerticalMerge، VerticalAlignment، PreferredWidth و چهار ویژگی حاشیه‌گذاری (LeftPadding، RightPadding، TopPadding، BottomPadding) را آشکار می‌کند که همه می‌توانند به‌طور همزمان با SetPaddings() تنظیم شوند. RowFormat Borders، Height، HeightRule، AllowBreakAcrossPages و HeadingFormat را نشان می‌دهد. برای بازنشانی هر یک به مقادیر پیش‌فرض قبل از تنظیم مقادیر جدید برای ردیف یا سلول بعدی، CellFormat.ClearFormatting() یا RowFormat.ClearFormatting() را فراخوانی کنید.
مرحله ۵: تنظیم چیدمان سراسری جدول و AutoFit
پس از ایجاد جدول، ویژگی‌های چیدمان را مستقیماً بر روی شیء Table تنظیم کنید: Alignment (TableAlignment)، Bidi، LeftIndent، PreferredWidth، Style، StyleIdentifier، StyleName، StyleOptions (TableStyleOptions) و TextWrapping. برای اعمال یک سبک حاشیه، عرض و رنگ در سرتاسر جدول، Table.SetBorders() را فراخوانی کنید، یا برای تنظیم یک طرف خاص، Table.SetBorder() را استفاده کنید؛ ClearBorders() و ClearShading() آنها را بازنشانی می‌کنند. Table.AutoFit(AutoFitBehavior) اندازه جدول و سلول‌های آن را بر اساس رفتار انتخابی تغییر اندازه می‌دهد – پس از هر ویرایش ساختاری دوباره آن را فراخوانی کنید، زیرا فقط وضعیت جدول را در لحظه اجرای خود بازتاب می‌دهد، نه به‌صورت مداوم.
مرحله ۶: تنظیم عرض‌های ترجیحی و سلول
مقادیر عرض را با روش‌های کارخانه‌ای ایستا PreferredWidth.FromPercent() برای چیدمانی که به عرض صفحه موجود سازگار می‌شود، یا PreferredWidth.FromPoints() برای عرض ثابت ایجاد کنید؛ PreferredWidthType گزارش می‌دهد که چه نوع مقداری (Auto، Percent یا Points) یک PreferredWidth خاص دارد. نتیجه را به Table.PreferredWidth برای کل جدول یا به CellFormat.PreferredWidth برای یک سلول اختصاص دهید.
مرحله ۷: ادغام سلول‌ها
سلول‌ها را به‌عنوان ادغام‌شده علامت بزنید با تنظیم CellFormat.HorizontalMerge یا CellFormat.VerticalMerge (هر دو به‌صورت CellMerge) بر روی سلول‌هایی که باید در ادغام شرکت کنند. اگر سلول‌ها فقط به‌صورت ظاهری با تطبیق عرضشان شبیه به ادغام شده بودند و به‌صورت صریح علامت‌گذاری نشده بودند، Table.ConvertToHorizontallyMergedCells() را فراخوانی کنید تا آن چیدمان بصری را به سلول‌هایی با وضعیت واقعی CellMerge تبدیل کند. CellVerticalAlignment کنترل می‌کند که محتوا چگونه به‌صورت عمودی درون یک سلول تراز شود، مستقل از هر ادغامی.
مرحله ۸: خواندن جدول‌ها از یک سند موجود
برای کار با جدول‌هایی که قبلاً در یک سند بارگذاری شده وجود دارند، Body.Tables را بخوانید (یا ویژگی Tables را بر روی هر Story دیگر) — یک TableCollection — به جای ساخت جدول‌های جدید. Table.Rows یک RowCollection برمی‌گرداند و Row.Cells یک CellCollection برمی‌گرداند؛ هر سه نوع مجموعه از Add()، Insert()، Remove()، RemoveAt()، Contains() و IndexOf() برای ویرایش‌های برنامه‌نویسی پشتیبانی می‌کنند. پس از حذف ردیف‌ها یا سلول‌ها، Table.EnsureMinimum()، Row.EnsureMinimum() یا Cell.EnsureMinimum() را فراخوانی کنید تا گره حداقل ساختار معتبر مورد انتظار Word را حفظ کند — به ترتیب یک ردیف خالی، یک سلول خالی یا یک پاراگراف خالی.
مشکلات رایج و راه‌حل‌ها
یک سند ذخیره‌شده خراب به‌نظر می‌رسد، یا خطایی هنگام ذخیره‌سازی رخ می‌دهد یک ردیف یا خود جدول هرگز بسته نشد. همیشه جفت کنید DocumentBuilder.StartTable() با یک نهایی EndTable(), و هر ردیف را با EndRow() قبل از رفتن به ردیف بعدی یا پایان جدول.
سلول‌های جدید قالب‌بندی‌ای که تنظیم کرده‌ام را دریافت نمی‌کنند CellFormat and RowFormat در DocumentBuilder پس از این که سلول‌های تحت تأثیر قبلاً وارد شدند. تنظیم DocumentBuilder.CellFormat / RowFormat قبل از InsertCell() or EndRow() فراخوانی که محتوایی که می‌خواهید قالب‌بندی شود را ایجاد می‌کند.
جدول پس از ویرایش محتوا، به‌صورت مورد انتظار اندازه‌اش تغییر نمی‌کند. Table.AutoFit(AutoFitBehavior) ساختار جدول را فقط در لحظه‌ای که فراخوانی می‌شود، بازتاب می‌دهد. پس از هر ویرایش ساختاری—اضافه یا حذف ردیف‌ها، سلول‌ها یا محتوا—اگر نیاز به تنظیم مجدد طرح باشد، آن را دوباره فراخوانی کنید.
سلول‌هایی که به‌نظر می‌رسد ادغام شده‌اند، هنگام بازخوانی به‌عنوان سلول‌های جداگانه رفتار می‌کنند. سلول‌ها فقط بر اساس عرض مطابقت داده شدند، نه با flagged with CellMerge. فراخوانی Table.ConvertToHorizontallyMergedCells(), یا تنظیم CellFormat.HorizontalMerge / VerticalMerge به‌صورت صریح بر روی سلول‌هایی که باید ادغام شوند.
حذف ردیف‌ها یا سلول‌ها جدول را در وضعیت نامعتبر می‌گذارد. Word انتظار دارد هر Table, Row, و Cell برای حفظ یک ساختار معتبر حداقل. پس از حذف محتوا به‌صورت برنامه‌نویسی، فراخوانی EnsureMinimum() بر روی گره‌ای که به‌تازگی اصلاح شده است.
سوالات متداول
چگونه می‌توانم جدول را از ابتدا بسازم به‌جای ویرایش جدول موجود؟
از DocumentBuilder استفاده کنید: StartTable() را فراخوانی کنید، سپس برای هر سلول در یک ردیف InsertCell() را اعمال کنید، EndRow() برای بستن ردیف، برای ردیف‌های اضافه تکرار کنید، و EndTable() برای بستن جدول.
چگونه می‌توانم جدول‌های موجود در یک سند بارگذاری‌شده را دریافت کنم؟
خاصیت Tables (یک TableCollection) را در Body بخشی که به آن علاقه‌مند هستید بخوانید، یا در هر Story دیگری مانند سرصفحه یا پاورقی.
چگونه جدول را به درصدی از عرض صفحه تنظیم کنم به‌جای عرض ثابت؟
به‌جای PreferredWidth.FromPoints(value)، Table.PreferredWidth = PreferredWidth.FromPercent(value) را اختصاص دهید.
تفاوت تنظیم حاشیه‌ها با SetBorders و SetBorder چیست؟
Table.SetBorders() یک سبک خط، عرض و رنگ را به‌صورت همزمان به تمام حاشیه‌های جدول اعمال می‌کند؛ Table.SetBorder() یک سمت را تنظیم می‌کند و اجازه می‌دهد سایدهای مختلف فرمت‌های متفاوتی داشته باشند.
چگونه قبل از استفاده مجدد، قالب‌بندی یک سلول یا ردیف را بازنشانی کنم؟
متد CellFormat.ClearFormatting() را بر روی CellFormat سلول فراخوانی کنید، یا RowFormat.ClearFormatting() را بر روی RowFormat ردیف.
