تُرجمت هذه الصفحة آليًا وقد تحتوي على أخطاء. اقرأ الأصل الإنجليزي

العناصر

Link

يأخذ الرابط المستخدم إلى مكان ما: صفحة ويب، أو تطبيقًا آخر (mailto:، tel:)، أو شاشة من التطبيق نفسه. وهو يتولى السلوك: الضغطات، ومفتاحا Return وSpace أثناء امتلاكه تركيز لوحة المفاتيح، وحالة التعطيل، ودور الرابط لقارئات الشاشة. أما المظهر فمن شأن التطبيق: فـLink لا يملك لونًا ولا خطًا سفليًا ولا تسمية خاصة به، وما يظهر هو عناصره الفرعية. href يحدد وجهة الرابط؛ فهو بيانات تُستخدم عند الفتح، وليس نصًا يظهر على الشاشة.

el-link.tsx
use nsh_base::{link, theme};
use nsh_core::prelude::*;

fn docs() -> impl IntoElement {
    link()
        .href("https://example.com/docs")
        .text_color(move || theme().primary)
        .underline()
        .hover(|s| s.opacity(0.8))
        .focus(|s| s.rounded_sm().outline(px(2.0)).outline_color(move || theme().ring))
        .child(text("Read the docs"))
}

يأتي Link من nsh/base، وهي الحزمة nsh-base في Rust. في Rust، ينشئ link() رابطًا بدالة ضبط لكل خاصية (.href(..)، .open_with(..))، ومستمعٍ لكل حدث (.on_open(..)، .on_press(..))، ودوال الأنماط المضبوطة الأنواع للرابط، و.child(..) لمحتواه.

#الفتح

الضغطة أو النقرة، أو Return أو Space على الرابط الذي يملك التركيز، تفتح href الخاص به:

  1. يُبلّغ onOpen({ href }) عن وجهة الرابط.
  2. مع openWith="system" (الافتراضي)، يُفتح عنوان URL لتطبيق آخر أو موقع آخر، أي عنوان له مخطط (https:، mailto:، tel:، أو مخطط سجّله تطبيق آخر)، خارج التطبيق، كما يفتحه openUrl: يتناوله أولًا موجّه التطبيق المضيف، ثم النظام. أما أي href آخر، كمسار من التطبيق (/orders/42) أو #anchor، فيُبلَّغ عنه ويبقى في عهدة التطبيق.
  3. يُبلّغ onPress() عن الضغطة.

مع openWith="app"، يكون معالج onOpen في التطبيق هو الذي يفتح الرابط: مسار خاص به، أو صفحة في عرض ويب داخل التطبيق، أو تأكيد أولًا.

import { Link } from "nsh/base";

<Link href={`/orders/${order.id}`} openWith="app" onOpen={({ href }) => router.push(href)} class="text-primary">
  <Text>Order #{order.id}</Text>
</Link>

يتطلب فتح عنوان URL خارج التطبيق صلاحية openUrl عندما يصرّح التطبيق بالصلاحيات في nsh.json ("openUrl": true، أو { "schemes": ["https", "mailto"] }).

#الخصائص

الخاصيةRustالنوعالافتراضيالوصف
href.href(..)stringلا شيءوجهة الرابط: عنوان URL، أو مسار من التطبيق. يُبلَّغ عنه عبر onOpen ولا يُعرض أبدًا.
openWith.open_with(LinkOpenWith::App)"system" | "app" (LinkOpenWith)"system"من يفتح href: النظام يفتح عنوان URL لتطبيق آخر أو موقع آخر؛ و"app" يترك الأمر إلى onOpen.
disabled.disabled(..)booleanfalseلا ضغطات، ولا استجابة بصرية للضغط، ولا تركيز لوحة مفاتيح؛ وتُطبَّق أنماط disabled:، وتذكر قارئات الشاشة أنه معتّم.
current.current(..)booleanfalseالرابط إلى الصفحة التي يتصفحها المستخدم، في قائمة تنقل أو مسار تنقل: تذكر قارئات الشاشة أنها الصفحة الحالية.
accessibilityLabel.accessibility_label(..)stringلا شيءما تنطق به قارئات الشاشة، عندما يقول المحتوى القليل جدًا (أيقونة).
hitSlop.hit_slop(..)number | Partial<Edges>لا شيءالمسافة خارج حدوده التي تظل الضغطات فيها محتسبة، بالنقاط: رقم واحد لكل الجهات، أو تسمية الجهات. كما في hitSlop الخاص بالعرض.
children.child(..)JSX.Elementلا شيءالمحتوى: تسمية، أو أيقونة، أو أي شيء يعرضه التطبيق.
class، styleدوال الأنماطstring، StyleProp<ViewStyle>لا شيءمظهر الرابط: لونه وخطه السفلي وحشوه؛ وتنتقل خصائص النص إلى النصوص الموجودة بداخله.
activeStyle، hoverStyle، focusStyle، disabledStyle.active(|s| ..)، .hover(..)، .focus(..)، .disabled_style(..)StyleProp<ViewStyle>لا شيءنمط الرابط أثناء الضغط عليه أو تمرير المؤشر فوقه أو تركيزه أو تعطيله، كفئات <state>:.

