الدالتان Launch وParam

مقالة
10/16/2024

ينطبق على: تطبيقات اللوحة

يقوم بتشغيل صفحة ويب أو تطبيق كانفاس ويوفر الوصول إلى معلمات الإطلاق.

تشغيل

إطلاق صفحة ويب أو تطبيق لوحة. تدعم الوظيفة:

العنوان (مطلوب)، عنوان URL لصفحة الويب الخاصة بتطبيق اللوحة.
المعلمات (اختياري) ، القيم المسماة لتمريرها إلى صفحة الويب أو تطبيق اللوحة. في تطبيق اللوحة، يمكن قراءة المعلمات باستخدام وظيفة Param.
الهدف (اختياري) ، علامة تبويب المتصفح التي يتم فيها تشغيل صفحة الويب أو تطبيق اللوحة.

لا يمكن استخدام الإطلاق إلا في صيغ السلوك.

‏‫ملاحظة

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

عنوان

يتم تشغيل صفحات ويب عبر عنوان URL. على سبيل المثال:

Launch( "https://bing.com" )

يمكنك تشغيل تطبيقات اللوحة باستخدام ارتباط ويب أو URI‎ التطبيق (معرف التطبيق الذي يتضمن البادئة /providers/Microsoft.PowerApps/apps/). للعثور على هذه القيم لتطبيق:

انتقل إلى Power Apps.
من جزء التنقل الأيسر، حدد التطبيقات.
حدد تطبيقك.
حدد التفاصيل من القائمة العليا.
يُمكنك أيضًا تحديد ... (أوامر إضافية) ثم حدد التفاصيل من القائمة المنسدلة.
انسخ ارتباط الويب.

يمكن استخدام ارتباط الويب في أي صفحة ويب وسيقوم بتشغيل تطبيق اللوحة. كما يمكن استخدامها مع Launch. على سبيل المثال:

Launch( "https://apps.powerapps.com/e/{environment id}/a/{app id}?tenantId={tenantId}" )

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

المعلمات

يمكن أن يؤدي التشغيل إلى تمرير المعلمات إلى صفحة الويب أو تطبيق اللوحة. يمكن توفير المعلمات بطريقتين:

قائمة وسيطات لأزواج قيمة الاسم. على سبيل المثال:
```
Launch( "https://bing.com/search", "q", "Power Apps", "count", 1 )
```
سجل قيم الحقول. على سبيل المثال:
```
Launch( "https://bing.com/search", { q: "Power Apps", count: 1 } )
```
يمكن أن يكون هذا النموذج أسهل للعمل معه لأنه يجعل الارتباط بين الاسم والقيمة أكثر وضوحًا. يعتبر هذا هو النموذج الوحيد الذي يدعم وسيطة LaunchTarget الاختيارية.

يتم ترميز العنوان والمعلمات قبل تمريره لاستبدال بعض الأحرف غير الأبجدية الرقمية بـ % ورقم ست عشري كما لو تم استخدا وظيفة EncodeUrl في كل منها.

عند بدء تشغيل صفحة ويب، يمكن تضمين سلسلة استعلام من المعلمات في نهاية عنوان URL. ستتم أضافه إيه معلمات اضافيه يتم توفيرها لوظيفة Launch إلى نهاية سلسله الاستعلام. لا تعمل سلاسل الاستعلام عند تشغيل تطبيق اللوحة.

عند تشغيل تطبيق على جهاز محمول حيث يتم تشغيل هذا التطبيق بالفعل، لن يتم تحديث المعلمات في التطبيق قيد التشغيل. يلزم إعادة تحميل التطبيق لتحديث المعلمات.

استهداف

استخدم وسيطة LaunchTarget لتحديد نافذه المستعرض الهدف التي سيتم فتح صفحه الويب أو التطبيق فيها. استخدم إحدى قيم تعداد LaunchTarget التالية أو توفير النافذة المخصصة الاسم.

