الشيفرة المضمَّنة

نظرة عامة

link

Web

tanrei-code

schedule

SwiftUI

TanreiInlineCode

radio_button_unchecked

Jetpack Compose

TanreiInlineCode

radio_button_unchecked

Flutter

TanreiInlineCode

radio_button_unchecked

React Native

InlineCode

radio_button_unchecked

مولَّد من docs/status/status.json, specs/inline-code.spec.json

في جملة، وفي عنوان، وبالطراز plain

شغِّل npm install في المجلد الذي فيه package.json، ثم شغِّل الخادم بالأمر npm run dev -- --port 4000.

تعيين size على مجموعة

الطراز plain: comp.button.container.shape

الشيفرة المضمَّنة (inline code) تسمّي شيئًا من الشيفرة داخل جملة: أمرًا، أو خاصية، أو ملفًّا، أو قيمة. أما أسطر الشيفرة التي تُقرأ وتُنسخ فهي كتلة شيفرة. والمفاتيح التي تُضغط هي اختصار لوحة مفاتيح، وهو ينطق أسماء المفاتيح المعدِّلة.

الاستخدام

link

على الويب، الشيفرة المضمَّنة صنف (class) على عنصر code الذي تكتبه أنت، لا عنصر مستقل. والنص موجود في المستند، فيعمل البحث، والبحث في الصفحة، والنسخ، قبل أن يعمل أي سكربت. وكل عنصر code داخل .tanrei-prose ليس في عنصر pre يُرسم بالطريقة نفسها من دون الصنف، فلا يحتاج ما يُولَّد من Markdown إلى شيء.

أما SwiftUI و Compose و Flutter و React Native فمخطَّط لها: الأسماء التي بجانب كل منصة في أعلى هذه الصفحة هي ما تعطيها إياه المواصفة، ولا شيء منها متاح هناك بعد.

<link rel="stylesheet" href="@tanrei/web/tokens.css" />
<link rel="stylesheet" href="@tanrei/web/code.css" />

<!-- الطراز tonal: الافتراضي. -->
<p>شغِّل <code class="tanrei-code" translate="no" spellcheck="false">npm install</code> أولًا.</p>

<!-- الطراز plain: الخط وحده، بلون النص الذي حوله. -->
<code class="tanrei-code" data-variant="plain">comp.button.container.shape</code>

<!-- عنصر سلف يختار لكل مقطع بداخله. -->
<table data-tanrei-code="plain">
  <tr><td><code class="tanrei-code">variant</code></td><td><code class="tanrei-code">filled</code></td></tr>
</table>

import '@tanrei/web/code.css';

<p>شغِّل <code className="tanrei-code" translate="no" spellCheck={false}>npm install</code> أولًا.</p>

الخاصية	على الويب
text	محتوى العنصر نفسه
variant: tonal	data-variant="tonal"
variant: plain	data-variant="plain"
variant: auto (الافتراضي)	بلا خاصية HTML (attribute). يختار أقرب عنصر سلف له data-tanrei-code="plain" أو "tonal"، والطراز tonal حيث لا سلف يختار

المواصفات

link

تلتفّ، وكل قطعة تحتفظ بتعبئتها

الرمز tanrei.comp.navigation-drawer.item.selected.hovered.state-layer.color أطول من هذا السطر. ينكسر حيث ينتهي السطر ولا يُقصّ أبدًا.

في رابط، وفي نص مؤكَّد، وعمود من الشيفرة

راجع مرجع المكوّن Button. لا تعيِّن disabled أبدًا على المخرج الوحيد.

الخاصيةالقيمة الافتراضيةvariantfilledsizemedium

ليس للشيفرة المضمَّنة مقاس خاص بها. مقاس خطها هو مقاس النص الذي تقع فيه، مضروبًا في نسبة واحدة (comp.inline-code.label.scale) تسوّي بين خط الشيفرة وخط النص. في نص المتن يكون ذلك 13 بجانب 14. وفي العنوان هو مقاس العنوان نفسه.

لا تجعل سطرها أعلى أبدًا. ارتفاع التعبئة هو ارتفاع صندوق النص لخط الشيفرة نفسه، ولا حشو فوقها ولا تحتها.

يلتفّ المقطع مع سطره. ينكسر عند مسافاته أولًا. والجزء الذي لا مسافة فيه وهو أطول من السطر ينكسر بين الأحرف، ولا تُضاف واصلة، لأن الواصلة كانت ستغيّر الشيفرة. ولا يُقصّ أبدًا ولا يُمرَّر.

داخل الرابط تأخذ لون الرابط، ويمرّ خط الرابط السفلي تحتها. وداخل النص المؤكَّد (strong) تكون أثقل بدرجة وزن واحدة. ولا تُكتب مائلة أبدًا.

