ملف Xlsx

# إنشاء ملفات XLSX وتعديلها وتحليلها

| المهمة | الأسلوب | |---|---| | **إنشاء** أو **تعديل** باستخدام الصيغ/التنسيق | `openpyxl` — انظر الملاحظات أدناه | | **إدخال** أو **إخراج بيانات مجمعة** | `pandas` (`read_excel`, `to_excel`) | | **نظرة سريعة** على ورقة عمل | `markitdown file.xlsx` — `## SheetName` لكل ورقة؛ يقرأ ملفات `.xlsm` أيضا. لا توجد إحداثيات للخلايا، لذا لا تخطط للتعديلات بناء عليه | | **قراءة** نموذج (الصيغ *والقيم*) | تمريران ل `load_workbook` — انظر الملاحظات |

> `openpyxl` و `pandas` و `markitdown` مثبتة مسبقا — لا تقم بتشغيل `pip install` أولا؛ اكتب السكريبت واستورد مباشرة. فقط إذا فشل الاستيراد (أو كان أمر `markitdown` مفقودا): قم بتشغيل `pip install` للحزمة المفقودة.

> مسارات السكريبتات أدناه نسبية إلى دليل هذه المهارة.

## المتطلبات لكل مخرج

- **خط احترافي** (Arial, Times New Roman) في جميع أنحاء المستند، ما لم يذكر المستخدم خلاف ذلك. - **صفر أخطاء في الصيغ.** لا تسلم أبدا بينما `recalc.py` يبلغ عن `errors_found`. إذا كنت تعتقد أن الخطأ سبق وجودك، فأثبت ذلك: قم بتحميل *الملف الأصلي* باستخدام `data_only=True` وانظر إلى تلك الخلية. الخطأ الذي أدخلته يبدو تماما كالخطأ الذي ورثته. - **استخدم الصيغ، ولا تستخدم النتائج المكتوبة يدويا أبدا.** اكتب `sheet['B10'] = '=SUM(B2:B9)'`، وليس المجموع المحسوب بواسطة Python. يجب أن تعيد ورقة العمل حساباتها عندما تتغير مدخلاتها. - **اتبع مواصفات المستخدم حرفيا.** أسماء علامات التبويب الدقيقة، ورؤوس الأعمدة الدقيقة، والصيغة التي حددها. أي إعادة تصميم تحسب شيئا آخر تفشل، مهما كانت أنيقة. - **وثق كل افتراض ورقم مكتوب يدويا** حيث سيراه القارئ — تعليق خلية، أو خلية مجاورة في نهاية الجدول. استشهد بمصدر حقيقي عندما يكون موجودا (`المصدر: تقرير الشركة 10-K، السنة المالية 2024، الصفحة 45، ملاحظة الإيرادات، [رابط SEC EDGAR]`)؛ عندما يأتي الرقم من المستخدم، قل ذلك بوضوح. - **المصنف الذي *تنشئه* ليقوم شخص ما بملئه** يحتاج إلى شرح موجز يحدد الخلايا التي يجب تعديلها، وصف مثال واحد لقيم واقعية توضح التنسيق المتوقع. لا تضف أبدا مثل هذا الصف إلى ملف طلب منك تعديله. - **تعديل ملف موجود: طابق اتفاقياته تماما.** إنها تتجاوز كل إرشادات هنا. ابحث عن خلايا الإدخال المخصصة أولا — لون خط مميز، تعبئة، أو تظليل يميزها — اكتب هناك فقط، واترك كل صيغة موجودة دون تغيير.

## إعادة الحساب (إلزامي كلما احتوى الملف على صيغ)

يكتب openpyxl الصيغ كسلاسل **بدون قيم مخبأة**. حتى تقوم بإعادة الحساب، تقرأ كل خلية صيغة ك `None` لأي شيء يقرأ القيم المخبأة — `pandas`، `load_workbook(data_only=True)`، ومعظم برامج المعاينة.

```bash python scripts/recalc.py output.xlsx [timeout_seconds] # الافتراضي 30 ```

يقوم LibreOffice بحساب كل صيغة، ويتم **إعادة كتابة الملف في مكانه**، وتحصل على JSON: `status` (`success` | `errors_found`)، `total_formulas`، `total_errors`، وملخص `error_summary` يحدد ما يصل إلى 100 خلية لكل نوع خطأ (`locations_truncated` يخبرك بعدد الخلايا التي تم حجبها — ثق في `total_errors`، وليس طول القائمة). قم بإصلاح ما يحدده وقم بتشغيله مرة أخرى. **JSON مع مفتاح `error` بدلا من `status` يعني أنه لم يتم إعادة حساب أي شيء**، وهذه الحالة فقط تخرج بقيمة غير صفرية — `errors_found` تخرج بقيمة 0، لذا لا تعامل أبدا الخروج النظيف على أنه مصنف نظيف.

**إعادة حساب ناجحة تثبت أن صيغك *تقيم*، وليس أنها *صحيحة*.** نطاق خاطئ بواحد أو مرجع إلى صف خاطئ ينتج عنه ملف نظيف وخال من الأخطاء بأرقام خاطئة. اكتب 2-3 صيغ أولا وتحقق من أنها تسحب القيم التي تتوقعها، قبل بناء الشبكة.

**المصنف الذي يرتبط بملف آخر يفقد تلك الروابط** إذا قمت بإعادة حفظه باستخدام openpyxl ثم أعدت حسابه. تقرأ هذه الصيغة `='[1]Returns Analysis'!$B$2` — `[1]` هو فهرس في قائمة المراجع الخارجية للمصنف، ويحدد *ملفا منفصلا على القرص*، وليس ورقة عمل. نادرا ما يكون هذا الملف موجودا هنا، لذا فإن القيمة المخبأة للخلية هي الشيء الوحيد الذي يحمل بياناتها. يزيل openpyxl هذه القيمة عند الحفظ؛ ثم يتعين على LibreOffice حل المرجع فعليا، ويفشل، ويكتب `#NAME?`، ويحذف كل رابط. يرفض `recalc.py` التشغيل في تلك الحالة — انسخ قيم تلك الخلايا من الملف الأصلي قبل حفظها (`--force` يتجاوز، ويقبل الفقد).

## اختيار الصيغ التي تبقى بعد التحقق

ينفذ LibreOffice عددا أقل من الدوال مقارنة ب Excel، والدالة التي لا يستطيع تقييمها تصبح `#NAME?` حرفيا مدمجا في الملف الذي تسلمه.

- **فضل الدوال من عصر Excel 2007** — `SUMIFS`, `INDEX`, `MATCH`, `IFERROR`, `SUMPRODUCT` — التي لا تحتاج إلى بادئة. - **ست دوال بعد 2007 تعمل، ولكن فقط مع بادئة `_xlfn.`**، لأن openpyxl يكتب صيغتك في XML حرفيا ويخزن Excel أسماء ما بعد 2007 ببادئة (تخفي واجهته البادئة): `_xlfn.TEXTJOIN`, `_xlfn.CONCAT`, `_xlfn.IFS`, `_xlfn.SWITCH`, `_xlfn.MAXIFS`, `_xlfn.MINIFS`. إذا كتبت بدون بادئة، فإن كل منها ينتج `#NAME?`. - **لا تستخدم أبدا `XLOOKUP`, `XMATCH`, `SORT`, `FILTER`, `UNIQUE`, أو `SEQUENCE`.** لا يستطيع LibreOffice في وقت التشغيل تقييمها تحت *أي* بادئة. تقوم الإصدارات الأحدث بتقييمها، لكنها دوال مصفوفة متدفقة و