LaunchTarget enum	‏‏الوصف
الجديد	يتم فتح صفحة الويب أو التطبيق في نافذة أو علامة تبويب جديدة.
استبدل	تحل صفحة الويب أو التطبيق محل النافذة أو علامة التبويب الحالية.
اسم	بدلاً من قيمة التعداد، استخدم السلسلة النصية الخاصة بك في نافذة أو علامة تبويب الاسم. و Self هو اسم داخلي فقط يستخدم فقط بواسطة وظيفة التشغيل. لن يكون له تأثير على عنوان النافذة التي يشاهدها المستخدمون ولن يتطابق معها. في حالة وجود نافذه أو علامة تبويب بالاسم المحدد بالفعل، سيتم استبدال محتوياتها. خلاف ذلك، سيتم إنشاء نافذة أو علامة تبويب جديدة. لا يمكن أن يبدأ الاسم بحرف الشرطة السفلية "_".

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

‏‫ملاحظة‬

يعد استخدام LaunchTarget مع أي قيمة غير جديد في السيناريوهات المضمنة (على سبيل المثال، Power BI أو SharePoint) اغير مدعوم وقد يتسبب في حدوث سلوك غير متوقع. قد يتغير هذا السلوك مستقبلاً، أو قد يتسبب في حدوث خطأ.

Param

تسترد وظيفة Param معلمة تم تمريرها إلى التطبيق عند إطلاقه. إذا لم يتم تمرير المعلمة المسماة، فإن وظيفة Param تقوم بإرجاع فارغ.

عند تشغيل تطبيق اللوحة من تطبيق لوحة آخر، استخدم وسيطات المعلمة لوظيفة Launch. سيتم ترميز أسماء المعلمات وقيمها تلقائيًا بعنوان URL.
عند تشغيل تطبيق لوحة من صفحه ويب، أضف معلمات إلى سلسلة الاستعلام الخاصة بارتباط ويب تطبيق اللوحة. ويتضمن هذا إضافة &parametername=parametervalue بافتراض أنه قد تم بدء سلسلة الاستعلام بالفعل لـ tenantId. على سبيل المثال، قد تؤدي إضافة &First%20Name=Vicki&category=3 تمرير معلمتين: First Name مع قيمة "Vicki" وcategory مع قيمة "3" (نوع القيمة هو نص). يجب أن يكون ترميز اسم المعلمة وقيمتها إذا كانت تحتوي على مسافات أو أحرف خاصة، على غرار استخدام وظيفة EncodeURL.
أسماء المعلمات حساسة لحالة الأحرف.
سيتم تلقائيًا ترميز أسماء وقيم Param لاستخدامها في تطبيقك.
لا تتغير قيم المعلمات ما لم يُعاد تحميل التطبيق. لا يؤدي استخدام تشغيل على جهاز محمول حيث يعمل التطبيق بالفعل إلى تحديث المعلمات.
حتى إذا كانت المعلمة تحتوي علي رقم، سيكون النوع الذي تم إرجاعه بواسطة Param هو سلسلة نصية دائمًا. سيحدث التحويل إلى أنواع أخرى تلقائيًا أو يستخدم تحويلات صريحة مثل وظيفة Value للتحويل صراحةً إلى رقم.

‏‫ملاحظة‬

وبالنسبة للصفحات المخصصة، فإن المعلمات الوحيدة التي قبلتها الصفحة هي: recordId و entityName.

بناء الجملة

إطلاق (العنوان [، اسم المعلمة 1 ، قيمة المعلمة 1 ، ...] )

العنوان - مطلوب. عنوان صفحه ويب أو معرف تطبيق لتشغيله.
أسماء المعلمات- اختياري. اسم المعلمة.
قيم المعلمة- اختياري. قيم المعلمة المقابلة لتمريرها إلى التطبيق أو صفحه الويب.

إطلاق ( العنوان ، { [ اسم المعلمة 1: المعلمة القيمة 1 ، ...] } [، هدف الإطلاق ] )

