F. وثائق واجهة برمجة التطبيقات

يتيح لك think-cell التحكم برمجيًا في بعض الوظائف من خلال واجهة برمجة تطبيقات. يمكنك هنا إيجاد نظرة عامة على كل وظائف واجهة برمجة التطبيقات المتاحة، بالإضافة إلى إرشادات عامة حول كيفية إعداد بيئة التطوير لديك من أجل كتابة وحدات ماكرو، أو وظائف إضافية، أو برامج مستقلة تستطيع الوصول إليها.

F.1
بدء الاستخدام
F.2
مرجع واجهة برمجة التطبيقات

F.1 بدء الاستخدام

واجهة برمجة التطبيقات الخاصة ببرنامج think-cell مدمجة في نموذج التنفيذ التلقائي لتطبيقات Office، بحيث يمكن الوصول إليها من أي لغة تستخدمها لبرمجة Office، مثل Visual Basic for Applications أو C#.

نقطة الدخول إلى think-cell هي كائن الوظيفة الإضافية think-cell. يمكن الوصول إليه عبر المجموعة Application.COMAddIns. الاستدعاءات في think-cell متأخرة الربط دائمًا، وبالتالي لا توجد مكتبة أنواع أو مرجع لإضافته. راجع قاعدة معارف Microsoft للحصول على توضيح:

استخدام الربط المبكر والربط المتأخر في التنفيذ التلقائي

بعض وظائف واجهة برمجة التطبيقات هي أساليب تنتمي لكائن الوظيفة الإضافية think-cell في PowerPoint، وبعضها أساليب تنتمي لكائن الوظيفة الإضافية think-cell في Excel. سوف نستخدم tcPpAddIn للمراجع إلى الوظيفة الإضافية لبرنامج PowerPoint وtcXlAddIn للمراجع إلى الوظيفة الإضافية لبرنامج Excel.

F.1.1 Visual Basic for Applications

لكتابة وحدات ماكرو باستخدام Visual Basic for Applications (VBA)، سوف تستخدم بيئة التطوير المدمجة في تطبيق Office المضيف. يمكن الوصول إليها بواسطة الضغط على المفتاحين Alt+F11. عادةً ما يكون تعريف وحدة الماكرو مضمّنًا في وحدة نمطية يمكنك إضافتها من خلال إدراجوحدة نمطية. يمكنك عرض كل وحدات الماكرو المعرّفة لمستند معين بواسطة الضغط على المفتاحين Alt+F8.

للإشارة إلى أن استدعاءات الأساليب في الوظيفة الإضافية think-cell متأخرة الربط، سيكون عليك توضيح المتغير الذي يحتوي على المرجع إليها بمثابة Object:

Dim tcaddin As Object 
Set tcaddin = Application.COMAddIns("thinkcell.addin").Object

مكتبة الأنواع لتطبيق Office المضيف هي المرجع الافتراضي دائمًا. إذا كنت بحاجة للوصول إلى نموذج الكائن لتطبيق Office آخر، سيكون عليك إضافة مكتبة الأنواع الخاصة به كمرجع.

على سبيل المثال، إذا كنت تريد استخدام وحدة ماكرو في PowerPoint لمعالجة بيانات في ورقة Excel قبل تحديث مخطط think-cell منها، سيكون عليك إضافة مكتبة كائنات Microsoft Excel 16.0 يدويًا عبر مربع الحوار مراجعالأدوات في بيئة تطوير VBA.

ملاحظة: 16.0 هو رقم الإصدار لتطبيقات Office 2016 والتطبيقات الأحدث. بالنسبة لتطبيقات Office 2010 أو 2013، سيكون عليك استخدام مكتبات الكائنات 14.0 أو 15.0، على التوالي. إذا كانت لديك إصدارات عديدة مثبتة من تطبيقات Office، فلن يعرض مربع الحوار المراجع سوى مكتبات الكائنات لأحدث إصدار مثبت. سنفترض فيما يلي أنك تستخدم تطبيقات Office 2016 أو إصدار أحدث.

سيؤدي استخدام Application.COMAddIns("thinkcell.addin").Object إلى حصولك دائمًا على كائن الوظيفة الإضافية think-cell لتطبيق Office المضيف الحالي، وهو tcPpAddIn أو tcXlAddIn، بحسب ما إذا كنت تستخدمه في PowerPoint أو Excel. للحصول على مرجع لكائن الوظيفة الإضافية في تطبيق Office الآخر والوصول إلى وظائف واجهة برمجة التطبيقات التي يعرضها، احصل عليه من خلال مثيل تطبيق مناسب.

على سبيل المثال، للحصول على مرجع لـ tcXlAddIn من PowerPoint:

Dim xlapp As Object
Set xlapp = New Excel.Application

Dim tcXlAddIn As Object
Set tcXlAddIn = xlapp.COMAddIns("thinkcell.addin").Object

لاحظ أن هذا الأمر يتطلب إضافة مكتبة كائنات Excel بمثابة مرجع.

نوصي باستخدام العبارة Option Explicit التي تفرض التوضيح الصريح لكل المتغيرات، مما يساعد في تلافي أخطاء البرمجة الشائعة وتحسين الاقتراحات المقدمة من IntelliSense. يمكنك إضافتها تلقائيًا إلى كل الوحدات النمطية من خلال تنشيط الأدواتخياراتإعدادات التعليمات البرمجيةطلب توضيح المتغيرات. وهي مضمنة في كل نماذج التعليمات البرمجية الخاصة بنا.

