Extension:Chart/fa

راهنمای افزونهٔ مدیاویکی

Chart وضعیت انتشار: پایدار
انجام	Tag
توضیحات	نمودارها را بازتاب می‌دهد
نویسنده(گان)	Brooke Vibber, Katie Filbert, Roan Kattouw
سیاست سازگاری	Master maintains backward compatibility.
MediaWiki	>= 1.47.0
تغییر پایگاه داده	خیر
پارامترها $wgChartRequestSizeLimit $wgChartProgressiveEnhancement $wgChartWizardEnabled $wgChartTransformsEnabled $wgChartServiceUrl $wgChartCliPath
Hooks used ChangeTagsListActive LinksUpdateComplete ListDefinedTags PageSaveComplete ParserFirstCallInit RecentChange_save SkinTemplateNavigation::Universal SpecialPage_initList
Licence	پروانۀ همگانی گنو ۳٫۰ یا بعدتر
بارگیری	Download extension Git [?]: Browse repository (Phabricator · GitHub) Gerrit code review Git commit log Download source tarball README
Translate the Chart extension if it is available at translatewiki.net
Issues	Open tasks · گزارش یک مشکل

افزونهٔ Chart قابلیت‌های اساسی تجسم داده‌های تعاملی را ارائه می‌کند که برای جایگزینی برخی از جنبه‌های افزونهٔ Graph ، اما نه همه آن‌ها، طراحی شده‌اند. این افزونه در حال حاضر برای ویکی‌های ویکی‌مدیا در دست توسعه است. برای جزئیات بیشتر در مورد فرآیند توسعه، به Extension:Chart/Project مراجعه کنید.

این افزونه از انواع نمودارهای زیر پشتیبانی می‌کند:

• نمودار خطی
• نمودار ناحیه‌ای
• نمودار میله‌ای
• نمودار دایره‌ای

نصب

افزونهٔ Chart نیاز به نصب افزونه‌ی JsonConfig و همچنین دانلود کتابخانه‌ی Chart Renderer JavaScript (در واقع TypeScript) دارد.

برای دستورالعمل‌های کامل راه‌اندازی، به پروندهٔ README.md در مخزن مراجعه کنید.

محصول ویکی‌مدیا

برای استفاده در تولید ویکی‌مدیا، برای دستورالعمل‌های کلی در مورد استقرار سرویس، به wikitech:Kubernetes/Deployments#Cheatsheet مراجعه کنید. Key bits here:

• find your commit's build image id from chart-renderer's CI, eg "2025-06-24-201619-production"
  • edit deployment-charts's helmfile.d/services/chart-renderer/values.yaml to reference the new version
  • get it +2'd by a deployer