العنوان - مطلوب. عنوان صفحه ويب أو معرف تطبيق لتشغيله.
أسماء المعلمات- اختياري. اسم المعلمة.
قيم المعلمة- اختياري. قيم المعلمة المقابلة لتمريرها إلى التطبيق أو صفحه الويب.
LaunchTarget - اختياري. قيمة تعداد LaunchTarget أو اسم مخصص.

المعلمة ( اسم المعلمة)

اسم المعلمة- مطلوب. تم تمرير اسم المعلمة إلى التطبيق.

المعلمات المحجوزة

يتم حجز الكلمات الأساسية التالية للاستخدام الداخلي (بصرف النظر عن الحالة)، ولا ينبغي استخدامها كمعلمة مخصصة في وظيفة Param():

amp%3Bauthmode
amp%3Benableonbehalfof
amp%3Bhidenavbar
amp%3Blocale
appmetadataversion
authmode
channeltype
cordovapath
correlationid
debug
delegatelaunchurl
delegatelaunchurl
disablepreviewredirect
embedderorigin
enableonbehalfof
groupid
hideappsplash
hidenavbar
تلميح
hostclienttype
hostmode
iframecontainerid
isfullscreen
ispreviewmode
loader
loaderType
الإعدادات المحلية
الموقع
packagekind
packageproperties
playerresourcespath
playersessionid
powerappslanguage
screencolor
sdkversion
موقع
skipappmetadata
skipiframecreation
skiplaunchappcache
المصدر
sourcetime
standaloneconsent
teamid
teamtype
tenantId
النسق
uselocalpackagehostresources
userteamrole

الأمثلة

التشغيل البسيط

من تطبيق لوحة إلى صفحة ويب:

الصيغة	الوصف
إطلاق( "http://bing.com/search", "q", "Power Apps", "count", 1 )	فتح صفحة الويب https://bing.com/search?q=Power%20Apps&count=1. يتم فتح نافذة أو علامة تبويب جديدة.
إطلاق( "http://bing.com/search", { q: "Power Apps", count: 1 } )	نفس الأمثلة السابقة باستخدام تدوين السجل المكافئ. يتم فتح نافذة أو علامة تبويب جديدة.
إطلاق( "http://bing.com/search", { q: "Power Apps", count: 1 }, LaunchTarget.Replace )	نفس الأمثلة السابقة، مع استبدال النافذة الحالية أو علامة التبويب بالنتيجة إذا تم تشغيلها في مستعرض ويب.
إطلاق( "http://bing.com/search", { q: "Power Apps", count: 1 }, "Search Results" )	نفس المثال السابق، إنشاء أو استبدال محتويات النافذة أو علامة التبويب المسماة نتائج البحث.

من تطبيق لوحة إلى تطبيق لوحة

قم بتحديث معرف التطبيق واسم الشاشة ورقم السجل حسب الاقتضاء.

Launch( "/providers/Microsoft.PowerApps/apps/YOUR-APP-ID",
        { Navigate: "Second Screen", Record: 34 }
)

من صفحة ويب إلى تطبيق لوحة

قم بتحديث معرف التطبيق ومعرف المستأجر واسم الشاشة ورقم السجل حسب الاقتضاء.

<html>
  <body>
    <a
      href="https://apps.powerapps.com/play/e/YOUR-APP-ENVIRONMENT-ID/a/YOUR-APP-ID?tenantId=YOUR-TENANT-ID&Navigate=Second%20Screen&Record=34"
    >
      Launch canvas app
    </a>
  </body>
</html>

معلمة بسيطة

أمثلة تشغيل بسيطة أعلاه لتشغيل تطبيق لوحة من صفحة ويب أو من تطبيق لوحة آخر تعرض أمثلة بسيطة لوظيفة Param:

صيغة	‏‏الوصف	نتيجة
المعلمة ( "التنقل")	تم توفير معلمة Navigate عند بدء تشغيل التطبيق وإرجاعه.	"شاشة أخرى"
المعلمة ( "سجل")	تم توفير معلمة Record عند بدء تشغيل التطبيق. وعلي الرغم من انه قد تم تمريرها كرقم إلى وظيفة Launch، فستكون النتيجة من Param سلسله نصيه يمكن تحويلها ضمنيا أو بوضوح إلى أنواع أخرى.	"34"
المعلمة ( "المستخدم")	لم يتوفير المعلمة User. يتم إرجاع قيمة فارغ التي يمكن اختبارها باستخدام وظيفة IsBlank.	خلبي

