آواتار — Avatar

آواتار هویت یک کاربر را در فهرست، نظر، کارت یا نمایهٔ کاربر نشان می‌دهد. اگر تصویر نباشد یا بارگذاری نشود، حروف اول نام نمایش داده می‌شود؛ این حروف با تابع ساخته می‌شوند. چند آواتار را با همپوشانی کنار هم می‌گذارد و بقیه را در «+N» جمع می‌کند. آواتار غیرتعاملی است و نام شخص همیشه منبع نام دسترسی آن است.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Avatar, AvatarGroup, getInitials } from '@tokapps/tuk';

نمونهٔ زنده

علی رضایی

کد قابل کپی

پایه: حروف اول و تصویر

TSX

import { Avatar } from '@tokapps/tuk';export function UserAvatars() {  return (    <>      <Avatar name="علی رضایی" />      <Avatar name="سارا" />      <Avatar name="Sara Khan" />      <Avatar name="مریم احمدی" src="/avatars/maryam.jpg" />    </>  );}

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

TSX

import { Avatar, AvatarGroup } from '@tokapps/tuk';export function TeamGroup() {  return (    <AvatarGroup label="اعضای تیم" max={3} size="lg">      <Avatar name="علی رضایی" shape="rounded" />      <Avatar name="سارا محمدی" shape="rounded" />      <Avatar name="Mehdi Karimi" shape="rounded" />      <Avatar name="نیلوفر پارسا" shape="rounded" />      <Avatar name="پویا کریمی" shape="rounded" />    </AvatarGroup>  );}

تصویر خراب و نام تزئینی

اگر تصویر بارگذاری نشود، آواتار به حروف اول برمی‌گردد (در این مثال «م‌ا»). در حالت صفحه‌خوان آواتار را نمی‌خواند، چون نام کنار آن نوشته شده است.

TSX

import { Avatar } from '@tokapps/tuk';export function CommentAuthor() {  return (    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 'var(--tds-space-2)' }}>      <Avatar name="مریم احمدی" src="/broken/404.jpg" size="sm" decorative />      مریم احمدی    </span>  );}

تابع

TSX

import { getInitials } from '@tokapps/tuk';getInitials('علی رضایی');        // «ع‌ر» (با نیم‌فاصله)getInitials('Sara Khan');       // «SK»getInitials('سارا');            // «س»getInitials('Mehdi Karimi', 1); // «M»

همهٔ پیکربندی‌ها

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

پراپ	نوع	پیش‌فرض	توضیح
		— (الزامی)	نام گروه برای صفحه‌خوان، مثلاً «اعضای تیم».
			حداکثر تعداد آواتار نمایش‌داده‌شده؛ بقیه در «+N» جمع می‌شوند.
	· · ·		اندازهٔ همهٔ آواتارهای داخل گروه را تعیین می‌کند.
		—	آواتارها.
		—	کلاس روی ریشه.
سایر ویژگی‌ها		—	روی ریشهٔ گروه اعمال می‌شوند.

ورودی	نوع	پیش‌فرض	توضیح
		—	نام کامل.
			اگر کمتر از باشد فقط حرف اول کلمهٔ اول برمی‌گردد.

خروجی است. قواعد: نام فارسی یا عربی‌حروف → حروف اول کلمهٔ اول و آخر با نیم‌فاصله ()؛ نام لاتین → حروف بزرگ ()؛ نام تک‌کلمه‌ای → فقط یک حرف؛ رشتهٔ خالی → خروجی خالی. نیم‌فاصله فقط وقتی اضافه می‌شود که حروف خروجی فارسی یا عربی باشند.

ساختار و اسلات‌ها

code

Avatar (span)              data-tds="avatar"  data-size  data-shape  [data-fallback]  [data-overflow]  data-print├─ img                     data-part="image"   (وقتی تصویر بارگذاری شده)└─ span                    data-part="initials" aria-hidden  (وقتی حروف اول نمایش داده می‌شود)AvatarGroup (div)          data-tds="avatar-group"  data-size  role="group"├─ Avatar …                (حداکثر max تا)└─ span «+N»               data-tds="avatar"  data-overflow="true"  role="img"  data-part="initials" > bdi

بخش ثابت: ریشهٔ با ، تصویر یا حروف اول، و ساختار گروه با . بخش قابل‌تغییر: ، ، و توکن‌های .

همهٔ حالت‌ها