تُرتَّب دائمًا من اليسار إلى اليمين، مقطعًا مستقلًّا، وفي الجملة التي من اليمين إلى اليسار أيضًا.

البنية

الجزء	الوصف
1 container · اختياري	The fill behind the text in the tonal form: as tall as the code face's own text box, with small corners and a little room at each end of every piece of the run. Decorative; the plain form has none.
2 label	The code: its characters exactly as given, in the code face.
3 outline · اختياري	An edge around the fill, where a design system gives it a width. The default system draws none.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
text	string	""	The code: the characters exactly as they are to be read and copied ("npm install", "comp.button.container.shape"). Spaces inside it are kept.
variant	auto | tonal | plain	"auto"	How the run is set apart. tonal: the code face on a faint fill. plain: the code face alone, in the color of the text around it, for a column or a list whose every entry is code and for text on a colored container. auto, the default, takes what the nearest ancestor chooses for the inline code inside it, and tonal where none does.

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
ICD-1	THE inline code SHALL set its text in the family, the weight and the letter spacing of comp.inline-code.label.typescale, at the font size of the text it sits in multiplied by comp.inline-code.label.scale — whatever that text is: a paragraph, a heading of any level, a lead paragraph, a caption, a label, a table cell — and SHALL NOT take the font size or the line height of the code role itself.
ICD-2	THE inline code SHALL sit on the baseline of the text it is part of, as a part of that text's line, and SHALL NOT make that line taller or change the distance between lines (PRS-17); its fill, where it has one, SHALL be as tall as the code face's own text box (from its ascent to its descent at the drawn size) and SHALL NOT be padded above or below.
ICD-3	WHILE the inline code is drawn tonal (ICD-5) THE inline code SHALL draw behind its text a fill of comp.inline-code.container.color with corners comp.inline-code.container.shape eased by sys.shape.corner-smoothing, extend that fill by comp.inline-code.container.padding-inline before the first and after the last character, draw its text in comp.inline-code.label.color, and, where comp.inline-code.outline.width is above 0, draw an edge of that width in comp.inline-code.outline.color inside the fill; it SHALL draw no elevation.
ICD-4	WHILE the inline code is drawn plain (ICD-5) THE inline code SHALL draw no fill, no edge and no padding, and SHALL draw its text in the color of the text it sits in, so that it reads on any container that text reads on.
ICD-5	WHILE variant is tonal or plain THE inline code SHALL be drawn in that form; WHILE variant is auto THE inline code SHALL be drawn in the form the nearest ancestor chooses for the inline code inside it (a table whose column is code, a callout, a list of names), and tonal where no ancestor chooses one; WHEN that choice changes while the inline code is shown THE inline code SHALL follow it at once.
ICD-6	THE inline code SHALL wrap with the line it sits in: it breaks first at the spaces inside it; a part with no space that is longer than the line SHALL break between any two characters rather than run past the edge of its container; and no hyphen or any other character SHALL be drawn at a break. Each piece of a run that breaks SHALL keep the fill, the corners and both paddings of ICD-3. THE inline code SHALL NOT cut its text and SHALL NOT scroll.
ICD-7	THE inline code SHALL draw the characters of text as given: every space is kept, a run of spaces is not collapsed, a line break in text is drawn as one space, and the text is not hyphenated, not capitalised or otherwise transformed, not translated by the platform's translation, not spell-checked and not turned into a link by itself.
ICD-8	THE inline code SHALL lay out its text as a left-to-right run of its own, isolated from the text around it, in every layout direction (PRS-26): a path, a call and an operator keep their order inside a right-to-left sentence and reorder nothing beside them; the run takes its place in the sentence by the sentence's own direction.
ICD-9	THE inline code SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the inline code is shown THE inline code SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows.
ICD-10	WHERE the inline code sits inside a link THE inline code SHALL draw its text in the link's color in place of comp.inline-code.label.color and the link's underline SHALL run under it; WHERE it sits inside strong text it SHALL gain sys.typescale.emphasis.body of weight over the weight of comp.inline-code.label.typescale, as strong text does (PRS-2); WHERE it sits inside emphasised text it SHALL NOT be slanted.
ICD-11	THE inline code SHALL NOT take pointer, touch or keyboard input of its own, SHALL NOT take focus or be a stop in the focus order, and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state, draws no state layer and no focus indicator, and emits no event. WHERE it is placed inside an element that takes input (a link, a button, a list item) input over it SHALL reach that element, which draws its own states.
ICD-12	THE inline code SHALL expose its text as text, read where it sits in the sentence, with the role of code where the platform has one and no name of its own; it SHALL NOT be announced as anything else and SHALL NOT expose its form. Selecting it SHALL select its characters with the text around it, and copying that selection SHALL yield exactly text: no character stands for the padding of ICD-3.
ICD-13	THE inline code SHALL draw all of its text in one color: it takes no syntax roles and SHALL NOT highlight, parse or otherwise interpret what it holds.
ICD-14	WHERE the platform draws with a person's own forced colors THE inline code SHALL draw its text in the platform's text color (the link color inside a link) and no fill, and an edge only where comp.inline-code.outline.width is above 0, in that text color: the face tells code from words, so nothing rests on the fill.
ICD-15	WHILE the text size is enlarged THE inline code SHALL grow with the text it sits in, keeping the proportion of ICD-1, its padding and its corners; at twice the text size in a container 320 wide it SHALL wrap as ICD-6 says and SHALL NOT cause horizontal scrolling.
ICD-16	IF text is empty THE inline code SHALL draw nothing, take no space and expose nothing. WHEN variant names a value this spec does not have THE inline code SHALL be drawn as variant auto, and in debug builds report the unknown value.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-code	TanreiInlineCode	TanreiInlineCode	TanreiInlineCode	InlineCode
text · الخاصية	textContent	text	text	text	children
variant · الخاصية	data-variant	variant	variant	variant	variant
ملاحظات	A class, not an element, as prose is: <code class="tanrei-code">npm install</code> from the optional stylesheet @tanrei/web/code.css, and every code that is prose's own and not inside a pre when prose.css is loaded (the code rules of prose.css move here; PRS-16's islands apply). The text is the element's own content, so it is in the document for search engines, find-in-page and copy without script. variant is data-variant="tonal | plain" on the code; an ancestor chooses with data-tanrei-code="plain" (ICD-5), which rendered Markdown cannot set per run and a table or a callout can set once. ICD-1: font-family, font-weight and letter-spacing from the code role and font-size: calc(1em * var(--tanrei-comp-inline-code-label-scale)), so a heading's size is followed without a rule per level. ICD-2: line-height: 0 on the run, as today, and no block padding. ICD-6: overflow-wrap: anywhere, white-space: pre-wrap, hyphens: none, box-decoration-break: clone. ICD-7: translate="no" and spellcheck="false" are the author's or the renderer's attributes; the README says so. ICD-8: direction: ltr; unicode-bidi: isolate. ICD-14: forced-color-adjust is left alone; the fill is a background, which the mode removes.	TanreiInlineCode(_ text: String, variant:) is a Text that concatenates with the Text around it (Text("Run ") + TanreiInlineCode("npm install")), and AttributedString.tanreiInlineCode(variant:) styles a run of a renderer's attributed string. The ancestor's choice is an environment value. A Text run can carry a background color but neither corners nor padding: inside a sentence the tonal form is a square fill without ICD-3's padding, and the README says so; a run that stands alone is drawn whole.	AnnotatedString.Builder.tanreiInlineCode(text, variant) adds the run with its span style and an annotation, and Modifier.tanreiInlineCode() on the Text that holds it draws the fills behind the annotated ranges from the text layout (one rounded rectangle per line piece). TanreiInlineCode(text, variant) is a composable for a run that stands alone. The ancestor's choice is a composition local.	TanreiInlineCode.span(text, variant:) returns an InlineSpan for Text.rich; the fill is painted behind the run's boxes by TanreiInlineCodeText, which wraps the rich text. TanreiInlineCode(text) is a widget for a run that stands alone. The ancestor's choice is an inherited widget.	<InlineCode>npm install</InlineCode> nested in a <Text>. A nested Text takes a background color but, on iOS, neither corners nor padding: the tonal form inside a sentence is a square fill there, stated in the README. The ancestor's choice is a context. Follows the app's direction where an ancestor's is not known.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--tanrei-comp-inline-code-container-color	sys.color.surface-container-highest	#eeeeee
--tanrei-comp-inline-code-container-padding-inline	sys.space.space50	4px
--tanrei-comp-inline-code-container-shape	sys.shape.corner.extra-small	3px
--tanrei-comp-inline-code-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-inline-code-label-scale	—	0.9286
--tanrei-comp-inline-code-outline-color	sys.color.outline-variant	#000000 · 8%
--tanrei-comp-inline-code-outline-width	sys.space.space0	0px
--tanrei-comp-inline-code-label-typescale	sys.typescale.code	400 13px/1.5385

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