F.1.2 C#

يمكنك استخدام واجهة برمجة التطبيقات الخاصة ببرنامج think-cell من C# عند تطوير وظائف إضافية وملحقات تعليمات برمجية لمستندات يتم تشغيلها داخل تطبيق Office مضيف، وكذلك عند تطوير تطبيقات مستقلة.

سوف نفترض فيما يلي أنك تستخدم أداة Visual Studio 2017 أو إصدار أحدث لتطوير حلول Office بلغة C#. راجع القسم التالي لمزيد من إرشادات الإعداد الخاصة بتطوير الوظائف الإضافية على وجه التحديد. سوف نشير إلى قالب مشروع Visual Studio الواجب استخدامه عند تناول كل نموذج من نماذج التعليمات البرمجية الخاصة بنا.

لجعل استدعاءات الأساليب إلى كائن الوظيفة الإضافية think-cell متأخرة الربط، وضّح المتغير الذي يحتوي على المرجع لكائن الوظيفة الإضافية think-cell بمثابة dynamic؛ هذا هو أيضًا النوع الذي يستنتجه برنامج التحويل البرمجي عند توضيح المرجع بمثابة var، حتى تستطيع بسهولة كتابة:

var tcPpAddIn = ppapp.COMAddIns.Item("thinkcell.addin").Object;

هنا ppapp هو مرجع لكائن PowerPoint Application يتم تحميل think-cell بداخله.

للوصول إلى نموذج الكائن لتطبيق Office، سيكون عليك إضافة مكتبة الأنواع الخاصة به أو تجميع التوافق الأساسي (PIA) له بمثابة مرجع لمشروعك. نوصي بإضافة مكتبة الأنواع إذا أمكن وذلك نظرًا لأن Visual Studio سيقوم تلقائيًا بإضافة مرجع لتجميع التوافق الأساسي المرادف في حالة توفر واحد، أو إنشاء تجميع توافق من مكتبة الأنواع إذا لم يكن هناك واحد متوفر (انظر هنا).

على سبيل المثال، لكي تتمكن من الحصول على المرجع لكائن الوظيفة الإضافية think-cell على النحو المبين أعلاه، سيكون عليك إضافة مكتبة كائنات Microsoft PowerPoint 16.0 الموجودة في علامة التبويب مكتباتالأنواع COM ضمن مربع الحوار إدارة المراجع . بحسب نوع مشروعك، يتم الوصول إلى مربع الحوار هذا بواسطة النقر بزر الماوس الأيمن فوق المراجع أو التبعيات في مستكشف الحلول وتحديد إضافة مرجع (COM).

ملاحظة: 16.0 هو رقم الإصدار لتطبيقات Office 2016 والتطبيقات الأحدث. من خلال استخدام الخيار تضمين أنواع التوافق، الممكّن افتراضيًا من أجل مرجع لمكتبة أنواع COM، سيكون أي تطبيق يتم تجميعه مع استخدام هذا المرجع متوافقًا مع الإصدارات السابقة (والتالية) الأخرى لتطبيق Office طالما أن كل الواجهات المستخدمة موجودة في نموذج الكائن الخاص به. انظر هنا لمزيد من المعلومات.

تشير وظائف واجهة برمجة التطبيقات الخاصة ببرنامج think-cell إلى الأخطاء باستخدام فئات COM HRESULT. يتم تعيين بعض هذه الفئات تلقائيًا على فئات استثناءات NET. المرادفة، انظر كيفية: تعيين فئات HRESULT واستثناءات .

F.1.2.1 تطوير وظائف إضافية

لتطوير وظائف إضافية لتطبيق Office، أو ملحقات تعليمات برمجية لمستندات Office، سوف تستخدم الوظيفة الإضافية VSTO لـ PowerPoint/Excel وقوالب مشروعات قالب/مصنف VSTO لـ Excel. تعد هذه الأدوات جزءًا من مجموعة Office Developer Tools for Visual Studio المثبتة ضمن التكوين الافتراضي. في حالة عدم توفر هذه الأدوات والقوالب في النسخة المثبتة لديك من Visual Studio، يمكنك إضافتها، على سبيل المثال، من خلال الانتقال إلى الإعداداتالتطبيقاتVisual Studio 2022تعديلمجموعات الأدوات الأخرى، ثم تحديد تطوير Office/SharePoint والنقر فوق تعديل. انظر أيضًا وثائق Microsoft هنا وهنا.

يتم دائمًا تحميل تجميع التوافق الأساسي لتطبيق Office المضيف للقالب المحدد افتراضيًا. إذا كنت بحاجة للوصول إلى نموذج الكائن لتطبيق Office آخر، سيكون عليك إضافة مكتبة الأنواع الخاصة به كمرجع على النحو الموضح أعلاه.

ملاحظة: لا يمكن استخدام واجهة برمجة التطبيقات الخاصة ببرنامج think-cell من وظائف Office الإضافية—على الويب والتي أصبحت تُعرف الآن مع الأسف على سبيل الاختصار باسم "وظائف Office الإضافية" من Microsoft—نظرًا لأنها لا تستطيع التفاعل مع نموذج كائن تطبيق Office مباشرةً، ولا تستطيع على وجه الخصوص التفاعل مع وظائف COM الإضافية مثل think-cell.

F.2 مرجع واجهة برمجة التطبيقات