حالت	نشانه	نمایش
تصویر	و بدون	تصویر با .
حروف اول		حروف اول روی زمینهٔ .
خطای تصویر	تصویر، سپس	بازگشت خودکار به حروف اول.
تزئینی	(، بدون )	برای صفحه‌خوان پنهان است.
گروه بیش از سقف	روی آواتار «+N»	نمایش تعداد مازاد با مثل «۳ نفر دیگر».
چاپ پنهان		آواتار در چاپ پنهان.

آواتار تعاملی نیست و حالت‌های hover، focus، فعال یا غیرفعال ندارد. در کد حالت بارگذاری () تعریف نشده است.

تغییرات مجاز برای توسعه‌دهنده

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

تغییرات ممنوع (بنیان ثابت)

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

RTL، کیبورد و صفحه‌خوان

اولین آواتار گروه در RTL سمت راست قرار می‌گیرد و همپوشانی از راست انجام می‌شود.
حروف فارسی با نیم‌فاصله (ZWNJ) از هم جدا می‌شوند تا به هم نچسبند.
کیبورد: آواتار فوکوس نمی‌گیرد. از آن رد می‌شود.
صفحه‌خوان: با = نام؛ گروه با و ؛ «+N» با متن «N نفر دیگر».

صدا، حرکت، چاپ و کاهش حرکت

صدا: در کد پراپ تعریف نشده و کامپوننت بی‌صداست.
حرکت: ندارد (). در کاهش حرکت هم تغییری لازم نیست.
چاپ: پیش‌فرض با حفظ رنگ ()؛ ؛ با پنهان می‌شود.

توکن‌ها

معنایی: ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، .
مقیاس: .
فایل توکن: ؛ فهرست مصرفی در .

قرارداد ARCH

آیکون در این کامپوننت استفاده نمی‌شود؛ هویت فقط با نام یا تصویر است.
تصویر فقط با داده می‌شود و مسیر فایل داخلی در کد مستند نمی‌شود.
تم فقط توکن‌ها را تغییر می‌دهد؛ ساختار و ARIA ثابت است.
Gesture ندارد.

نکات

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

آواتار — Avatar

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Avatar, AvatarGroup, getInitials } from '@tokapps/tuk';

نمونهٔ زنده

علی رضایی

کد قابل کپی

پایه: حروف اول و تصویر

TSX

import { Avatar } from '@tokapps/tuk';export function UserAvatars() {  return (    <>      <Avatar name="علی رضایی" />      <Avatar name="سارا" />      <Avatar name="Sara Khan" />      <Avatar name="مریم احمدی" src="/avatars/maryam.jpg" />    </>  );}

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

TSX

import { Avatar, AvatarGroup } from '@tokapps/tuk';export function TeamGroup() {  return (    <AvatarGroup label="اعضای تیم" max={3} size="lg">      <Avatar name="علی رضایی" shape="rounded" />      <Avatar name="سارا محمدی" shape="rounded" />      <Avatar name="Mehdi Karimi" shape="rounded" />      <Avatar name="نیلوفر پارسا" shape="rounded" />      <Avatar name="پویا کریمی" shape="rounded" />    </AvatarGroup>  );}

تصویر خراب و نام تزئینی

TSX

import { Avatar } from '@tokapps/tuk';export function CommentAuthor() {  return (    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 'var(--tds-space-2)' }}>      <Avatar name="مریم احمدی" src="/broken/404.jpg" size="sm" decorative />      مریم احمدی    </span>  );}

تابع

TSX

import { getInitials } from '@tokapps/tuk';getInitials('علی رضایی');        // «ع‌ر» (با نیم‌فاصله)getInitials('Sara Khan');       // «SK»getInitials('سارا');            // «س»getInitials('Mehdi Karimi', 1); // «M»

همهٔ پیکربندی‌ها

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

پراپ	نوع	پیش‌فرض	توضیح
		— (الزامی)	نام گروه برای صفحه‌خوان، مثلاً «اعضای تیم».
			حداکثر تعداد آواتار نمایش‌داده‌شده؛ بقیه در «+N» جمع می‌شوند.
	· · ·		اندازهٔ همهٔ آواتارهای داخل گروه را تعیین می‌کند.
		—	آواتارها.
		—	کلاس روی ریشه.
سایر ویژگی‌ها		—	روی ریشهٔ گروه اعمال می‌شوند.

ورودی	نوع	پیش‌فرض	توضیح
		—	نام کامل.
			اگر کمتر از باشد فقط حرف اول کلمهٔ اول برمی‌گردد.

