---
read_when:
    - می‌خواهید یک عامل، نتیجه‌ای تعاملی را درون گفت‌وگوی وب نمایش دهد
    - به قرارداد ورودی، امنیت یا نگهداشت `show_widget` نیاز دارید
sidebarTitle: Show widget
summary: ویجت‌های مستقل SVG یا HTML را به‌صورت درون‌خطی در گفت‌وگوی وب رندر کنید
title: نمایش ویجت
x-i18n:
    generated_at: "2026-07-12T10:58:08Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 2de3760ec3aba9e6551eb31129c32f74fc69a8a158f9d6bde5a823136e5eae87
    source_path: tools/show-widget.md
    workflow: 16
---

`show_widget` یک قطعهٔ مستقل SVG یا HTML را به‌صورت درون‌خطی در رونوشت گفت‌وگوی رابط کنترل رندر می‌کند. Plugin همراه Canvas مالک این ابزار است و هر نتیجه را به‌عنوان یک سند Canvas هم‌مبدأ میزبانی می‌کند.

این ابزار فقط زمانی در دسترس است که کلاینت Gateway مبدأ، قابلیت `inline-widgets` را اعلام کند. رابط کنترل این قابلیت را به‌طور خودکار اعلام می‌کند. اجراهای کانال‌هایی مانند Telegram و WhatsApp به `show_widget` دسترسی ندارند.

انتقال قابلیت، بک‌اندهای مدل توکار، سرور برنامهٔ Codex و مبتنی بر CLI را پوشش می‌دهد. فراخوانندگان MCP احراز هویت‌شده با مجوز و فراخوانندگان مستقیم ابزار از طریق HTTP همچنان به‌صورت امن بسته می‌مانند، زیرا قابلیت‌های کلاینت را اعلام نمی‌کنند.

## استفاده از ابزار

عامل دو رشتهٔ الزامی ارائه می‌کند:

<ParamField path="title" type="string" required>
  عنوان کوتاهی که همراه پیش‌نمایش درون‌خطی و در عنوان سند میزبانی‌شده نمایش داده می‌شود.
</ParamField>

<ParamField path="widget_code" type="string" required>
  قطعهٔ مستقل SVG یا HTML. ورودی‌ای که پس از حذف فاصله‌های ابتدا و انتها با `<svg` آغاز شود، در حالت SVG رندر می‌شود؛ تمام ورودی‌های دیگر به‌عنوان قطعهٔ HTML در نظر گرفته می‌شوند. حداکثر طول: ۲۶۲٬۱۴۴ نویسه.
</ParamField>

نتیجهٔ ابزار شامل یک دستگیرهٔ پیش‌نمایش Canvas است؛ بنابراین گفت‌وگوی وب ویجت را مستقیماً از فراخوانی ابزار رندر می‌کند و پس از بارگذاری مجدد تاریخچه، آن را بازیابی می‌کند. رونوشت‌هایی که پیش‌نمایش‌ها را رندر نمی‌کنند، همچنان مسیر Canvas میزبانی‌شده را نشان می‌دهند.

## امنیت و ذخیره‌سازی

اسناد ویجت از یک خط‌مشی امنیت محتوا با محدودیت‌های سخت‌گیرانه استفاده می‌کنند: سبک و اسکریپت درون‌خطی مجاز هستند، تصاویر می‌توانند از نشانی‌های `data:` استفاده کنند و واکشی‌های خارجی و بارگذاری منابع مسدود می‌شوند. تمام نشانه‌گذاری‌ها، سبک‌ها، اسکریپت‌ها و داده‌های تصویر را درون `widget_code` نگه دارید.

`iframe` همیشه `allow-same-origin` را حذف می‌کند، حتی زمانی که حالت سراسری جاسازی رابط کنترل روی `trusted` تنظیم شده باشد؛ بنابراین اسکریپت‌های ویجت نمی‌توانند مبدأ برنامهٔ والد را بخوانند. میزبان Canvas همچنین اسناد ویجت را با سرآیند پاسخ `Content-Security-Policy: sandbox allow-scripts` ارائه می‌کند؛ بنابراین حتی با باز کردن مستقیم نشانی میزبانی‌شده، ویجت به‌جای مبدأ رابط کنترل در یک مبدأ مبهم اجرا می‌شود. سندباکس مرورگر مانع از آن نمی‌شود که یک اسکریپت `iframe` خودش را پیمایش کند؛ فقط کد ویجتی را رندر کنید که مایلید در آن قاب ایزوله اجرا شود.

`iframe` همچنین از [`gateway.controlUi.embedSandbox`](/fa/web/control-ui#hosted-embeds) پیروی می‌کند. سطح پیش‌فرض `scripts` ضمن حفظ جداسازی مبدأ، از ویجت‌های تعاملی پشتیبانی می‌کند.

Canvas در هر نشست حداکثر ۳۲ ویجت نگه می‌دارد (یا اگر نشستی در دسترس نباشد، به‌ازای هر عامل). ایجاد ویجتی دیگر، قدیمی‌ترین سند را در آن محدوده حذف می‌کند.

## مرتبط

- [جاسازی‌های میزبانی‌شدهٔ رابط کنترل](/fa/web/control-ui#hosted-embeds)
- [Plugin ‏Canvas](/fa/plugins/reference/canvas)
- [قابلیت‌های کلاینت پروتکل Gateway](/fa/gateway/protocol#client-capabilities)