F.2.1
تحديث العناصر وقوالب العروض التقديمية ببيانات Excel
F.2.2
التحكم في الأنماط
F.2.3
استيراد مخططات Mekko Graphics
F.2.4
متنوع

F.2.1 تحديث العناصر وقوالب العروض التقديمية ببيانات Excel

يمكن استخدام الوظائف الواردة في هذا القسم لتحديث عناصر think-cell برمجيًا، والتي عادةً ما تكون عناصر نائبة في قالب عرض تقديمي، ببيانات من Excel. تقوم UpdateChart بتحديث عناصر think-cell، المحددة بواسطة اسم معين لها في القالب، ببيانات من نطاق Excel منقول كوسيطة. انظر أيضًا مقدمة عن التنفيذ التلقائي لمعرفة كيفية إعداد القالب.

تقوم PresentationFromTemplate بإنشاء مثيل لقالب عرض تقديمي ببيانات من مصنف Excel مرتبط. انظر أيضًا ارتباطات بيانات Excel لمعرفة كيفية إنشاء ارتباطات Excel.

الوظائف الواردة في هذا القسم هي أساليب تنتمي إلى الوظيفة الإضافية think-cell في Excel.

F.2.1.1 UpdateChart

F.2.1.1.1 التوقيع
VBA
tcXlAddIn.UpdateChart( _ 
    target As Object, _ 
    strName As String, _ 
    rgData As Excel.Range, _ 
    bTransposed As Boolean _ 
)
C#
void tcXlAddIn.UpdateChart(
    object target,
    string strName,
    Excel.Range rgData,
    bool bTransposed
);
F.2.1.1.2 الوصف

تقوم هذه الوظيفة بتحديث كل العناصر في target التي تحمل الاسم strName بالبيانات الواردة في rgData. لكي يتم تفسير البيانات بصورة صحيحة للمخططات، يجب أن يكون النطاق rgData مطابقًا لتخطيط ورقة البيانات الافتراضي، أو الإصدار المبدّل، انظر أيضًا إنشاء مخطط من Excel وإدخال تخطيط البيانات. يتم تحديد استخدام الإصدار الافتراضي أو المبدّل بواسطة تعيين bTransposed على false أو trueعلى التوالي. للعناصر الأخرى بخلاف المخططات، مثل الجداول، يتم تجاهل قيمة bTransposed.

target يجب أن يكون Presentation، أو SlideRange، أو Slide مفرد، أو Master، أو CustomLayout.

تتم مطابقة الاسم strName دون حساسية لحالة الأحرف. يجب أن يكون قد تم تعيينه مسبقًا في PowerPoint باستخدام عنصر تحكم الخاصية اسم UpdateChart على النحو الموضح في مقدمة عن التنفيذ التلقائي.

لضمان استهداف العناصر الصحيحة، تأكد من أنها العناصر الوحيدة التي تم تعيين اسم UpdateChart لها على strName في الكائن المنقول بمثابة pres.

إذا كان العنصر المستهدف مرتبطًا بأي نطاق بيانات Excel عند استدعاء هذه الوظيفة، يتم قطع الارتباط. بعد ذلك، لن يتم ربط العنصر بأي نطاق Excel.

F.2.1.1.3 أمثلة

لاستخدام هذه النماذج، قم بإعداد عرض تقديمي على النحو الموضح في مقدمة عن التنفيذ التلقائي، واحفظه بمثابة C:\Samples\UpdateChart\template.pptx.

VBA

لاستخدام هذا النموذج، قم بإضافته إلى وحدة نمطية في مصنف Excel.

وهو يتطلب مرجع لمكتبة كائنات Microsoft PowerPoint 16.0 (انظر Visual Basic for Applications لمعرفة التفاصيل).

سيؤدي تشغيل UpdateChart_Sample في مصنف إلى تحديث المخطط في قالب العرض التقديمي بالبيانات الموجودة في النطاق A1:D5 بأول ورقة منه.

Option Explicit 
 
Sub UpdateChart_Sample() 

    ' Get the range containing the new data 
    Dim rng As Excel.Range 
    Set rng = ActiveWorkbook.Sheets(1).Range("A1:D5") 

    ' Get the think-cell add-in object 
    Dim tcXlAddIn As Object 
    Set tcXlAddIn = Application.COMAddIns("thinkcell.addin").Object 

    ' Get a PowerPoint instance. Hold on to this 
    ' object as long as you want to access the 
    ' generated presentations. There can only be a 
    ' single PowerPoint instance. If there is no 
    ' PowerPoint running, one will be started. 
    ' Otherwise the existing one is used.

    Dim ppapp As Object 
    Set ppapp = New PowerPoint.Application 

    Dim pres As PowerPoint.Presentation 

    ' PowerPoint window visible 
    ' Set pres = ppapp.Presentations.Open( _ 
    '  Filename:="C:\\Samples\\UpdateChart\\template.pptx", _
    '  Untitled:=msoTrue) 

    ' PowerPoint window invisible 

    Set pres = ppapp.Presentations.Open( _
    Filename:="C:\\Samples\\UpdateChart\\template.pptx", _
    Untitled:=msoTrue, _
    WithWindow:=msoFalse)

    Call tcXlAddIn.UpdateChart(pres, "Chart1", rng, False) 

    ' Save the updated presentation 
    pres.SaveAs ("C:\\Samples\\UpdateChart\\template_updated.pptx") 
    pres.Close 

    ppapp.Quit 
End Sub
C#