ساختار و اسلات‌ها

code

Avatar (span)              data-tds="avatar"  data-size  data-shape  [data-fallback]  [data-overflow]  data-print├─ img                     data-part="image"   (وقتی تصویر بارگذاری شده)└─ span                    data-part="initials" aria-hidden  (وقتی حروف اول نمایش داده می‌شود)AvatarGroup (div)          data-tds="avatar-group"  data-size  role="group"├─ Avatar …                (حداکثر max تا)└─ span «+N»               data-tds="avatar"  data-overflow="true"  role="img"  data-part="initials" > bdi

بخش ثابت: ریشهٔ با ، تصویر یا حروف اول، و ساختار گروه با . بخش قابل‌تغییر: ، ، و توکن‌های .

همهٔ حالت‌ها

حالت	نشانه	نمایش
تصویر	و بدون	تصویر با .
حروف اول		حروف اول روی زمینهٔ .
خطای تصویر	تصویر، سپس	بازگشت خودکار به حروف اول.
تزئینی	(، بدون )	برای صفحه‌خوان پنهان است.
گروه بیش از سقف	روی آواتار «+N»	نمایش تعداد مازاد با مثل «۳ نفر دیگر».
چاپ پنهان		آواتار در چاپ پنهان.

آواتار تعاملی نیست و حالت‌های hover، focus، فعال یا غیرفعال ندارد. در کد حالت بارگذاری () تعریف نشده است.

تغییرات مجاز برای توسعه‌دهنده

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

تغییرات ممنوع (بنیان ثابت)

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

RTL، کیبورد و صفحه‌خوان

اولین آواتار گروه در RTL سمت راست قرار می‌گیرد و همپوشانی از راست انجام می‌شود.
حروف فارسی با نیم‌فاصله (ZWNJ) از هم جدا می‌شوند تا به هم نچسبند.
کیبورد: آواتار فوکوس نمی‌گیرد. از آن رد می‌شود.
صفحه‌خوان: با = نام؛ گروه با و ؛ «+N» با متن «N نفر دیگر».

صدا، حرکت، چاپ و کاهش حرکت

صدا: در کد پراپ تعریف نشده و کامپوننت بی‌صداست.
حرکت: ندارد (). در کاهش حرکت هم تغییری لازم نیست.
چاپ: پیش‌فرض با حفظ رنگ ()؛ ؛ با پنهان می‌شود.

توکن‌ها

معنایی: ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، .
مقیاس: .
فایل توکن: ؛ فهرست مصرفی در .

قرارداد ARCH

آیکون در این کامپوننت استفاده نمی‌شود؛ هویت فقط با نام یا تصویر است.
تصویر فقط با داده می‌شود و مسیر فایل داخلی در کد مستند نمی‌شود.
تم فقط توکن‌ها را تغییر می‌دهد؛ ساختار و ARIA ثابت است.
Gesture ندارد.

نکات

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

آواتار — Avatar

نمونهٔ زنده

کد قابل کپی

پایه: حروف اول و تصویر

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

تصویر خراب و نام تزئینی

تابع getInitialsکپی کدکپی کد

همهٔ پیکربندی‌ها

Avatarکپی کدکپی کد

AvatarGroupکپی کدکپی کد

getInitials(name, max)کپی کدکپی کد

ساختار و اسلات‌ها

همهٔ حالت‌ها

تغییرات مجاز برای توسعه‌دهنده

تغییرات ممنوع (بنیان ثابت)

RTL، کیبورد و صفحه‌خوان

صدا، حرکت، چاپ و کاهش حرکت

توکن‌ها

قرارداد ARCH

نکات

آواتار — Avatar

نمونهٔ زنده

کد قابل کپی

پایه: حروف اول و تصویر

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

تصویر خراب و نام تزئینی

تابع getInitialsکپی کدکپی کد

همهٔ پیکربندی‌ها

Avatarکپی کدکپی کد

AvatarGroupکپی کدکپی کد

getInitials(name, max)کپی کدکپی کد

ساختار و اسلات‌ها

همهٔ حالت‌ها

تغییرات مجاز برای توسعه‌دهنده

تغییرات ممنوع (بنیان ثابت)

RTL، کیبورد و صفحه‌خوان

صدا، حرکت، چاپ و کاهش حرکت

توکن‌ها

قرارداد ARCH

نکات

تابع

تابع