# الخيارات

تأخذ جميع نقاط الدخول (`codeToHtml` و`codeToTokens` و`codeToTokensResult` و`codeToHast`) مصفوفة الخيارات نفسها كوسيطها الثاني. ولا يلزم سوى `lang` ونسق ألوان.

## `lang`

**مطلوب.** معرّف اللغة أو الاسم البديل المستخدم لتقسيم النص إلى رموز — `php` و`ts` و`js` و`rust` و`python` و`html` وغيرها. تبرز القيمة الخاصة `'ansi'` تسلسلات الهروب الطرفية بدلًا من استخدام قواعد نحوية (راجع [ANSI](https://shikiphp.inline0.dev/ar/docs/ansi)).

```php
['lang' => 'php']
```

## `theme`

معرّف نسق ألوان واحد. مطلوب ما لم يُحدّد `themes`.

```php
['lang' => 'php', 'theme' => 'github-dark']
```

## `themes`

خريطة تربط المفاتيح بمعرّفات نسق الألوان لإخراج نسقين (أو أكثر) عبر متغيرات CSS. مطلوب ما لم يُحدّد `theme`.

```php
['lang' => 'ts', 'themes' => ['light' => 'github-light', 'dark' => 'github-dark']]
```

## `defaultColor`

المفتاح في `themes` الذي يصبح لونًا افتراضيًا مضمنًا (وتصبح المفاتيح الأخرى متغيرات `--shiki-<key>` CSS). القيمة الافتراضية هي `'light'`. اضبطه على `false` لإخراج المتغيرات فقط دون لون افتراضي مضمن — وهو مفيد عندما تتحكم بكل الألوان من CSS.

```php
['themes' => ['light' => '…', 'dark' => '…'], 'defaultColor' => 'dark']
```

## `transformers`

قائمة من كائنات `Shikiphp\Transformer\Transformer` تُطبّق عبر المسار. راجع [المحولات](https://shikiphp.inline0.dev/ar/docs/transformers).

```php
use Shikiphp\Transformer\Notation\NotationHighlight;

['transformers' => [new NotationHighlight()]]
```

## `decorations`

طبّق الأصناف أو السمات على نطاقات عشوائية من المصدر حسب موضع السطر والحرف. كل زخرفة هي `{start, end, properties}`، وتكون المواضع `{line, character}` (تبدأ من الصفر).

```php
['decorations' => [
    [
        'start'      => ['line' => 0, 'character' => 0],
        'end'        => ['line' => 0, 'character' => 5],
        'properties' => ['class' => 'highlight'],
    ],
]]
```

## `colorReplacements`

أعد تعيين الألوان في المخرجات. تستبدل إدخالات السلاسل لونًا في كل المواضع؛ أما الإدخالات المتداخلة المرتبطة باسم نسق ألوان فتُطبّق على ذلك النسق وحده.

```php
['colorReplacements' => [
    '#ffffff'      => '#f8f8f2',          // global
    'github-dark'  => ['#24292e' => '#000'], // only in github-dark
]]
```

## `structure`

يُخرج `'classic'` (الافتراضي) بنية `pre > code > span.line > span` كاملة. أما `'inline'` فيُخرج امتدادات الرموز فقط مع فواصل الأسطر، دون تغليف `pre`/`code` — وهو مفيد للمقاطع المضمنة.

```php
['structure' => 'inline']
```

## `tabindex`

سمة `tabindex` في عنصر `<pre>`. القيمة الافتراضية هي `0`. مرّر `false` لحذفها.

```php
['tabindex' => false]
```

## `cssVariablePrefix`

البادئة المستخدمة لمتغيرات CSS ذات النسقين. القيمة الافتراضية هي `'--shiki-'`.

```php
['cssVariablePrefix' => '--my-']
```

## `mergeWhitespaces`

تتحكم في معالجة رموز المسافات البيضاء. تقوم `true` (الافتراضية) بدمج الرموز التي تحتوي على مسافات بيضاء فقط في الرمز التالي؛ وتقسم `'never'` المسافات البيضاء في بداية كل رمز ونهايته إلى رموز مستقلة؛ بينما تترك `false` الرموز كما هي.

```php
['mergeWhitespaces' => 'never']
```

## `tokenizeMaxLineLength`

تخطَّ تقسيم النص إلى رموز (وأخرج رمزًا نصيًا عاديًا واحدًا) لأي سطر يبلغ هذا الطول أو يتجاوزه، بوحدات UTF-16. لا يوجد حد افتراضيًا. يقي ذلك من المدخلات المرضية ذات السطر الواحد.

```php
['tokenizeMaxLineLength' => 1000]
```

## `meta`

بيانات وصفية عشوائية تُمرّر إلى المحولات عبر سياق المحول — مثل سلسلة البيانات الوصفية لسياج التعليمات البرمجية التي يستهلكها [`MetaHighlight`](https://shikiphp.inline0.dev/ar/docs/transformers#metahighlight) و[`MetaWordHighlight`](https://shikiphp.inline0.dev/ar/docs/transformers#metawordhighlight).

```php
['meta' => ['__raw' => '{1,3-5}']]
```

## `grammarState`

علامة `Shikiphp\GrammarState` (من `getLastGrammarState`) لاستئناف تقسيم النص إلى رموز منها. يجب أن تتطابق `lang` وtheme(s) المحفوظتان. راجع [`getLastGrammarState`](https://shikiphp.inline0.dev/ar/docs/api#shikiphpgetlastgrammarstate).