أمثله خطوه بخطوه لـ Launch وParam

تم استخدام قالب تخطيط كمبيوتر لوحي عرض المنتج للأمثلة التالية. لإنشاء تطبيق باستخدام هذا القالب، اتبع الخطوات من مقالة إنشاء تطبيق وحدد قالب عرض المنتج. كما يمكنك استخدام التطبيق الخاص بك.

مثال - تشغيل

انتقل إلى Power Apps.
من جزء التنقل الأيسر، حدد التطبيقات.
حدد تطبيقك ثم حدد تحرير.
حدد إدراج من القائمة، ثم حدد Label.
انقل التسمية إلى أسفل يمين الشاشة.
من جزء الخصائص على الجانب الأيسر، حدد اللون على أنه أبيض وقم بتعيين سمك الحد عند 1.
حدد خاصية Text من الجانب الأيمن وأدخل نصًا كـ أجهزة كمبيوتر لوحية لسطح المكتب في الأخبار.
من قائمه الخصائص في الجزء الأيسر العلوي، حدد OnSelect.
أدخل صيغة كـ Launch("https://www.bing.com/news/search","q","Microsoft Surface tablets"). يمكنك أيضًا استخدام أي عنوان URL ومعلمة وكلمات رئيسية أخرى من اختيارك.
احفظ التطبيق وانشره.
قم بتشغيل التطبيق.
حدد تسمية أجهزة Surface اللوحية في الأخبار لبدء البحث عن الأخبار باستخدام الكلمات الأساسية Microsoft لأجهزة Surface اللوحية.

تلميح

لإمكانية التوسع، يمكنك استبدال الكلمات الرئيسية التي تم إدخالها يدويًا في وظيفة Launch بـ المتغيرات.

مثال - Param

انتقل إلى Power Apps.
من جزء التنقل الأيسر، حدد التطبيقات.
حدد تطبيقك ثم حدد تحرير.
حدد إدراج من القائمة، ثم حدد Label.
انقل التسمية إلى أسفل يمين الشاشة.
حدد خاصية Text للتسمية من أعلى اليسار.
أدخل صيغة كـ Param("browser"). يمكنك أيضا استخدام معلمه مختلفه من اختيارك.
احفظ التطبيق وانشره.
انسخ ارتباط ويب للتطبيق الخاص بك من Power Apps.
افتح في مستعرض جديد.
قم بلصق "ارتباط ويب التطبيق" في المستعرض وقم بإلحاقه بـ &browser=Microsoft%20Edge في النهاية.
عند تشغيل تطبيقك، يعرض التصنيف قيمة المعلمة التي تم تمريرها.
اغلق عارض التطبيق وقم بتحرير التطبيق.
حدد التطبيقمن طريقه عرض الشجرة علي شريط التنقل الأيمن.
حدد خاصية StartScreen‎ في أعلى اليسار.
أدخل الصيغة كـ If( Param("screen") = "techspecs", TechSpecs ).

إذا كانت الدالة في خاصية StartScreen تتحقق مما إذا كانت المعلمة تساوي قيمة معينة ، في هذه الحالة القيمة techspecs. وعند التطابق، تُرسل عنصر تحكم الشاشة TechSpecs إلى الخاصية StartScreen.

‏‫ملاحظة‬

استبدل اسم عنصر التحكم TechSpecs في اسم الدالة If باسم عنصر تحكم شاشة في تطبيقك في حال عدم استخدامك قالب تطبيق عرض المنتج.
احفظ التطبيق وانشره.
افتح في مستعرض جديد.
قم بلصق "ارتباط ويب التطبيق" في المستعرض وقم بإلحاقه بـ &screen=techspecs في النهاية.
يتم تشغيل التطبيق مباشرة مع TechSpecs على أنه startscreen.