Declarative API

Alexandra Klepper

François Beaufort

تاريخ النشر: 18 مايو 2026

شرح	الويب	الإضافات	حالة Chrome	النيّة بالشراء
Github	الإصدار التجريبي للمطوّرين	الإصدار التجريبي للمطوّرين	العرض	النية في إجراء تجربة

استخدِم Declarative API لتحويل نماذج HTML العادية إلى أدوات WebMCP من خلال إضافة تعليقات توضيحية. تحدّد التعليقات التوضيحية اسم الأداة والغرض منها في عنصر <form>، بينما تعمل الحقول كمعلَمات للأداة. يحوّل المتصفّح هذه العناصر إلى تمثيل منظَّم يمكن للوكلاء استخدامه بشكل مشابه للأدوات الإجرائية.

قبل استخدام واجهة برمجة التطبيقات هذه، اطّلِع على أمثلة على حالات الاستخدام.

تسجيل الأداة

أضِف سمات HTML التالية إلى النموذج:

• toolname: سمِّ الأداة بوضوح استنادًا إلى الغرض منها.
• tooldescription: صِف الإجراء الذي تتخذه الأداة والغرض منه.

على سبيل المثال، يتوفّر النموذج التالي على example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

عندما يتصل وكيل toolname، يركّز المتصفّح على النموذج ويملأ حقوله. يبقى النموذج مرئيًا للمستخدم.

في حال إزالة سمة HTML‏ toolname أو tooldescription، سيتم إلغاء تسجيل الأداة.

(اختياري) مَعلمات الأداة

لتحسين الدقة، أضِف سمات HTML التالية إلى عناصر النموذج الفردية:

• toolparamdescription: لربط العناصر بوصف خاصية ضمن مخطّط JSON بدون هذه السمة، يستخدم المتصفّح المحتوى داخل <label> المرتبط ويتخطّى العناصر الفرعية التي يمكن تصنيفها. في حال عدم توفّر تصنيف، يعود المتصفّح إلى aria-description.

يستخدم النموذج التالي المَعلمات الاختيارية للعنصر <select>.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required toolparamtitle="Support type" 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

يتعامل المتصفّح مع هذا النموذج كأداة، ويتم تمثيله باستخدام JSON التالي:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

إرسال النموذج

لديك خياران لإرسال النموذج:

• على المستخدم النقر يدويًا على إرسال لإكمال المهمة.
• أضِف toolautosubmit لتفعيل عملية الإرسال والتنقّل عندما يستدعي النموذج هذه الأداة.

تقدّم واجهة SubmitEvent السمة المنطقية agentInvoked. يتم ضبط هذه السمة على "صحيح" كلما تم تشغيل نموذج من خلال وكيل يعمل بالذكاء الاصطناعي، وذلك لتكييف سلوك تطبيق الويب الخاص بك خصيصًا مع التفاعلات المستندة إلى الوكيل.

بالإضافة إلى ذلك، يتضمّن SubmitEvent الطريقة respondWith(Promise<any>)، ما يتيح لك تمرير وعد إلى المتصفّح يمكنك تنفيذه باستخدام نتائج النموذج. بعد ذلك، يتم تسلسل القيمة الناتجة وإرجاعها إلى النموذج كمخرجات الأداة. لاستخدام هذه الطريقة، يجب أولاً استدعاء preventDefault() لإيقاف عملية إرسال النموذج العادية في المتصفّح.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

تشير إشارات المتصفّح إلى أنّ وكيل الذكاء الاصطناعي نفّذ أداةً باستخدام الحدث "toolactivated". يتم تشغيل هذا الحدث في النافذة بعد ملء حقول النموذج مسبقًا. في المقابل، إذا ألغى المستخدم العملية التي ينفّذها الوكيل أو تم استدعاء الطريقة reset()، سيتم تشغيل الحدث "toolcancel". وكلا الحدثين غير قابل للإلغاء، ويوفّران السمة toolName لتحديد الهوية.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

تعديل مؤشر التركيز

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

• يتم تطبيق :tool-form-active على عنصر HTML form الخاص بالأداة.
• يتم تطبيق :tool-submit-active على زر الإرسال في النموذج، إذا كان متوفّرًا.

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

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

مزيد من المعلومات حول أفضل الممارسات المتعلّقة بالتركيز والأسلوب

التفاعل ومشاركة الملاحظات

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

• قراءة شرح WebMCP وطرح الأسئلة والمشاركة في المناقشة
• اطّلِع على أفضل الممارسات المتعلّقة بمنصة WebMCP.
• راجِع عملية التنفيذ في Chrome على حالة Chrome.
• الانضمام إلى برنامج استخدام الميزات قبل إطلاقها للاطّلاع على واجهات برمجة التطبيقات الجديدة قبل إطلاقها والانضمام إلى قائمتنا البريدية
• إذا كانت لديك ملاحظات حول طريقة تنفيذ Chrome لهذه الميزة، يُرجى إرسال تقرير عن خلل Chromium.