tonal

text: npm install

plain

text: npm install variant: plain

spaces

text: git commit -m "fix: a typo"

long

text: tanrei.comp.navigation-drawer.item.selec…

rtl

text: src/app/main.ts direction: rtl

in-paragraph

{}

in-heading

{}

in-large-text

{}

in-link-and-strong

{}

wrapping

{}

plain-in-table

variant: plain

japanese

{}

in-rtl-paragraph

direction: rtl

مولَّد من specs/inline-code.spec.json, tokens/comp/inline-code.tokens.json, design/tokens/

ما يرسمه الويب بطريقة مختلفة

link

• خاصيتا HTML translate="no" و spellcheck="false" تكتبهما أنت، أو يكتبهما محوِّل Markdown الذي تستخدمه. لا تستطيع ورقة أنماط أن تعيّنهما.
• الواصلة في الشيفرة موضع يجوز أن ينتهي عنده السطر، قبل أن يُكسر المقطع بين الأحرف.
• المحرّك WebKit يرسم التعبئة والزوايا لكل قطعة من مقطع يلتفّ، ولا يرسم الحيّز الذي عند كل طرف: القطع التي بعد الأولى تبدأ عند حافة التعبئة.
• فاصل السطر داخل المقطع يُرسم مسافة واحدة فقط في المتصفحات التي تدعم white-space-collapse: preserve-spaces. اكتب المقطع على سطر واحد.
• القيمة غير المعروفة للخاصية data-variant تُرسم كما تُرسم auto، ولا يُبلَّغ عن شيء في بنيات التنقيح.

