مقدمة
تُعد دالة `getDataFromExcelSheet` إحدى الدوال المضمنة في مكتبة `officejs`، والتي تُتيح للمستخدمين التفاعل مع جداول بيانات Excel من داخل التطبيقات التي أنشأوها باستخدام أدوات تطوير Office.
تسمح الدالة للمستخدمين بقراءة البيانات والكتابة إليها وتنسيقها داخل جداول البيانات، مما يجعلها أداة قوية لإجراء عمليات معالجة البيانات وتحليلها وإدارتها.
1. التركيب:
يتم استدعاء الدالة `getDataFromExcelSheet` باستخدام التركيب التالي:
“`typescript
getDataFromExcelSheet(range: string | Range): Promise;
“`
حيث:
– `range`: نطاق الخلايا الذي تريد استرداد البيانات منه. يمكن أن يكون هذا إما سلسلة نصية تمثل النطاق (مثل `A1:B10`) أو كائن `Range` يمثل النطاق.
– `Data`: كائن يحتوي على البيانات المستردة من النطاق المحدد. يحتوي هذا الكائن على خاصيتين: `values`، وهي مصفوفة ثنائية الأبعاد تحتوي على قيم الخلايا، و`formulas`، وهي مصفوفة ثنائية الأبعاد تحتوي على الصيغ الموجودة في الخلايا.
2. قراءة البيانات من ورقة عمل:
لقراءة البيانات من ورقة عمل، يمكنك استخدام الدالة `getDataFromExcelSheet` على النحو التالي:
“`typescript
const data = await Excel.run(async (context) => {
const sheet = context.workbook.worksheets.getItem(“Sheet1”);
const range = sheet.getRange(“A1:B10”);
const data = await range.getData();
return data;
});
“`
سيؤدي هذا إلى استرداد البيانات من النطاق `A1:B10` في ورقة العمل `Sheet1` وتخزين النتائج في متغير `data`. يمكنك بعد ذلك استخدام متغير `data` للوصول إلى قيم الخلايا والصيغ.
3. الكتابة إلى ورقة عمل:
للكتابة إلى ورقة عمل، يمكنك استخدام الدالة `setDataAsync` على النحو التالي:
“`typescript
const data = [
[“A1”, “B1”],
[“A2”, “B2”],
[“A3”, “B3”]
];
const range = sheet.getRange(“A1:B3”);
await range.setDataAsync(data);
“`
سيؤدي هذا إلى كتابة البيانات الموجودة في متغير `data` إلى النطاق `A1:B3` في ورقة العمل `Sheet1`.
4. تنسيق الخلايا:
لتنسيق الخلايا، يمكنك استخدام الدالة `formatCells` على النحو التالي:
“`typescript
const range = sheet.getRange(“A1:B3”);
await range.formatCells({
font: {
bold: true,
italic: true,
underline: “single”
},
fill: {
color: “red”
}
});
“`
سيؤدي هذا إلى تنسيق الخلايا في النطاق `A1:B3` باستخدام الخط العريض والمائل والتسطير المفرد ولون التعبئة الأحمر.
5. دمج الخلايا:
لدمج الخلايا، يمكنك استخدام الدالة `merge` على النحو التالي:
“`typescript
const range = sheet.getRange(“A1:B3”);
await range.merge();
“`
سيؤدي هذا إلى دمج الخلايا في النطاق `A1:B3` في خلية واحدة.
6. إلغاء دمج الخلايا:
لإلغاء دمج الخلايا، يمكنك استخدام الدالة `unmerge` على النحو التالي:
“`typescript
const range = sheet.getRange(“A1:B3”);
await range.unmerge();
“`
سيؤدي هذا إلى إلغاء دمج الخلايا في النطاق `A1:B3` وفصلها إلى خلايا منفصلة.
7. إدخال صفوف وأعمدة:
لإدخال صفوف وأعمدة، يمكنك استخدام الدالة `insert` على النحو التالي:
“`typescript
const range = sheet.getRange(“A1:B3”);
await range.insert(“right”);
“`
سيؤدي هذا إلى إدخال عمود جديد إلى يمين النطاق `A1:B3`.
خاتمة:
تُعد دالة `getDataFromExcelSheet` أداة قوية لإجراء عمليات معالجة البيانات وتحليلها وإدارتها من داخل التطبيقات التي أنشأتها باستخدام أدوات تطوير Office. فباستخدام هذه الدالة، يمكنك بسهولة قراءة البيانات والكتابة إليها وتنسيقها في جداول بيانات Excel، مما يُتيح لك تطوير تطبيقات فعالة ومُنتجة.