#الأحداث

الحدثRustالوصف
onOpen.on_open(|href: &SharedString| ..)الرابط يفتح href: مع openWith="app" يفتحه المعالج، ومع "system" يعرف المعالج ما طُلب من النظام فتحه. ويأتي قبل onPress.
onPress.on_press(|| ..)تم الضغط على الرابط: نقرة لمسية، أو نقرة بالفأرة، أو Return أو Space أثناء امتلاكه تركيز لوحة المفاتيح.

الرابط المعطّل لا يُبلّغ عن شيء، ولا تصل الضغطة عليه إلى أي عرض قابل للضغط يحيط به.

#الحالات

يضبط التطبيق نمط كل حالة بالفئات أو بخصائص النمط:

<Link
  href="https://example.com/changelog"
  class="self-start text-primary underline decoration-primary/40 transition-colors hover:decoration-primary active:opacity-70 focus:outline-2 focus:outline-ring disabled:text-muted-foreground disabled:no-underline"
>
  <Text>Changelog</Text>
</Link>

الرابط الذي سبقت زيارته يتولى التطبيق تذكّره: فهو يحتفظ بقيم href التي فتحها، ويضبط نمط تلك الروابط وفق حالته الخاصة.

const visited = signal(new Set<string>());

<Link
  href={href}
  onOpen={({ href }) => visited.set(new Set(visited()).add(href))}
  class={visited().has(href) ? "text-violet-600 underline" : "text-primary underline"}
>
  <Text>{label}</Text>
</Link>

#داخل النص

يُعدّ Link داخل <Text> صندوقًا مضمّنًا في الفقرة، شأنه شأن كل عرض داخل نص: فهو يقع ضمن السطر، ويحتفظ بحالاته وتركيزه ودوره، ويبقى على سطر واحد. ويضع align-text-bottom الرابط الذي يحتوي سطرًا واحدًا من النص على خط أساس الفقرة:

<Text class="text-[15px] text-foreground">
  By continuing you accept the{" "}
  <Link href="https://example.com/terms" class="align-text-bottom">
    <Text class="text-[15px] text-primary underline">terms of service</Text>
  </Link>
  .
</Text>

أما الرابط الذي ينتقل مع أسطر الفقرة فهو <Text> متداخل مع role="link" وonPress (راجع Text)، كما يرسم TextView روابط المستند.

#هدف صغير مع hitSlop

قد يكون الرابط أصغر من الإصبع: أيقونة، أو كلمة قصيرة. يجعل hitSlop الضغطات التي تقع قربه محتسبة، بالنقاط خلف كل جهة، دون تغيير تخطيطه ولا مظهره: رقم واحد لكل الجهات، أو تسمية الجهات ({ top: 8, bottom: 8 })، كما يقبلها hitSlop الخاص بالعرض.

<Link href="https://example.com/help" hitSlop={12} accessibilityLabel="Help" class="size-5 items-center justify-center">
  <Text>?</Text>
</Link>

#إمكانية الوصول

  • الرابط عنصر واحد لقارئات الشاشة، بالدور "link"؛ وتسميته هي نص عناصره الفرعية، أو accessibilityLabel. ويبقى href بيانات فقط: فقارئات الشاشة تنطق التسمية.
  • يُنطق current على أنه الصفحة الحالية (aria-current="page" في ARIA)، ويُنطق disabled كما تنطق المنصة العنصر المعتّم.
  • على macOS والويب يكون الرابط إحدى محطات تركيز لوحة المفاتيح: يصل إليه Tab، ويفتحه Return وSpace، وتُظهر أنماط focus: موضع التركيز.

راجع إمكانية الوصول للاطلاع على التسميات والأدوار والإعلانات بوجه عام.

#ملاحظات المنصات

  • iOS وAndroid وMac Catalyst: الضغطة هي لمسة تنتهي على الرابط.
  • أنظمة سطح المكتب (macOS وWindows وLinux وGPUI) والويب: الضغطة هي نقرة. وعلى macOS والويب، يفتح Return وSpace أيضًا الرابط الذي يملك تركيز لوحة المفاتيح.
  • يعرض الويب الرابط كعنصر له role="link".
  • ترسم كل منصة ما يضبطه التطبيق من أنماط.