الإرشادات

link

الطراز tonal أم plain

link

الطراز	ما يرسمه	استخدمه حين
الطراز tonal	خط الشيفرة على تعبئة خافتة	يكون اسمًا في نص جارٍ
الطراز plain	خط الشيفرة وحده، بلون النص الذي حوله	يكون عمودًا أو قائمة كل مدخل فيها شيفرة، أو نصًّا على حاوية ملوَّنة

افعل

link

• اكتب الجملة بحيث تُقرأ حين تُنطق الشيفرة كلمات. قارئات الشاشة لا تُعلن دور الشيفرة افتراضيًّا.
• استخدم الطراز plain على حاوية ملوَّنة، كحاوية حالة أو سطح معكوس. تعبئة الطراز tonal دور من أدوار السطح، ولا تُقرَن إلا بالأسطح.
• عيِّن الطراز مرة واحدة على العنصر السلف (data-tanrei-code="plain") لجدول أو قائمة من الأسماء.

لا تفعل

link

• لا تستخدم الشيفرة المضمَّنة للتوكيد. هي تقول «هذه شيفرة».
• لا تضع المفاتيح التي تُضغط في شيفرة مضمَّنة. استخدم اختصار لوحة المفاتيح.
• لا تضع فيها أكثر من سطر. استخدم كتلة الشيفرة.

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

link

الدور

code

التسمية

Inline code has no name of its own: it is text, read in its sentence. Its role is code where the platform has one (the web's code element); elsewhere it is plain text. Nothing announces its form.

الحد الأدنى للهدف

تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء

ملاحظات

• Not interactive: inline code takes no input and no focus (ICD-11), so there is no target to size; minimumTarget holds trivially. Inside a link it is part of that link's text and target.
• Told from the words around it by its face, not by color (WCAG 1.4.1): the fill is decorative, and the plain form and forced colors (ICD-14) draw none.
• Contrast in the default system: the tonal form's text is on-surface on surface-container-highest, and a link's color on that fill is held at the same ratio — both by the token invariants that hold text roles at 4.5:1 on every surface (7:1 in the high-contrast schemes). The plain form has the contrast of the text it sits in.
• The tonal form's fill is a surface role, so it is correct on a surface. On a colored container (a callout, an inverse tooltip, a filled button) the text color of ICD-3 is not paired with that container's content color: use plain there. A component that hosts text on such a container chooses plain for the inline code inside it (ICD-5).
• Screen readers do not announce the code role by default, so a sentence must make sense when the code is read as words. Symbols are read as the person's settings say; write a name out in the sentence where its spelling matters.
• It reflows (WCAG 1.4.10): a long name breaks rather than scroll the page (ICD-6, ICD-15). No hyphen is added, because a hyphen would change the code.
• Keys to press are a keyboard shortcut, which reads modifier names aloud; inline code would read the characters.

مولَّد من specs/inline-code.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

link

• هي عنصر code، فلها دور الشيفرة، ويُقرأ نصها حيث تقع في الجملة.
• تتميّز من الكلمات التي حولها بخطها، لا باللون. وفي الألوان المفروضة (forced colors) تزول التعبئة ولا يضيع شيء.
• لا تأخذ تركيزًا ولا إدخالًا. وداخل رابط أو زر، يصل الضغط فوقها إلى ذلك العنصر.
• الاسم الطويل ينكسر بدل أن يمرّر الصفحة، بأي مقاس للنص.
• تحديد جملة ونسخها ينسخ أحرف الشيفرة بالضبط.

ما عليك فعله

link

• اكتب الاسم بالكلمات في الجملة حيث تهمّ تهجئته، لأن العلامات تُقرأ كما تقول إعدادات الشخص.
• علِّم المقطع بالخاصية translate="no" لتتركه ترجمة المتصفح على حاله.