پارامترهای داینامیک

شماره پشتیبانی، ایمیل، قیمت اشتراک، نام شرکت و فایل صوتی معرفی در ده‌ها صفحه و مقاله تکرار می‌شوند. در TDS این‌ها پارامتر داینامیک هستند: یک بار در ادمین تعریف می‌شوند و همه‌جا با {{key}}کپی کد خوانده می‌شوند. تغییر مقدار در ادمین، بدون ویرایش متن‌ها، در کل سیستم اعمال می‌شود.

وضعیت: beta · قرارداد: @tokapps/tokens/paramsکپی کد (خالص) · React: @tokapps/tuk/paramsکپی کد · API: GET /paramsکپی کد · ادمین: «پارامترهای داینامیک»

نمونهٔ زنده

قرارداد

هر پارامتر یک ParamDefinitionکپی کد است:

interface ParamDefinition {  version: 1;  key: string;              // company.phone — حروف کوچک لاتین، رقم و نقطه  type: 'text' | 'richtext' | 'number' | 'money' | 'phone' | 'email' | 'url' | 'date' | 'boolean' | 'image' | 'audio' | 'video' | 'file' | 'json';  label: { fa: string; en?: string };  value: string | number | boolean | MediaValue | Record<string, unknown>;  format?: { numerals?: 'fa' | 'latin'; currency?: 'IRR' | 'IRT'; calendar?: 'persian' | 'gregory'; phone?: 'grouped' | 'plain' };  scope?: 'global' | `theme:${string}` | `product:${string}`;  updatedAt: string; updatedBy: string; revision: number;}

• کلید پس از ساخت تغییر نمی‌کند؛ نوع هم. مقدار نسخه‌دار است و تاریخچه دارد.
• scopeکپی کد خاص‌تر (تم یا محصول) روی globalکپی کد برنده است.
• رسانه (imageکپی کد، audioکپی کد، videoکپی کد، fileکپی کد) مقدار { src, title, subtitle, alt, artwork, duration }کپی کد دارد؛ srcکپی کد نسبی /files/<id>کپی کد یا http(s).
• اعتبارسنجی، قالب‌بندی (ارقام فارسی، مبلغ تومان، تاریخ جلالی) و resolveParamsکپی کد همه در @tokapps/tokens/paramsکپی کد هستند و در سرور هم کار می‌کنند.

نصب منبع در محصول

import { DynamicParamsProvider } from '@tokapps/tuk/params';export function Providers({ children }) {  return (    <DynamicParamsProvider      source={`${process.env.NEXT_PUBLIC_API_URL}/params`}      refreshMs={60_000}      fallback={staticSnapshot}      missing="placeholder"    >      {children}    </DynamicParamsProvider>  );}

sourceکپی کد می‌تواند خود snapshot (برای SSR)، نشانی GET /paramsکپی کد یا تابعی باشد که snapshot برمی‌گرداند. پاسخ ETagکپی کد دارد ("r<revision>"کپی کد) و بازخوانی‌های بعدی با ۳۰۴ بی‌هزینه‌اند.

مصرف در متن

import { Param, DynamicText, useParam } from '@tokapps/tuk/params';<p>تماس با پشتیبانی: <Param k="company.phone" link /></p><DynamicText as="p" text="{{company.name}} — {{company.email}}" />const { formatted, status } = useParam('pricing.pro');

• Paramکپی کد یک چیپ درون‌جریان است؛ chip={false}کپی کد فقط متن می‌دهد؛ linkکپی کد برای phone/email/url لینک می‌سازد.
• کلید ناشناخته با آیکون هشدار و [key]کپی کد دیده می‌شود (رنگ تنها نشانه نیست) و در حالت توسعه هشدار می‌دهد.

سینتکس در متن ساده و مارک‌داون

همین سینتکس در RichTextEditorکپی کد به چیپ قفل‌شده تبدیل می‌شود و در خروجی HTML به <span data-tds-param="company.phone">…</span>کپی کد.

تعریف در ادمین

1. پنل مدیریت → «پارامترهای داینامیک» → «پارامتر جدید».
2. کلید (company.phoneکپی کد)، نوع (شماره موبایل)، برچسب و مقدار را بدهید. برای رسانه فایل را بارگذاری کنید.
3. دکمهٔ کپی، {{company.phone}}کپی کد را به کلیپ‌بورد می‌دهد تا در متن یا ویرایشگر درج شود.
4. هر ویرایش، نسخهٔ جدید می‌سازد و مقدار قبلی در تاریخچه می‌ماند؛ بازگرداندن یک کلیک است.

انواع پارامتر

• انواع رسانه (imageکپی کد، audioکپی کد، videoکپی کد، fileکپی کد) با isMediaType(type)کپی کد از @tokapps/tokens/paramsکپی کد شناخته می‌شوند.
• validatorsکپی کد (requiredکپی کد، patternکپی کد، minکپی کد، maxکپی کد، maxLengthکپی کد، urlکپی کد، emailکپی کد، phoneکپی کد) هنگام ذخیره در سرور و در فرم اجرا می‌شوند.

پارامتر صوتی: تعریف، تنظیم و استفاده

یک پارامتر صوتی یک MediaValueکپی کد است. تنها srcکپی کد الزامی است؛ بقیه برای نمایش پلیر و داک‌اند.

{  "version": 1,  "key": "audio.intro",  "type": "audio",  "label": { "fa": "پیام صوتی معرفی" },  "description": "پخش‌شونده روی داک در صفحهٔ اصلی",  "value": {    "src": "/samples/audio-intro.wav",    "title": "معرفی توکاپس",    "subtitle": "نمونه",    "duration": 4,    "mime": "audio/wav"  },  "scope": "global"}

قواعد MediaValueکپی کد:

• srcکپی کد نسبی (/files/<id>کپی کد، /samples/…کپی کد) یا http(s)کپی کد است؛ javascript:کپی کد و data:کپی کد رد می‌شوند.
• titleکپی کد و artworkکپی کد در پلیر داک نمایش داده می‌شوند؛ altکپی کد فقط برای imageکپی کد لازم است.
• durationکپی کد (ثانیه) برای نمایش زمان در پلیر؛ اختیاری است.

استفاده در ویرایشگر:

1. در نوار ابزار «بلوک پخش از پارامتر صوتی» را بزنید؛ انتخاب‌گر فقط پارامترهای audioکپی کد را نشان می‌دهد.
2. کلید audio.introکپی کد درج می‌شود و در متن مارک‌داون به‌صورت ::player{param=audio.intro}کپی کد ذخیره می‌شود.
3. در رندر، پلیر مقدار زندهٔ پارامتر را می‌خواند؛ اگر ادمین srcکپی کد را عوض کند، همهٔ صفحات بدون ویرایش متن به فایل جدید می‌روند.

import { RichTextEditor } from '@tokapps/editor';import { DynamicParamsProvider } from '@tokapps/tuk/params';<DynamicParamsProvider source="/api/params">  <RichTextEditor label="مقاله" format="markdown" defaultValue="::player{param=audio.intro}" tools={['bold', 'param', 'block']} /></DynamicParamsProvider>

تفاوت با آپلود صوت در نوار ابزار: ابزار «افزودن صوت» فایل را همان‌جا در سند ذخیره می‌کند (گرهٔ playerکپی کد با srcکپی کد ثابت). این مقدار به پارامتر وصل نیست؛ برای استفادهٔ مشترک در چند صفحه، پارامتر بسازید.

ثابت یا قابل تنظیم؟

پس: «پارامتر صوتی» یک نوع داده در سیستم است که ادمین می‌سازد؛ «ابزار تصویر» یک قابلیت ثابت رابط ویرایشگر است که با toolsکپی کد فعال یا غیرفعال می‌شود.

انتقال داده به ویرایشگر و کامپوننت‌های فرم

ویرایشگر و هر کامپوننت کنترل‌شدهٔ دیگر یک قرارداد یکسان دارند:

import { useState } from 'react';import { RichTextEditor } from '@tokapps/editor';import { Input, Button } from '@tokapps/tuk';export function ArticleForm() {  const [title, setTitle] = useState('');  const [body, setBody] = useState('');  return (    <form method="post" action="/api/articles">      <Input label="عنوان" name="title" value={title} onChange={setTitle} />      <RichTextEditor        label="متن مقاله"        name="body"        format="markdown"        value={body}        onChange={(out) => setBody(out as string)}        validators={[{ type: 'required', message: 'متن الزامی است' }]}      />      <Button type="submit" variant="primary">ثبت</Button>    </form>  );}

• برای فرم بدون JavaScript از nameکپی کد استفاده کنید؛ برای کنترل کامل از onChangeکپی کد و valueکپی کد کنترل‌شده.
• کامپوننت‌های دیزاین‌سیستم (Inputکپی کد، Selectکپی کد، Switchکپی کد…) همین الگوی valueکپی کد/onChangeکپی کد/nameکپی کد را دارند؛ پارامتر را با useParamکپی کد می‌خوانید و مقدار اولیه را از آن می‌گیرید.

تحویل خروجی: ذخیره، رندر و generate

1. ذخیره: خروجی onChangeکپی کد را همان‌طور که هست ذخیره کنید؛ در markdownکپی کد متن کوتاه‌تر و قابل جستجو است، در jsonکپی کد ساختار کامل سند (با گره‌های playerکپی کد و paramکپی کد) حفظ می‌شود.
2. رندر در سرور یا SSR: از @tokapps/editor/renderکپی کد استفاده کنید تا پارامترها با مقدار زنده حل شوند:

import { toHTML } from '@tokapps/editor/render';const html = toHTML(articleDoc, { params: snapshot, locale: 'fa', missing: 'placeholder' });

snapshotکپی کد را از GET /paramsکپی کد یا از همان sourceکپی کد پروایدر بگیرید. missingکپی کد مشخص می‌کند کلید ناشناخته چطور نشان داده شود (keepکپی کد، emptyکپی کد، placeholderکپی کد).

3. پیش‌نمایش در ویرایشگر: دکمهٔ «پیش‌نمایش» نوار ابزار، همان سند را فقط‌خواندنی نشان می‌دهد؛ چیپ‌های {{key}}کپی کد مقدار زنده، و بلوک playerکپی کد پلیر پخش روی داک را نشان می‌دهند. ویرایشگر اصلی حفظ می‌شود و با دکمهٔ دوباره به آن برمی‌گردید. (این حالت برای format="markdown"کپی کد هم همان است.)
4. نمایش فقط‌خواندنی در کلاینت: RichTextEditorکپی کد با isReadOnlyکپی کد همان سند را بدون امکان ویرایش نشان می‌دهد؛ پارامترها و پلیر صوتی همان‌جا زنده حل می‌شوند.
5. generate مستندات: هر تغییری در MDX این صفحات با pnpm --filter @tokapps/docs generateکپی کد به public/docs/*.jsonکپی کد، llms.txtکپی کد و mcp/manifest.jsonکپی کد می‌رسد؛ پس از آن مستندات برای ایجنت‌ها هم به‌روز است.

قاعدهٔ ایجنت‌ها

واقعیت‌های شرکت/محصول (شماره، ایمیل، نشانی، قیمت، نام) هرگز به‌صورت ثابت در متن رابط نوشته نمی‌شوند؛ از {{key}}کپی کد یا <Param>کپی کد استفاده می‌شود (قاعدهٔ MCP dynamic-params-for-factsکپی کد). فهرست کلیدهای پروژه از GET /internal/params/keysکپی کد در اختیار سرور MCP است.