• (as a deployer) log into deployment.codfw.wmnet or deployment.eqiad.wmnet depending on the active data center
  • $ cd /srv/deployment-charts/helmfile.d/services/chart-renderer
    • latest service config should appear within a couple minutes (there's a regular update job)
  • $ helmfile -e staging -i apply --context 5
    • confirm the changes and let it deploy to staging
• test rendering on beta cluster
  • TODO: add a specific page with our planned live test charts
  • TODO: add directions on checking pixel rendering results
• once confirmed good, deploy to main clusters:
  • $ helmfile -e codfw -i apply --context 5
    • confirm the changes and let it deploy to codfw
  • $ helmfile -e eqiad -i apply --context 5
    • confirm the changes and let it deploy to eqiad

نحوهٔ استفاده

To render a chart, you must define a chart definition to associate with the tabular data source you want to render. A chart definition is structured as a relatively simple JSON file; see Extension:Chart/Specification for the syntax details.

Tabular data .tab syntax

All the charts in this example can be rendered from the same data source: Data:Chart Example Data.tab, a fictional dataset. Sample contents for these pages can be found in the sample directory.

• commons:Category:Data:Examples.chart
• commons:Data (namespace)
  • commons:Category:Data:.chart
  • commons:Category:Tabular data

Data:Example.chart

{
    "license": "CC0-1.0",
    "version": 1,
    "source": "Chart Example Data.tab",
    "type": "line",
    "title": {
        "en": "Example Chart Title"
    },
    "subtitle": {
        "en": "Example Subtitle"
    },
    "xAxis": {
        "title": {
        	"en": "Example X Axis Title"
        },
        "format": "none"
    },
    "yAxis": {
        "title": {
            "en": "Example Y Axis Title"
        },
        "format": "none"
    },
    "mediawikiCategories": [
        {
            "name": "Example category",
            "sort": "Its sortkey"
        }
    ],
    "transform": {
        "module": "Optional lua module for data transforms",
        "function": "transform_func",
        "args": {
            "arg_name": "arg_value"
        }
    }
}

Once a chart is defined, you can render it easily using the #chart parser function. In this case, the chart data is defined in Data:Chart Example Data.tab, and the chart itself is defined in Data:Example.Line.chart:

Wikipedia article title

{{#chart:Example.Line.chart}}

Note that a chart can be generic and reused with different data sources, like so:

{{#chart:Population through years.chart
|data=Population of USA.tab
}}

{{#chart:Population through years.chart
|data=Population of UK.tab
}}

{{#chart:Population through years.chart
|data=Population of Poland.tab
}}

Deprecated formats

The Chart definition JSON format originally allowed the title to be a plain string, rather than an object with localized title strings. xAxis and yAxis title fields also supported plain strings, but is now deprecated.

Deprecated:

{
    "license": "CC0-1.0",
    "description": {
        "en": "1993 Canadian federal election"
    },
    "title": "Example chart",
    "xAxis": {
        "title": "month"
    },
    "yAxis": {
        "title": "votes"
    },
}

This should instead be:

{
    "license": "CC0-1.0",
    "description": {
        "en": "1993 Canadian federal election"
    },
    "title": {
      "en": "Example chart"
    },
    "xAxis": {
        "title": {
            "en": "month"
        }
    },
    "yAxis": {
        "title": {
            "en": "votes"
        }
    },
}

Date formats in tabular data

When creating charts with dates on the x-axis, dates in tabular data should be formatted as strings that are exactly 10 characters long in the format:

• YYYY-MM-DD, e.g., 2025-10-20

Other 10 character strings that are parseable by JavaScript's Date.parse() function may also work, though not officially supported.

When dates are detected in the first column of the tabular data, they will be automatically localized based on the wiki's content language.

{
    "license": "CC0-1.0",
    "description": {
        "en": "1993 Canadian federal election"
    },
    "mediawikiCategories": [
        {
            "name": "Data:.tab",
            "sort": ""
        },
        {
            "name": "Data:Examples.tab",
            "sort": ""
        }
    ],
    "schema": {
        "fields": [
            {
                "name": "date",
                "type": "string",
                "title": {
                    "en": "Date",
                    "fr": "Date"
                }
            },
            {
                "name": "pc",
                "type": "number",
                "title": {
                    "en": "PC",
                    "fr": "PC"
                }
            },
            {
                "name": "liberal",
                "type": "number",
                "title": {
                    "en": "Liberal",
                    "fr": "Libéral"
                }
            },
            {
                "name": "ndp",
                "type": "number",
                "title": {
                    "en": "NDP",
                    "fr": "NPD"
                }
            },
            {
                "name": "bq",
                "type": "number",
                "title": {
                    "en": "BQ",
                    "fr": "BQ"
                }
            },
            {
                "name": "reform",
                "type": "number",
                "title": {
                    "en": "Reform",
                    "fr": "Réform"
                }
            }
        ]
    },
    "data": [
        [
            "1993-09-09",
            35,
            37,
            8,
            8,
            10
        ],
        [
            "1993-09-14",
            36,
            33,
            8,
            10,
            11
        ],
        [
            "1993-09-20",
            35,
            35,
            6,
            11,
            11
        ]
    ]
}

مشاهدهٔ مثال‌ها در ویکی‌انبار:

• commons:Data:1993_Canadian_federal_election.tab
• commons:Data:1993_Canadian_federal_election.chart

For years, the dates should be numbers:

{
    "license": "CC0-1.0",
    "description": {
        "en": "New Zealand annual wine production, in millions of litres"
    },
    "sources": "Statistics from New Zealand Winegrowers 1998–2024 annual reports",
    "schema": {
        "fields": [
            {
                "name": "year",
                "type": "number",
                "title": {
                    "en": "Year"
                }
            },
            {
                "name": "production",
                "type": "number",
                "title": {
                    "en": "Wine produced (million litres)"
                }
            }
        ]
    },
    "data": [
        [
            1990,
            54.4
        ],
        [
            1991,
            49.9
        ],
        [
            1992,
            41.6
        ],
        [
            1993,
            32.5
        ],
        [
            1994,
            41.1
        ],
        [
            1995,
            56.4
        ]
    ]
}

Example of charts and tabular data with years on the x axis:

• commons:Data:New_Zealand_Annual_Wine_Production.tab
• commons:Data:New_Zealand_Annual_Wine_Production.chart

See Support for dates ADR in gerrit for more details on date support.

شخصی‌سازی

داده‌های خام

ده رنگ Hex موجود

شخصی‌سازی نمودارها در حال حاضر محدود است. امید است که پس از آزمایش، بحث و ارزیابی، راه‌حل‌هایی برای شخصی‌سازی پیدا شود که دسترسی‌پذیری، رندرینگ مختص دستگاه یا امنیت را به خطر نیندازد.

اندازه

در حال حاضر، نمودارها کل عرض ظرفی را که در آن قرار می‌گیرند، اشغال می‌کنند.

هدف نهایی این است که اطمینان حاصل شود نمودارها صرف نظر از دستگاهی که روی آن خوانده می‌شوند، خوانا نمایش داده شوند؛ برای جزئیات بیشتر به T376845 مراجعه کنید.

پوسته

در حال حاضر، نمودارها به یک پالت رنگ پیش‌فرض محدود شده‌اند. این پالت با دقت و با در نظر گرفتن دسترسی‌پذیری طراحی شده است. تفکر پشت این انتخاب‌های رنگی را می‌توان در T369863 بررسی کرد.

بعضی از نمودارها به تم‌های رنگی خاصی نیاز دارند، برای مثال، برای نمایش داده‌های مربوط به احزاب سیاسی. این یک سوال بی‌پاسخ باقی می‌ماند که چگونه می‌توان به بهترین شکل از این نوع شخصی‌سازی پشتیبانی کرد، بدون اینکه توانایی خوانندگانی که نیازهای دسترسی (مثلاً کوررنگی) دارند را برای استفاده از آنها به خطر انداخت.

توجه

توجه داشته باشید، اگرچه نمودارها در حال حاضر خروجی SVG را ارائه می‌دهند که می‌توان آن را از طریق TemplateStyles استایل‌بندی کرد، لطفاً توجه کنید که استایل‌بندی عناصر SVG مرتبط نباید پایدار در نظر گرفته شود زیرا ممکن است در هر زمانی تغییر کند. لطفاً برای تغییر ظاهر نمودار به CSS تکیه نکنید، زیرا این کار ممکن است در آینده منجر به نمودارهای غیرفعال شود یا با ویژگی‌های دسترسی که اندازه فونت را تغییر می‌دهند و ویژگی‌هایی مانند حالت تاریک تداخل داشته باشد.

بین‌المللی‌سازی

نمودارها فقط می‌توانند در زبان محتوای ویکی جاسازی شوند؛ بنابراین، برای مثال، رشته جستار "uselang" (مثلاً ?uselang=es) روی نمودار تأثیری نخواهد گذاشت.

قالب نمودار از تعریف متن مانند عنوان و برچسب‌ها به زبان‌های مختلف پشتیبانی می‌کند، به طوری که می‌توان از یک نمودار در ویکی‌های زبان‌های مختلف استفاده کرد. این مثال از نموداری را ببینید که از چندین زبان در یک ویکی به زبان اسپانیایی پشتیبانی می‌کند.

مشکلات شناخته‌شده

این نمای پالایش‌شده از تابلوی Charts Phabricator را ببینید.

انواع نمودار

برای همه نمودارها، انتظار می‌رود داده‌ها به صورت ستونی مرتب شوند، به طوری که ستون اول نشان‌دهنده x-axis و ستون‌های بعدی نشان‌دهنده سری‌ها یا منحنی‌ها روی y-axis باشند.

خطی

داده‌های خام

این یک مثال از یک نمودار خطی است.

در مثال زیر، متغیر {{#chart: }} در یک کانتینر {{Image frame }} قرار گرفته است تا عرض نمودار را تنظیم کند و یک برنگاشت نیز به آن اضافه شود. همچنین پیوندی به داده‌های خام جدولی ارائه شده است، که در آن می‌توان اطلاعاتی در مورد منابع داده‌ها یافت:

Wikipedia article title

{{image frame
|content={{#chart:Example.Line.chart}} [[commons:Data:Chart Example Data.tab|'''Raw data''']]
|width = 340
|caption = This is an example of a line chart.
}}

نتیجه را در این بخش ببینید.

میله‌ای

در اینجا نمودار، تمام عرض ناحیه محتوای صفحه را پوشش می‌دهد:

Wikipedia article title

{{#chart:Example.Bar.chart}} <div align="center">[[commons:Data:Chart Example Data.tab|'''Raw data''']]</div>

این منجر به:

داده‌های خام

ناحیه‌ای

داده‌های خام

دایره‌ای

نمودارهای دایره‌ای نوع خاصی از نمودار هستند و منابع داده ممکن است برای نمایش مناسب نیاز به اصلاح داشته باشند.

هنگام خواندن داده‌ها، هر ستون غیر عددی (مثلاً محور x) حذف می‌شود و مجموع تمام ردیف‌ها در نمودار نمایش داده می‌شود.

برای مثال، در جایی که چندین ردیف مقادیر A و B و C را در تاریخ‌های متعدد، مثلاً اول ژانویه و دوم ژانویه، نشان می‌دهند، بخش نمودار دایره‌ای برای A نشان دهنده مجموع مقادیر تمام ردیف‌های A در آن تاریخ‌ها خواهد بود.

داده‌های خام

Finding existing charts

Charts that can be used in articles live on Wikimedia Commons and can be tracked using MediaWiki categories.

This query can be used as a proxy to find charts that others have made and contribute translations, and this to find tab pages that may be used to produce charts.

The set of wiki pages that use charts on any particular wiki can be found in the category whose name is defined at MediaWiki:chart-render-category و MediaWiki:Chart-error-category (Category:Pages using the Chart extension و Category:Pages using the Chart extension with rendering errors on this wiki). Please make sure to connect your wiki categories to d:Q131382738 and d:Q131406605 to make the interwiki search easier.

مهاجرت از افزونهٔ Graph

لطفاً برای نمودارهای قدیمی که باید به افزونه‌ی Charts منتقل شوند، به ردهٔ صفحات ویکی‌پدیا با نمودارهای غیرفعال در زبان‌های مختلف مراجعه کنید. با این حال، برخی از آنها بدون جایگزینی با نمودارهای جدید، حذف شده‌اند. این فهرست را می‌توان با فهرست بایگانی‌شده‌ی ۲۰۰ صفحه‌ی اول از بین ۲۳۸۱۱ صفحه‌ی ویکی‌پدیای انگلیسی که نمودارهایشان غیرفعال شده و از سال ۲۰۲۳، یعنی کمی پس از اضافه شدن الگوها به آن دسته، و متناظر با آنها در زبان‌های دیگر، مقایسه کرد.

مستندات فنی

با توجه به مشکلات Extension:Graph ، تمام تصمیمات مربوط به افزونه جدید با دقت بررسی شده است، با این امید که اعتماد و اطمینان نسبت به جایگزین آن ایجاد شود.

تاکنون، تصمیمات فنی در مخزن کد در پوشه /doc/adr مستند شده‌اند.

پایش خطاها

Failing .chart pages are automatically stored in commons:Category:Pages using the Chart extension with rendering errors. Wiki pages with faulty charts are automatically stored in Category:Pages using the Chart extension with rendering errors in different language versions.

Errors with client side chart rendering will be logged to logstash. (فقط برای توسعه دهندگان)

ابزارهایی برای تولید نمودارها

چندین روش قابل تصور برای تولید و ویرایش نیمه خودکار نمودارها و داده‌های جدولی آنها وجود دارد:

• The script graphDataImport can be used in the web browser to extract data from existing graph wikitext and similar, and convert it to a .tab page, a .chart definition page and new wikitext.
• Generative AI can be prompted to extract data from existing graph wikicode and tables, and convert it to .tab and .chart pages and generate new wikicode, according to given specifications. It can also provide translation of titles, and be utilized to extend and update the .tab page with new data.
• The gadget TabularImportExport can convert Excel and .csv files to and from the .tab pages. You can activate it via your Commons preferences.
• The JSON ویرایش به‌عنوان جدول user interface (part of the Jsonconfig extension) is available from the .tab edit page.
• Some bots can periodically import statistics from the web, or from existing Wikipedia graphs, to .tab or .chart pages, upon request. Such bots include DPLA bot and SLiuBot.
• GraphBot گراف‌های ویکی‌پدیای انگلیسی را به chart تبدیل می‌کند.

همچنین ببینید

• Extension:Chart/Project/FAQ – پرسش‌های رایج
• Transforms