لاستخدام هذا النموذج، استبدل التعليمة البرمجية في Program.cs ضمن قالب المشروع تطبيق وحدة التحكم بلغة C# به.

وهو يتطلب مراجع لمكتبة كائنات Microsoft PowerPoint 16.0، ومكتبة كائنات Microsoft Excel 16.0، ومكتبة كائنات Microsoft Office 16.0 (انظر C# لمعرفة التفاصيل).

سيؤدي تشغيل التطبيق الناتج إلى تحديث المخطط في قالب العرض التقديمي لكي يحتوي على سلسلة فردية باسم "السلسلة 1" تحمل القيم 1، و2، و3 وحفظ النتيجة بمثابة template_updated.pptx.

using Excel = Microsoft.Office.Interop.Excel;
using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Office = Microsoft.Office.Core;

namespace ConsoleApplication_UpdateChart
{
    class Program
    {
        static void Main()
        {
            Excel.Application xlapp = new Excel.Application { Visible = true };

            Excel.Workbook workbook = xlapp.Workbooks.Add(1);
            Excel.Worksheet worksheet = (Excel.Worksheet)workbook.Sheets[1];
            worksheet.Cells[3, 1] = "Series 1";
            worksheet.Cells[3, 2] = 1;
            worksheet.Cells[3, 3] = 2;
            worksheet.Cells[3, 4] = 3;

            PowerPoint.Application ppapp = new PowerPoint.Application();
            PowerPoint.Presentation presentation = ppapp.Presentations.Open(
                    "C:\\Samples\\UpdateChart\\template.pptx",
                    Office.MsoTriState.msoFalse,
                    Office.MsoTriState.msoTrue
            );

            var tcXlAddIn = xlapp.COMAddIns.Item("thinkcell.addin").Object;
            tcXlAddIn.UpdateChart(
                presentation,
                "Chart1",
                worksheet.get_Range("A1", "D3"),
                false
            );

            presentation.SaveAs("C:\\Samples\\UpdateChart\\template_updated.pptx");
            presentation.Close();
            ppapp.Quit();

            workbook.Close(false);
            xlapp.Quit();
        }
    }
}

F.2.1.2 PresentationFromTemplate

F.2.1.2.1 التوقيع
VBA
tcXlAddIn.PresentationFromTemplate( _ 
    wb As Excel.Workbook, _ 
    strTemplate As String, _ 
    ppapp As PowerPoint.Application _ 
) As PowerPoint.Presentation
C#
PowerPoint.Presentation tcXlAddIn.PresentationFromTemplate(
    Excel.Workbook wb,
    string strTemplate,
    PowerPoint.Application ppapp
);
F.2.1.2.2 الوصف

تستخدم هذه الوظيفة ارتباطات البيانات بين مصنف Excel wb والقالب الذي يحمل اسم الملف strTemplate لإنشاء مثيل لذلك القالب من خلال تحديث العناصر المرتبطة باستخدام البيانات المستمدة من النطاقات المرتبطة بها. تكون النتيجة عرضًا تقديميًا جديدًا داخل مثيل PowerPoint ppapp.

strTemplate قد يكون مسارًا كاملاً أو مسارًا نسبيًا يتم التعامل معه بعد ذلك باعتباره نسبيًا إلى موقع ملف مصنف Excel wb.

يتم تحديث كل العناصر الموجودة في strTemplate والمرتبطة بمصنف Excel wb (بصرف النظر عما إذا كان قد تم تعيينها على التحديث التلقائي أم لا). في العرض التقديمي الناتج، يتم قطع ارتباطات البيانات الخاصة بها لمنع إجراء تغييرات إضافية بهذه العناصر.

يتم ترك العناصر الموجودة في strTemplate والمرتبطة بمصنفات Excel أخرى بخلاف wb دون تغيير وتظل مرتبطة، لذلك يمكن تحديث الارتباطات من مصنفات Excel متعددة من خلال حفظ نتيجة هذه الوظيفة كقالب جديد ثم استدعاء هذه الوظيفة مرة أخرى مع المصنف التالي.

إذا كنت تريد التحكم في ألوان مقاطع المخطط أو تنسيق خلايا الجدول باستخدام ارتباط Excel، يمكنك تعيين نظام الألوان على الخيار استخدام تعبئة ورقة بيانات إضافية (انظر نظام الألوان) أو استخدام ورقة بيانات... (انظر تنسيق جدول) على التوالي. بالمثل، للتحكم في تنسيق الأرقام باستخدام ارتباط Excel، قم بتعيينه على استخدام تنسيق Excel (راجع تنسيق الأرقام).

تأكد من تعيين خيارات التنسيق ذات الصلة وتنسيق الأرقام للخلايا المعنية في Excel قبل استدعاء PresentationFromTemplate.

F.2.1.2.3 أمثلة

لاستخدام هذه النماذج، قم أولاً بإنشاء عرض تقديمي يحتوي على مخطط مكدس مرتبط بالنطاق G1:K4 بأول ورقة في مصنف Excel على النحو الموضح في إنشاء مخطط من Excel. احفظ العرض التقديمي الناتج بمثابة C:\Samples\PresentationFromTemplate\template.pptx والمصنف بمثابة data.xlsx في نفس الدليل.

VBA

لاستخدام هذا النموذج، قم بإضافته إلى وحدة نمطية في مصنف Excel data.xlsx الذي تم إعداده على النحو الموضح أعلاه.

وهو يتطلب مرجع لمكتبة كائنات Microsoft PowerPoint 16.0 (انظر Visual Basic for Applications لمعرفة التفاصيل).

سيؤدي تشغيل PresentationFromTemplate_Sample إلى تغيير القيمة في الخلية Sheet1!H3 المرتبطة بالقيمة الأولى في السلسلة الأولى من المخطط الموجود في template.pptx من i=1 إلى 10، وإنشاء عرض تقديمي جديد مع تحديث المخطط الموجود في القالب لكي يحتوي على تلك القيمة، والتي لم تعد مرتبطة بالمصنف، وحفظه بمثابة output_i.pptx في نفس الدليل الخاص بالقالب.

Option Explicit

Sub PresentationFromTemplate_Sample()
    ' Get the range to modify. It is more efficient
    ' to do this once rather than within the loop.
    Dim rng As Excel.Range
    Set rng = ActiveWorkbook.Sheets(1).Cells(3, 8)

    ' Get the think-cell add-in object
    Dim tcXlAddIn As Object
    Set tcXlAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Get a PowerPoint instance. Hold on to this
    ' object as long as you want to access the
    ' generated presentations. There can only be a
    ' single PowerPoint instance. If there is no
    ' PowerPoint running, one will be started.
    ' Otherwise the existing one is used.
    Dim ppapp As Object
    Set ppapp = New PowerPoint.Application

    Dim i As Integer
    For i = 1 To 10
        ' Modify the range value.
        ' Note: Avoid selecting the cell prior to
        ' changing it. It is very slow and has
        ' undesirable side-effects.
        ' BAD:
        ' rng.Select
        ' ActiveWindow.Selection.Value = 0
        ' GOOD:
        rng.Value = i

        ' Generate a new presentation based on the
        ' linked template.
        Dim pres As PowerPoint.Presentation
        Set pres = tcXlAddIn.PresentationFromTemplate( _
            Excel.ActiveWorkbook, "template.pptx", ppapp _
        )

        ' If you want to modify the new presentation
        ' before saving it this is the place to do it.
        
        ' Save the new presentation
        pres.SaveAs "C:\Samples\PresentationFromTemplate\output_" & i & ".pptx"
        
        ' Explicitly close the presentation when we
        ' are done with it to free its memory.
        ' Letting the object go out of scope is not
        ' sufficient.
        pres.Close
    Next
End Sub
C#

لاستخدام هذا النموذج، استبدل التعليمة البرمجية في Program.cs ضمن قالب المشروع تطبيق وحدة التحكم بلغة C# به.

وهو يتطلب مراجع لمكتبة كائنات Microsoft PowerPoint 16.0، ومكتبة كائنات Microsoft Excel 16.0، ومكتبة كائنات Microsoft Office 16.0 (انظر C# لمعرفة التفاصيل).

سيؤدي تشغيل التطبيق الناتج إلى فتح تطبيق Excel أمامك، وتحميل المصنف data.xlsx، وتغيير القيمة في الخلية H3 المرتبطة بالقيمة الأولى في السلسلة الأولى من المخطط الموجود في template.pptx من i=1 إلى 10، وإنشاء عرض تقديمي جديد مع تحديث المخطط الموجود في القالب لكي يحتوي على تلك القيمة، والتي لم تعد مرتبطة بالمصنف، وحفظه بمثابة output_i.pptx في نفس الدليل الخاص بالقالب.

using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Excel = Microsoft.Office.Interop.Excel;

namespace ConsoleApplication_PresentationFromTemplate
{
    class Program
    {
        static void Main()
        {
            var xlapp = new Excel.Application { Visible = true };
            var tcXlAddIn = xlapp.COMAddIns.Item("thinkcell.addin").Object;
            var workbook = xlapp.Workbooks.Open("C:\\Samples\\PresentationFromTemplate\\data.xlsx");
            var ppapp = new PowerPoint.Application();
            for (var i = 1; i <= 10; ++i)
            {
                workbook.Sheets[1].Cells[3, 8] = i;

                PowerPoint.Presentation presentation = tcXlAddIn.PresentationFromTemplate(
                    workbook,
                    "C:\\Samples\\PresentationFromTemplate\\template.pptx",
                    ppapp
                );

                presentation.SaveAs("C:\\Samples\\PresentationFromTemplate\\output_" + i + ".pptx");
                presentation.Close();
            }
            ppapp.Quit();
            workbook.Close(false);
            xlapp.Quit();
        }
    }
}

F.2.2 التحكم في الأنماط

يمكن استخدام الوظائف الواردة في هذا القسم لتحميل أنماط think-cell، وفحصها، وإزالتها برمجيًا. تقوم LoadStyle بتحميل نمط من ملف نمط في شريحة رئيسية أو تخطيط مخصص واحد. تقوم LoadStyleForRegion بتحميل نمط من ملف نمط في منطقة محددة من تخطيط مخصص. تُعيد GetStyleName اسم النمط الذي تم تحميله في شريحة رئيسية أو تخطيط مخصص. تقوم RemoveStyles بإزالة كل الأنماط من تخطيط مخصص.

انظر إنشاء نمط think-cell وتنسيق ملف النمط لمزيد من المعلومات حول إنشاء الأنماط وتحريرها. انظر تحميل ملفات الأنماط لمزيد من المعلومات حول تحميلها.

الوظائف الواردة بهذا القسم هي أساليب تنتمي إلى الوظيفة الإضافية think-cell في PowerPoint.

F.2.2.1 LoadStyle

F.2.2.1.1 التوقيع
VBA
tcPpAddIn.LoadStyle( _ 
    CustomLayoutOrMaster As Object, _ 
    FileName As String 
)
C#
void tcPpAddIn.LoadStyle(
    object CustomLayoutOrMaster,
    string FileName
);
F.2.2.1.2 الوصف

تقوم هذه الوظيفة بتحميل النمط الموجود في ملف النمط في FileName في تخطيط رئيسي أو مخصص يتم تحديده عبر المعلمة CustomLayoutOrMaster.

CustomLayoutOrMaster يجب أن يكون CustomLayout أو Master.

عند التطبيق على تخطيط مخصص تم تعيين نمط إقليمي به (راجع LoadStyleForRegion)، ستتم إزالة النمط الإقليمي. يعني ذلك أنك بحاجة إلى تحميل النمط الذي يجب تطبيقه على باقي الشريحة باستخدام هذه الوظيفة قبل تحميل نمط مقيد بمنطقة معينة.

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

F.2.2.1.3 أمثلة
VBA

لاستخدام هذا النموذج، أضف التعليمات البرمجية التالية إلى وحدة نمطية في PowerPoint (راجع Visual Basic for Applications لمعرفة التفاصيل).

Option Explicit
 
Sub LoadStyle_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim master As Master
    Set master = Application.ActivePresentation.Designs(1).SlideMaster

    Dim style As String
    style = "C:\some\path\styles\style.xml"

    Call tcPpAddIn.LoadStyle(master, style)
End Sub

F.2.2.2 LoadStyleForRegion

F.2.2.2.1 التوقيع
VBA
tcPpAddIn.LoadStyleForRegion( _ 
    CustomLayout As PowerPoint.CustomLayout, _ 
    FileName As String, _
    Left as Single, _
    Top as Single, _
    Width as Single, _
    Height as Single _
)
C#
void tcPpAddIn.LoadStyleForRegion(
    PowerPoint.CustomLayout CustomLayout,
    string FileName,
    float Left,
    float Top,
    float Width,
    float Height
);
F.2.2.2.2 الوصف

تقوم هذه الوظيفة بتحميل ملف النمط الموجود في FileName في التخطيط المخصص CustomLayout وقصره على منطقة محددة بواسطة Left، Top، Width، Height. في بقية أجزاء الشريحة، يتم تطبيق النمط الذي تم تحميله في الشريحة الرئيسية، أو ذلك الذي تم تحميله سابقًا في التخطيط المخصص باستخدام LoadStyle.

يتم إعطاء المعلمات Left، Top، Width، Height بنقاط PowerPoint. ويحدد Left وTop مسافة الحواف اليسرى والعلوية للمنطقة من الحواف اليسرى والعلوية للتخطيط المخصص، على التوالي. ستقوم عادةً بتعيينها بمثابة كسور من إجمالي ارتفاع الشريحة وعرضها. على سبيل المثال، بالنسبة لمنطقة تغطي الثلثين الأيمنين من التخطيط المخصص، ستقوم بتعيين

Left = CustomLayout.Width / 3
Top = 0
Width = CustomLayout.Width * 2 / 3
Height = CustomLayout.Height

يمكنك أيضًا إضافة شكل يدويًا إلى شريحة أو تخطيط مخصص، أو الاستعلام عن خصائصه Left، Top، Width، Height برمجيًا واستخدام القيم مع LoadStyleForRegion لتقييد النمط إلى نفس المنطقة التي تتم تغطيتها بواسطة الشكل.

يدعم think-cell نمطين بحد أقصى لكل تخطيط مخصص. يتم تعيين أحدهما باستخدام LoadStyle وهو يغطي كل شيء غير مقيد إلى منطقة، ويتم تعيين الآخر باستخدام LoadStyleForRegion.

F.2.2.2.3 أمثلة
VBA

لاستخدام هذا النموذج، أضف التعليمات البرمجية التالية إلى وحدة نمطية في PowerPoint (راجع Visual Basic for Applications لمعرفة التفاصيل).

Option Explicit
 
Sub LoadStyleForRegion_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim layout As CustomLayout
    Set layout = Application.ActivePresentation.Designs(1).SlideMaster.CustomLayouts(2)

    ' Define a region covering the left half of the custom layout
    Dim left, top, width, height As Single
    left = 0
    top = 0
    width = layout.Width / 2
    height = layout.Height

    Dim style As String
    style = "C:\some\path\styles\style.xml"

    Call tcPpAddIn.LoadStyleForRegion(layout, style, left, top, width, height)
End Sub

F.2.2.3 GetStyleName

مدعومة في think-cell 13 والإصدارات الأحدث.

F.2.2.3.1 التوقيع
VBA
tcPpAddIn.GetStyleName( _ 
    CustomLayoutOrMaster As Object _ 
) As String
C#
string tcPpAddIn.GetStyleName(
    object CustomLayoutOrMaster
);
F.2.2.3.2 الوصف

تُعيد هذه الوظيفة اسم النمط الذي تم تحميله في CustomLayout أو Master CustomLayoutOrMaster. هذا نفس الاسم المحدد في السمة name للعنصر <style> بملف النمط المرادف (راجع النمط).

وهي تُعيد سلسلة فارغة في حالة عدم تحميل نمط في CustomLayoutOrMaster. لاحظ أن الشريحة الرئيسية تحتوي دائمًا على نمط يتم تحميله بها عندما يكون think-cell نشطًا وأن اسم النمط لا يمكن أن يكون فارغًا.

في حالة إعادة اسم لـ CustomLayout، فإنه يكون اسم النمط الذي تم تحميله به باستخدام LoadStyle، وليس اسم النمط الذي تم تحميله باستخدام LoadStyleForRegion، إن وُجد.

F.2.2.3.3 أمثلة
VBA

لاستخدام هذا النموذج، أضف التعليمات البرمجية التالية إلى وحدة نمطية في PowerPoint (راجع Visual Basic for Applications لمعرفة التفاصيل).

Option Explicit

Sub GetStyleName_Sample()

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object
    
    ' Get the Master of the first slide of the current presentation
    Dim master As Master
    Set master = Application.ActivePresentation.Slides(1).Master
    
    ' Print the name of the style loaded to the debug console
    Dim name As String
    name = tcPpAddIn.GetStyleName(master)
    Debug.Print name
End Sub

F.2.2.4 RemoveStyles

F.2.2.4.1 التوقيع
VBA
tcPpAddIn.RemoveStyles( _ 
    CustomLayout As PowerPoint.CustomLayout _ 
)
C#
void tcPpAddIn.RemoveStyles(
    PowerPoint.CustomLayout CustomLayout
);
F.2.2.4.2 الوصف

تقوم هذه الوظيفة بإزالة كل الأنماط من التخطيط المخصص CustomLayout. بعد ذلك، يتم تطبيق النمط المحمّل في الشريحة الرئيسية. من الممكن وجود نمط محمّل في التخطيط المخصص ونمط آخر مقيد على منطقة محددة من التخطيط المخصص. نظرًا لأن RemoveStyles تزيل جميع الأنماط، فستتم إزالة النمطين. لا يمكن إزالة النمط المحمّل في الشريحة الرئيسية نظرًا لضرورة وجود نمط صالح مرتبط بالشريحة الرئيسية دائمًا. يمكن الكتابة فوقه باستخدام ملف نمط مختلف.

F.2.2.4.3 أمثلة
VBA

لاستخدام هذا النموذج، أضف التعليمات البرمجية التالية إلى وحدة نمطية في PowerPoint (راجع Visual Basic for Applications لمعرفة التفاصيل).

Option Explicit
 
Sub RemoveStyles_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim layout As CustomLayout
    Set layout = Application.ActivePresentation.Designs(1).SlideMaster.CustomLayouts(2)

    Call tcPpAddIn.RemoveStyles(layout)
End Sub

F.2.3 استيراد مخططات Mekko Graphics

يمكن استخدام الوظائف الواردة في هذه القسم لاستيراد المخططات التي تم إنشاؤها باستخدام Mekko Graphics إلى think-cell وفحصها برمجيًا. تقوم ImportMekkoGraphicsCharts باستبدال مخططات Mekko Graphics بمخططات think-cell المناظرة. تقوم GetMekkoGraphicsXML باستخراج تعريف XML لمخطط Mekko Graphics.

الوظائف الواردة بهذا القسم هي أساليب تنتمي إلى الوظيفة الإضافية think-cell في PowerPoint.

F.2.3.1 ImportMekkoGraphicsCharts

مدعومة في think-cell 13 والإصدارات الأحدث.

F.2.3.1.1 التوقيع
VBA
tcPpAddIn.ImportMekkoGraphicsCharts ( _
    ashp As PowerPoint.Shape() _
) As PowerPoint.Slide
C#
PowerPoint.Slide tcPpAddIn.ImportMekkoGraphicsCharts(
    PowerPoint.Shape[] ashp
);
F.2.3.1.2 الوصف

تستبدل هذه الوظيفة كل مخططات Mekko Graphics في صفيف Shape المنقولة إليه بمخطط think-cell مناظر. يجب أن تكون جميع الأشكال على نفس الشريحة. قبل تعديل الشريحة، ستقوم الوظيفة بإنشاء نسخة من الشريحة غير المعدّلة وإدراجها بعد الإصدار المعدّل مباشرةً.

تُعيد الوظيفة مرجعًا لهذه النسخة، إذا تم إنشاء واحدة.

وهي تُعيد Nothing/null، إذا لم يتم تعديل العرض التقديمي، على سبيل المثال نظرًا لعدم احتواء الصفيف على أي مخططات Mekko Graphics.

F.2.3.1.3 أمثلة
VBA

لاستخدام هذا النموذج، قم بإضافته إلى وحدة نمطية في PowerPoint (انظر Visual Basic for Applications لمعرفة التفاصيل).

سيؤدي تشغيل ImportAll بالعرض التقديمي إلى التنقل عبر الشرائح في العرض التقديمي واستبدال كل مخططات Mekko Graphics المرئية بمخططات think-cell مناظرة، مع إنشاء نسخة من كل شريحة تحتوي على مخطط قبل تعديلها.

Option Explicit

Sub ImportAll()

    ' Get reference to think-cell Object

    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Iterate over copy of original Slides to avoid
    ' iterating over copies inserted by ImportMekkoGraphicsCharts again

    Dim SlidesCopy As New Collection
    Dim Slide As PowerPoint.Slide
    For Each Slide In ActivePresentation.Slides
        SlidesCopy.Add Slide
    Next Slide
    
    For Each Slide In SlidesCopy
    
        ' Construct Array containing only visible shapes on slide
        
        Dim visibleShapes() As PowerPoint.Shape
        ReDim visibleShapes(1 To Slide.Shapes.Count)
        Dim shapeIndex As Long
        For shapeIndex = 1 To Slide.Shapes.Count
            If Slide.Shapes(shapeIndex).Visible Then
                Set visibleShapes(shapeIndex) = Slide.Shapes(shapeIndex)
            End If
        Next shapeIndex
        
        ' Pass Array to ImportMekkoGraphics and store return value
        
        Dim CopySlide As PowerPoint.Slide
        Set CopySlide = tcPpAddIn.ImportMekkoGraphicsCharts(visibleShapes)
        
        ' If Slide was modified...
        If Not CopySlide Is Nothing Then
        ' ... do things with copy of unmodified slide
        End If
    Next Slide
End Sub
C#

لاستخدام هذا النموذج، قم بإضافة هذا الأسلوب إلى الفئة ThisAddIn من قالب المشروع الوظيفة الإضافية VSTO لـ PowerPoint بلغة C# (انظر C# و تطوير وظائف إضافية لمعرفة التفاصيل).

private void ImportAll(PowerPoint.Presentation presentation)
    {
        var tcPpAddIn = presentation.Application.COMAddIns.Item("thinkcell.addin").Object;
        foreach (PowerPoint.Slide slide in presentation.Slides.Cast<PowerPoint.Slide>().ToList())
        {
            PowerPoint.Slide slideCopy = tcPpAddIn.ImportMekkoGraphicsCharts(
                slide.Shapes.Cast<PowerPoint.Shape>().ToArray()
            );
        }
    }

قم بإضافة السطر التالي إلى الأسلوب ThisAddIn_Startup لتشغيل ImportAll بكل عرض تقديمي مفتوح:

Application.PresentationOpen += new PowerPoint.EApplication_PresentationOpenEventHandler(ImportAll);

F.2.3.2 GetMekkoGraphicsXML

مدعومة في think-cell 13 والإصدارات الأحدث.

F.2.3.2.1 التوقيع
VBA
tcPpAddIn.GetMekkoGraphicsXML ( _
    shp As PowerPoint.Shape _
) As String
C#
string tcPpAddIn.GetMekkoGraphicsXML(
    PowerPoint.Shape shp
);
F.2.3.2.2 الوصف

تُعيد هذه الوظيفة XML لمخطط Mekko Graphics في shp بمثابة سلسلة. وهي لا تقوم بتعديل الشكل المنقول إليه.

إذا لم يكن shp مخطط Mekko Graphics، يحدث خطأ E_INVALIDARG (0x80070057).

F.2.3.2.3 أمثلة
VBA

لاستخدام هذا النموذج، أضف التعليمات البرمجية التالية إلى وحدة نمطية في PowerPoint (راجع Visual Basic for Applications لمعرفة التفاصيل).

Option Explicit

Sub GetMekkoGraphicsXMLOfAllShapes()

    ' Get reference to think-cell Object

    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Go through the slides in the presentation and
    ' output the XML of each Mekko Graphics chart on the slide
    ' to the debug console

    Dim slide As PowerPoint.slide
    For Each slide In Application.ActivePresentation.Slides
        Dim shape As PowerPoint.shape
        For Each shape In slide.Shapes
            Debug.Print tcPpAddIn.GetMekkoGraphicsXML(shape)
        Next shape
    Next slide
End Sub
C#

لاستخدام هذا النموذج، استبدل التعليمة البرمجية في Program.cs ضمن تطبيق وحدة التحكم به.

وهو يتطلب مراجع لمكتبة كائنات Microsoft PowerPoint 16.0 ومكتبة كائنات Microsoft Office 16.0 (انظر C# لمعرفة التفاصيل).

سيؤدي تشغيل التطبيق إلى التنقل عبر العرض التقديمي في C:\Samples\GetMekkoGraphicsXML\presentation.pptx وطباعة XML لمخططات Mekko Graphics الموجودة به إلى وحدة التحكم.

using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Office = Microsoft.Office.Core;

namespace Sample
{
    class Program
    {
        static void Main()
        {
            var ppapp = new PowerPoint.Application();
            var presentation = ppapp.Presentations.Open(
                "C:\\Samples\\GetMekkoGraphicsXML\\presentation.pptx",
                /*ReadOnly*/Office.MsoTriState.msoTrue,
                /*Untitled*/Office.MsoTriState.msoTrue,
                /*WithWindow*/Office.MsoTriState.msoFalse
            );

            var tcPpAddIn = ppapp.COMAddIns.Item("thinkcell.addin").Object;
            foreach (PowerPoint.Slide slide in presentation.Slides)
            {
                foreach (PowerPoint.Shape shape in slide.Shapes)
                {
                    string xml = tcPpAddIn.GetMekkoGraphicsXML(shape);
                    Console.WriteLine(xml);
                }
            }

            presentation.Close();
            ppapp.Quit();
        }
    }
}

F.2.4 متنوع

الوظائف الواردة بهذا القسم هي أساليب تنتمي إلى الوظيفة الإضافية think-cell في PowerPoint.

F.2.4.1 StartTableInsertion

مدعومة في think-cell 13 والإصدارات الأحدث.

F.2.4.1.1 التوقيع
VBA
tcPpAddIn.StartTableInsertion()
C#
void tcPpAddIn.StartTableInsertion();
F.2.4.1.2 الوصف

يتسم استدعاء هذا الأسلوب بنفس تأثير النقر فوق جدول في قائمة العناصر في PowerPoint.

مشاركة