()`)، بخصائص مُنمَّطة من البنية ([Building with Rust](https://nsh.dev/translations/ar/docs/rust.md#extending-a-rust-app-with-tsx)). أما قطعة الواجهة التي تستعملها Rust وحدها، فتكفي دالة عادية تعيد `impl IntoElement`، وتكون معاملاتها هي الخصائص. وفي TSX، يجوز أن يعيد المكوّن عنصرًا، أو سلسلة نصية أو رقمًا، أو مصفوفة، أو `null`، أو دالة تعيد أيًّا من هذه (يتتبعها المُصيِّر)؛ ويصف النوع `Component` من `nsh` واحدًا منها:
```rust
fn row(title: impl Into, content: impl IntoElement) -> impl IntoElement {
view()
.flex_row()
.gap_2()
.child(text(title.into()))
.child(content)
}
```
```tsx
import type { Component, JSX } from "nsh";
import { Text, View } from "nsh";
const Row: Component<{ title: string; children?: JSX.Element }> = (props) => (
{props.title}
{props.children}
);
```
### ما الذي يُعاد تشغيله
القيمة المعطاة لعنصر تُعيَّن مرة واحدة؛ أما الارتباط (binding) فيتتبّع ما يقرؤه. في Rust يكون الارتباط closure (أو signal أو memo أو خاصية) يوضع حيث تذهب القيمة. وفي TSX يقرّر المترجم ذلك لكل تعبير في JSX: يتغيّر التعبير عندما **يستدعي دالة أو يقرأ خاصية** (خارج الدوال المتداخلة)، وكل ما عدا ذلك يُعيَّن مرة واحدة:
```rust
text(move || format!("{}", count.get())) // follows count
text(props.title) // follows the prop
text(label.clone()) // a plain value: set once
view().opacity(move || if busy.get() { 0.5_f32 } else { 1.0 }) // follows busy
```
```tsx
{count()} // follows count
{props.title} // follows the prop
{user.name} // re-read when something it depends on changes
{label} // a plain variable: set once
// the style object is rebuilt when busy changes
```
الخاصية أو العنصر الفرعي المتغيّر هو effect أصلي صغير يعيّن تلك الخاصية وحدها أو يستبدل ذلك العنصر الفرعي وحده. وتُقارَن الأنماط (diff) في Rust، فالنمط الذي يتغيّر لا يرسل إلا الخصائص التي تغيّرت.
معالجات الأحداث تُعيَّن مرة واحدة: closure في Rust، ودالة أو اسم في TSX (`onPress={() => …}`، `onPress={save}`). وفي TSX تُتتبَّع التعبيرات الأخرى (`onPress={props.onPress}` يتتبّع الخاصية).
### الخصائص (Props)
خصائص مكوّن Rust هي حقول بنية `#[derive(Props)]`، وكل منها `Prop`: قيمة، أو ارتباط مرّره المكوّن الأب. اقرأ الخاصية داخل ارتباط (`text(props.title)`، `move || props.title.get()`) لتتبّعها؛ أما `props.title.get()` في الجسم فيقرؤها مرة واحدة. الحقول التي عليها `#[prop(default)]` أو `#[prop(default = …)]`، وكذلك `Option`، اختيارية. تبدأ الدالة المُنشِئة كل خاصية بقيمتها الافتراضية، ويستدعي الأب دوال التعيين للخصائص التي يحتاجها: `badge().label("New")`.
الخاصية في TSX التي تُعطى تعبيرًا متغيّرًا تُمرَّر على شكل getter: قراءة `props.title` تستدعيه، وهذا ما يتيح لـ JSX الذي يقرؤه أن يتتبّعه. أما الخصائص الثابتة فقيم عادية. وفي الحالتين، تُقرأ الخصائص في المكان الذي تُستخدم فيه:
```rust
// Wrong: reads the prop once, when the component runs.
#[component]
fn Title(props: TitleProps) -> impl IntoElement {
let content = props.text.get();
text(content)
}
// Right: binds the text to the prop.
#[component]
fn Title(props: TitleProps) -> impl IntoElement {
text(props.text)
}
```
```tsx
// Wrong: reads the prop once, when the component runs.
function Title(props: { text: string }) {
const { text } = props;
return {text};
}
// Right: reads it in JSX, which follows it.
function Title(props: { text: string }) {
return {props.text};
}
```
ومكوّن TSX الذي يفكّك خصائصه في المعامل، `function Title({ text }: …)`، يقرؤها بالطريقة نفسها مرة واحدة، ويحذّر البناء من ذلك مع ذكر الخصائص التي ينبغي قراءتها بدلًا منها:
```text
warn App.tsx:3:16: Title takes its props apart (`{ text }`): each is read once, when Title runs, and does not follow changes; take `props` and read `props.text` where it is used (`split(props, [...])` to pass the rest on)
```
الخاصية التي يريدها المكوّن مرة واحدة فقط، مثل معرّف (id) يبدأ به، تُقرأ في الجسم (`props.id.get_untracked()`، `const { id } = props;`)، فيكون ذلك صريحًا.
وفي TSX ينطبق الأمر نفسه على القيم الافتراضية: اكتب `props.color ?? "#ddf4ff"` في JSX بدلًا من التفكيك مع قيمة افتراضية. ولحساب شيء انطلاقًا من الخصائص، استخدم closure أو [`computed`](https://nsh.dev/translations/ar/docs/reactivity.md#computed):
```rust
#[component]
fn Price(props: PriceProps) -> impl IntoElement {
let formatted = move || format!("${:.2}", props.cents.get() as f64 / 100.0);
text(formatted)
}
```
```tsx
function Price(props: { cents: number }) {
const formatted = () => `$${(props.cents / 100).toFixed(2)}`;
return {formatted()};
}
```
### العناصر الفرعية (Children)
ما يضعه الأب داخل مكوّن يصل إليه بوصفه عناصره الفرعية: حقل `children: Prop` في Rust، يملؤه الأب بـ `.child(..)`؛ و`props.children` في TSX، وهو getter يبني تلك العناصر عند قراءته:
```rust
#[derive(Debug, Clone, PartialEq, Props)]
pub struct CardProps {
/// The title.
pub title: Prop,
/// The content.
pub children: Prop,
}
#[component]
pub fn Card(props: CardProps) -> impl IntoElement {
view()
.p(px(14.0))
.rounded(px(12.0))
.bg(move || theme().background)
.gap_2()
.child(text(props.title).font_weight(FontWeight::SEMIBOLD))
.child(props.children)
}
card()
.title("Account")
.child(text(move || format!("Signed in as {}", user.get().name)))
```
```tsx
function Card(props: { title: string; children?: JSX.Element }) {
return (
{props.title}
{props.children}
);
}
Signed in as {user().name}
```
في TSX، كل قراءة لـ `props.children` تبني العناصر الفرعية من جديد (عروض أصلية جديدة): لذا اقرأها مرة واحدة، في المكان الذي توضع فيه العناصر الفرعية. ومن بين عدة عناصر فرعية، يصل العنصر المتغيّر (`` أو `` أو `{cond() ? a : b}`) على شكل دالة، ويحدّث `{props.children}` ذلك العنصر وحده: فتحتفظ العناصر المجاورة بعروضها، ويحتفظ حقل الإدخال بنصه وتركيزه. وتجمع الأجزاء (Fragments) (`<>…`) العناصر دون عرض.
ويمكن أيضًا بناء العناصر الفرعية بدالة يستدعيها المكوّن مع معاملات، أي دالة استدعاء للتصيير (render callback):
```rust
fn repeat(times: usize, row: impl Fn(usize) -> E) -> impl IntoElement {
view().child((0..times).map(row))
}
repeat(3, |i| text(format!("Row {i}")))
```
```tsx
function Repeat(props: { times: number; children: (i: number) => JSX.Element }) {
return {Array.from({ length: props.times }, (_, i) => props.children(i))};
}
{(i) => Row {i}}
```
## التحكم في التدفق
`when` و`each` في Rust، و`` و`` في TSX، هي أدوات تحكم في التدفق مضمّنة. ولا تُصيّر أي عرض خاص بها.
```rust
when(move || user.get().is_some(), move || {
text(move || format!("Hello, {}", user.get().map(|u| u.name).unwrap_or_default()))
})
.otherwise(|| text("Signed out"))
each(todos, |todo| todo.id, |todo, index| {
text(move || format!("{}. {}", index.get() + 1, todo.get().title))
})
```
```tsx
Signed out