اختيار متسلسل Cascader

يُستخدم منتقي الاختيار المتسلسل في سيناريوهات البيانات متعددة المستويات، مثل اختيار المقاطعة والمدينة والمنطقة.

الاستخدام الأساسي

vue

<script setup>
import { ref } from 'vue'

const value1 = ref([])
const options1 = [
  {
    value: 'zhinan',
    label: 'دليل',
    children: [
      {
        value: 'sheji',
        label: 'دليل التصميم',
        children: [
          { value: 'yuansze', label: 'الألوان' },
          { value: 'fuziyuanze', label: 'الخطوط' },
        ],
      },
      {
        value: 'shejiguize',
        label: 'قواعد التصميم',
      },
    ],
  },
  {
    value: 'zujian',
    label: 'المكوّنات',
    children: [
      { value: 'jiben', label: 'أساسية' },
      { value: 'fankui', label: 'تغذية راجعة' },
    ],
  },
]
</script>

<template>
  <!-- الاستخدام الأساسي -->
  <lh-cascader v-model="value1" :options="options1" />
</template>

vue

<script>
export default {
  data() {
    return {
      value1: [],
      options1: [
        {
          value: 'zhinan',
          label: 'دليل',
          children: [
            {
              value: 'sheji',
              label: 'دليل التصميم',
              children: [
                { value: 'yuansze', label: 'الألوان' },
                { value: 'fuziyuanze', label: 'الخطوط' },
              ],
            },
            {
              value: 'shejiguize',
              label: 'قواعد التصميم',
            },
          ],
        },
        {
          value: 'zujian',
          label: 'المكوّنات',
          children: [
            { value: 'jiben', label: 'أساسية' },
            { value: 'fankui', label: 'تغذية راجعة' },
          ],
        },
      ],
    }
  },
}
</script>

<template>
  <!-- الاستخدام الأساسي -->
  <lh-cascader v-model="value1" :options="options1" />
</template>

وضع الاختيار المتعدد

عند ضبطه كوضع اختيار متعدد، يمكن اختيار أكثر من نتيجة.

vue

<script setup>
import { ref } from 'vue'

const value2 = ref([])
const options2 = [
  {
    value: 'zhinan',
    label: 'دليل',
    children: [
      { value: 'sheji', label: 'دليل التصميم' },
      { value: 'shejiguize', label: 'قواعد التصميم' },
    ],
  },
  {
    value: 'zujian',
    label: 'المكوّنات',
    children: [
      { value: 'jiben', label: 'مكوّنات أساسية' },
      { value: 'fankui', label: 'مكوّنات التغذية الراجعة' },
    ],
  },
]
</script>

<template>
  <!-- وضع الاختيار المتعدد -->
  <lh-cascader v-model="value2" :options="options2" multiple />
</template>

vue

<script>
export default {
  data() {
    return {
      value2: [],
      options2: [
        {
          value: 'zhinan',
          label: 'دليل',
          children: [
            { value: 'sheji', label: 'دليل التصميم' },
            { value: 'shejiguize', label: 'قواعد التصميم' },
          ],
        },
        {
          value: 'zujian',
          label: 'المكوّنات',
          children: [
            { value: 'jiben', label: 'مكوّنات أساسية' },
            { value: 'fankui', label: 'مكوّنات التغذية الراجعة' },
          ],
        },
      ],
    }
  },
}
</script>

<template>
  <!-- وضع الاختيار المتعدد -->
  <lh-cascader v-model="value2" :options="options2" multiple />
</template>

تعطيل الخيارات

تعطيل العقدة عبر خاصية disabled.

vue

<script setup>
import { ref } from 'vue'

const value3 = ref([])
const options3 = [
  {
    value: 'zhinan',
    label: 'دليل',
    disabled: true,
    children: [
      { value: 'sheji', label: 'دليل التصميم' },
    ],
  },
  {
    value: 'zujian',
    label: 'المكوّنات',
    children: [
      { value: 'jiben', label: 'مكوّنات أساسية' },
      { value: 'fankui', label: 'مكوّنات التغذية الراجعة', disabled: true },
    ],
  },
]
</script>

<template>
  <!-- تعطيل الخيارات -->
  <lh-cascader v-model="value3" :options="options3" />
</template>

vue

<script>
export default {
  data() {
    return {
      value3: [],
      options3: [
        {
          value: 'zhinan',
          label: 'دليل',
          disabled: true,
          children: [
            { value: 'sheji', label: 'دليل التصميم' },
          ],
        },
        {
          value: 'zujian',
          label: 'المكوّنات',
          children: [
            { value: 'jiben', label: 'مكوّنات أساسية' },
            { value: 'fankui', label: 'مكوّنات التغذية الراجعة', disabled: true },
          ],
        },
      ],
    }
  },
}
</script>

<template>
  <!-- تعطيل الخيارات -->
  <lh-cascader v-model="value3" :options="options3" />
</template>

الحجم والتعطيل والقراءة فقط

يضبط size الحجم، ويعطّل disabled المنتقي بأكمله، ويجعل readonly العرض للقراءة فقط، ويخصّص placeholder العنصر النائب، ويزيل clearable زر المسح.

vue

<script setup lang="ts">
import { ref } from 'vue'

const demoCascSize = ref([])
const demoCascSize2 = ref([])
const demoCascDisabled = ref([])
const demoCascReadonly = ref([])
const demoCascPlaceholder = ref([])
const demoCascNoClear = ref([])
const options = [
  {
    value: 'zhinan',
    label: 'دليل',
    children: [
      { value: 'sheji', label: 'دليل التصميم' },
      { value: 'shejiguize', label: 'قواعد التصميم' },
    ],
  },
  {
    value: 'zujian',
    label: 'المكوّنات',
    children: [
      { value: 'jiben', label: 'مكوّنات أساسية' },
      { value: 'fankui', label: 'مكوّنات التغذية الراجعة' },
    ],
  },
]
</script>

<template>
  <!-- small -->
  <lh-cascader v-model="demoCascSize" :options="options" size="small" placeholder="small" />
  <!-- large -->
  <lh-cascader v-model="demoCascSize2" :options="options" size="large" placeholder="large" />
  <!-- حالة التعطيل -->
  <lh-cascader v-model="demoCascDisabled" :options="options" disabled placeholder="حالة التعطيل" />
  <!-- حالة القراءة فقط -->
  <lh-cascader v-model="demoCascReadonly" :options="options" readonly placeholder="حالة القراءة فقط" />
  <!-- عنصر نائب مخصص -->
  <lh-cascader v-model="demoCascPlaceholder" :options="options" placeholder="عنصر نائب مخصص" />
  <!-- غير قابل للمسح -->
  <lh-cascader v-model="demoCascNoClear" :options="options" :clearable="false" placeholder="غير قابل للمسح" />
</template>

vue

<script>
export default {
  data() {
    return {
      demoCascSize: [],
      demoCascSize2: [],
      demoCascDisabled: [],
      demoCascReadonly: [],
      demoCascPlaceholder: [],
      demoCascNoClear: [],
      options: [
        {
          value: 'zhinan',
          label: 'دليل',
          children: [
            { value: 'sheji', label: 'دليل التصميم' },
            { value: 'shejiguize', label: 'قواعد التصميم' },
          ],
        },
        {
          value: 'zujian',
          label: 'المكوّنات',
          children: [
            { value: 'jiben', label: 'مكوّنات أساسية' },
            { value: 'fankui', label: 'مكوّنات التغذية الراجعة' },
          ],
        },
      ],
    }
  },
}
</script>

<template>
  <!-- small -->
  <lh-cascader v-model="demoCascSize" :options="options" size="small" placeholder="small" />
  <!-- large -->
  <lh-cascader v-model="demoCascSize2" :options="options" size="large" placeholder="large" />
  <!-- حالة التعطيل -->
  <lh-cascader v-model="demoCascDisabled" :options="options" disabled placeholder="حالة التعطيل" />
  <!-- حالة القراءة فقط -->
  <lh-cascader v-model="demoCascReadonly" :options="options" readonly placeholder="حالة القراءة فقط" />
  <!-- عنصر نائب مخصص -->
  <lh-cascader v-model="demoCascPlaceholder" :options="options" placeholder="عنصر نائب مخصص" />
  <!-- غير قابل للمسح -->
  <lh-cascader v-model="demoCascNoClear" :options="options" :clearable="false" placeholder="غير قابل للمسح" />
</template>

عرض المسار والبحث

يتحكم show-all-levels فيما إذا كان حقل الإدخال يعرض المسار الكامل (افتراضيًا true، وعند إيقافه يُعرض اسم المستوى الأخير فقط)؛
يخصّص separator فاصل المسار، ويسري أيضًا على لوحة نتائج البحث؛
عند ضبط emit-path على false يربط v-model قيمة المستوى الأخير فقط، مع إبقاء حقل الإدخال يعرض المسار الكامل؛
يسمح check-strictly بتحديد عقدة من أي مستوى (النقر على أي مستوى يحدده مباشرة، ويعتمد تصفّح المستويات الفرعية على المرور بالفأرة)؛
يفعّل filterable البحث، فتُعرض المطابقات بالمسار الكامل بعد إدخال كلمة مفتاحية؛
يطوي collapse-tags الوسوم في وضع الاختيار المتعدد؛
يوقف cascading الربط بين تحديد العقدة الأب والعقد الابنة؛
يخصّص item-config الأسماء البديلة لحقول العقدة (مثل بناء الشجرة عبر id / name)، ويسري ذلك على عرض المسار أيضًا.

جميع الأمثلة التالية تضمّن قيمًا محددة سلفًا، بحيث يمكن مقارنة الفروقات دون الحاجة إلى الاختيار مستوىً مستوى: يعرض المسار الكامل «مقاطعة تشيجيانغ / مدينة هانغتشو / حي شيهو»، وعند إيقاف show-all-levels يظهر «حي شيهو» فقط، ومع separator=" > " يظهر «مقاطعة تشيجيانغ > مدينة هانغتشو > حي شيهو».

مقاطعة تشيجيانغ/مدينة هانغتشو/حي شيهو

مقاطعة تشيجيانغ/مدينة هانغتشو/حي بينجيانغ

vue

<script setup lang="ts">
import { ref } from 'vue'

const demoCascFullPath = ref(['zhejiang', 'hangzhou', 'xihu'])
const demoCascAllLevels = ref(['zhejiang', 'hangzhou', 'xihu'])
const demoCascSep = ref(['zhejiang', 'hangzhou', 'xihu'])
const demoCascEmit = ref(['xihu'])
const demoCascStrict = ref(['zhejiang', 'hangzhou'])
const demoCascFilter = ref([])
const demoCascCollapse = ref(['xihu', 'haishu'])
const demoCascLoose = ref(['xihu', 'binjiang'])
const demoCascItem = ref(['zhejiang', 'hangzhou', 'xihu'])

const pathOptions = [
  {
    value: 'zhejiang',
    label: 'مقاطعة تشيجيانغ',
    children: [
      {
        value: 'hangzhou',
        label: 'مدينة هانغتشو',
        children: [
          { value: 'xihu', label: 'حي شيهو' },
          { value: 'binjiang', label: 'حي بينجيانغ' },
        ],
      },
      {
        value: 'ningbo',
        label: 'مدينة نينغبو',
        children: [{ value: 'haishu', label: 'حي هايشو' }],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'مقاطعة جيانغسو',
    children: [
      {
        value: 'nanjing',
        label: 'مدينة نانجينغ',
        children: [{ value: 'xuanwu', label: 'حي شوانوو' }],
      },
    ],
  },
]

const aliasedOptions = [
  {
    id: 'zhejiang',
    name: 'مقاطعة تشيجيانغ',
    sub: [
      {
        id: 'hangzhou',
        name: 'مدينة هانغتشو',
        sub: [
          { id: 'xihu', name: 'حي شيهو' },
          { id: 'binjiang', name: 'حي بينجيانغ' },
        ],
      },
      {
        id: 'ningbo',
        name: 'مدينة نينغبو',
        sub: [{ id: 'haishu', name: 'حي هايشو' }],
      },
    ],
  },
]
</script>

<template>
  <!-- المسار الكامل (افتراضي) -->
  <lh-cascader v-model="demoCascFullPath" :options="pathOptions" placeholder="المسار الكامل (افتراضي)" />
  <!-- عرض المستوى الأخير فقط -->
  <lh-cascader v-model="demoCascAllLevels" :options="pathOptions" :show-all-levels="false" placeholder="عرض المستوى الأخير فقط" />
  <!-- فاصل > -->
  <lh-cascader v-model="demoCascSep" :options="pathOptions" separator=" > " placeholder="فاصل >" />
  <!-- إعادة قيمة المستوى الأخير فقط -->
  <lh-cascader v-model="demoCascEmit" :options="pathOptions" :emit-path="false" placeholder="إعادة قيمة المستوى الأخير فقط" />
  <!-- اختيار أي مستوى -->
  <lh-cascader v-model="demoCascStrict" :options="pathOptions" check-strictly placeholder="اختيار أي مستوى" />
  <!-- قابل للبحث -->
  <lh-cascader v-model="demoCascFilter" :options="pathOptions" filterable placeholder="قابل للبحث" />
  <!-- طي الوسوم في الاختيار المتعدد -->
  <lh-cascader v-model="demoCascCollapse" :options="pathOptions" multiple collapse-tags placeholder="طي الوسوم في الاختيار المتعدد" />
  <!-- عدم ربط الأب بالابن -->
  <lh-cascader v-model="demoCascLoose" :options="pathOptions" multiple :cascading="false" placeholder="عدم ربط الأب بالابن" />
  <!-- أسماء الحقول البديلة -->
  <lh-cascader v-model="demoCascItem" :options="aliasedOptions" :item-config="{ value: 'id', label: 'name', children: 'sub' }" placeholder="أسماء الحقول البديلة" />
</template>

vue

<script>
export default {
  data() {
    return {
      demoCascFullPath: ['zhejiang', 'hangzhou', 'xihu'],
      demoCascAllLevels: ['zhejiang', 'hangzhou', 'xihu'],
      demoCascSep: ['zhejiang', 'hangzhou', 'xihu'],
      demoCascEmit: ['xihu'],
      demoCascStrict: ['zhejiang', 'hangzhou'],
      demoCascFilter: [],
      demoCascCollapse: ['xihu', 'haishu'],
      demoCascLoose: ['xihu', 'binjiang'],
      demoCascItem: ['zhejiang', 'hangzhou', 'xihu'],
      pathOptions: [
        {
          value: 'zhejiang',
          label: 'مقاطعة تشيجيانغ',
          children: [
            {
              value: 'hangzhou',
              label: 'مدينة هانغتشو',
              children: [
                { value: 'xihu', label: 'حي شيهو' },
                { value: 'binjiang', label: 'حي بينجيانغ' },
              ],
            },
            {
              value: 'ningbo',
              label: 'مدينة نينغبو',
              children: [{ value: 'haishu', label: 'حي هايشو' }],
            },
          ],
        },
        {
          value: 'jiangsu',
          label: 'مقاطعة جيانغسو',
          children: [
            {
              value: 'nanjing',
              label: 'مدينة نانجينغ',
              children: [{ value: 'xuanwu', label: 'حي شوانوو' }],
            },
          ],
        },
      ],
      aliasedOptions: [
        {
          id: 'zhejiang',
          name: 'مقاطعة تشيجيانغ',
          sub: [
            {
              id: 'hangzhou',
              name: 'مدينة هانغتشو',
              sub: [
                { id: 'xihu', name: 'حي شيهو' },
                { id: 'binjiang', name: 'حي بينجيانغ' },
              ],
            },
            {
              id: 'ningbo',
              name: 'مدينة نينغبو',
              sub: [{ id: 'haishu', name: 'حي هايشو' }],
            },
          ],
        },
      ],
    }
  },
}
</script>

<template>
  <!-- المسار الكامل (افتراضي) -->
  <lh-cascader v-model="demoCascFullPath" :options="pathOptions" placeholder="المسار الكامل (افتراضي)" />
  <!-- عرض المستوى الأخير فقط -->
  <lh-cascader v-model="demoCascAllLevels" :options="pathOptions" :show-all-levels="false" placeholder="عرض المستوى الأخير فقط" />
  <!-- فاصل > -->
  <lh-cascader v-model="demoCascSep" :options="pathOptions" separator=" > " placeholder="فاصل >" />
  <!-- إعادة قيمة المستوى الأخير فقط -->
  <lh-cascader v-model="demoCascEmit" :options="pathOptions" :emit-path="false" placeholder="إعادة قيمة المستوى الأخير فقط" />
  <!-- اختيار أي مستوى -->
  <lh-cascader v-model="demoCascStrict" :options="pathOptions" check-strictly placeholder="اختيار أي مستوى" />
  <!-- قابل للبحث -->
  <lh-cascader v-model="demoCascFilter" :options="pathOptions" filterable placeholder="قابل للبحث" />
  <!-- طي الوسوم في الاختيار المتعدد -->
  <lh-cascader v-model="demoCascCollapse" :options="pathOptions" multiple collapse-tags placeholder="طي الوسوم في الاختيار المتعدد" />
  <!-- عدم ربط الأب بالابن -->
  <lh-cascader v-model="demoCascLoose" :options="pathOptions" multiple :cascading="false" placeholder="عدم ربط الأب بالابن" />
  <!-- أسماء الحقول البديلة -->
  <lh-cascader v-model="demoCascItem" :options="aliasedOptions" :item-config="{ value: 'id', label: 'name', children: 'sub' }" placeholder="أسماء الحقول البديلة" />
</template>

الخصائص

الخاصية	الوصف	النوع	الافتراضي
modelValue	القيمة المرتبطة	`(string \| number)[]`	`() => []`
options	قائمة الخيارات	`[LhCascaderNode](#type-LhCascaderNode)`[]	`() => []`
size	الحجم	`"small" \| "medium" \| "large" \| "mini" \| "x-large"`	`'medium'`
disabled	ما إذا كان معطّلًا	`boolean`	`false`
clearable	ما إذا كان قابلًا للمسح	`boolean`	`true`
placeholder	العنصر النائب (عند عدم تمريره تُؤخذ القيمة من حزمة اللغة `cascader.placeholder`، بالعربية «يرجى الاختيار»)	`string`	`''`
readonly	ما كان للقراءة فقط	`boolean`	`false`
showAllLevels	ما إذا كان حقل الإدخال يعرض المسار الكامل	`boolean`	`true`
checkStrictly	إمكانية تحديد عقدة من أي مستوى	`boolean`	`false`
emitPath	ما إذا كانت القيمة المُعادة تتضمن المسار الكامل	`boolean`	`true`
multiple	ما إذا كان اختيارًا متعددًا	`boolean`	`false`
cascading	ما إذا كان التحديد متسلسلًا بين المستويات	`boolean`	`true`
separator	الفاصل	`string`	`'/'`
collapseTags	ما إذا كانت الوسوم تُطوى في وضع الاختيار المتعدد	`boolean`	`false`
filterable	ما إذا كان قابلًا للبحث	`boolean`	`false`
itemConfig	الأسماء البديلة لحقول العقدة	`[LhCascaderItemConfig](#type-LhCascaderItemConfig)`	`() => ({})`
sx	خصائص التخطيط السريع (مثل `{ mt: 2, w: '50%' }`)، تُحوّل إلى أنماط سطرية تُطبَّق على العنصر الجذري للمُشغِّل (لا تتأثر لوحة القائمة المنبثقة)	`LhSxProps`	—

الأحداث

الحدث	الوصف	معاملات الاستدعاء
change	يُطلق عند تغيّر القيمة المختارة	`(value: (string \| number)[], path: LhCascaderNode[] \| null)`
update:model-value	يُطلق عند تغيّر القيمة المرتبطة	`value: (string \| number)[]`

بنية البيانات

تعريف النوع LhCascaderNode:

interface LhCascaderNode {
  value: string | number
  label: string
  disabled?: boolean
  leaf?: boolean
  children?: LhCascaderNode[]
}

تعريفات الأنواع

بنى TypeScript التي يصدّرها هذا المكوّن خارجيًا (مستخرَجة تلقائيًا من packages/components/cascader/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لعرض التعريف كاملًا؛ وصف الخصائص في جدول الخصائص أعلاه):

LhCascaderProps

export interface LhCascaderProps {
  modelValue?: (string | number)[]
  options?: LhCascaderNode[]
  size?: LhComponentSize
  disabled?: boolean
  clearable?: boolean
  placeholder?: string
  readonly?: boolean
  showAllLevels?: boolean
  checkStrictly?: boolean
  emitPath?: boolean
  multiple?: boolean
  cascading?: boolean
  separator?: string
  collapseTags?: boolean
  filterable?: boolean
  itemConfig?: LhCascaderItemConfig
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

LhCascaderItemConfig _{(مأخوذ من @lh-ui/share/core/cascader)}

/**
 * تعيين خصائص العنصر ضمن خصائص Cascader
 */
export interface LhCascaderItemConfig {
  value?: string
  label?: string
  children?: string
  disabled?: string
  leaf?: string
}

LhCascaderNode _{(مأخوذ من @lh-ui/share/core/cascader)}

/**
 * عقدة Cascader
 */
export interface LhCascaderNode {
  value: string | number
  label: string
  disabled?: boolean
  leaf?: boolean
  children?: LhCascaderNode[]
}

LhComponentSize _{(مأخوذ من @lh-ui/share/core/shared)}

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]

الفتحات

الفتحة	الوصف	المحتوى الافتراضي
no-match	المحتوى المخصص للوحة البحث عند عدم وجود نتائج مطابقة	حزمة اللغة `cascader.noMatch` (بالعربية «لا توجد بيانات مطابقة»)

اختيار متسلسل Cascader ​

الاستخدام الأساسي ​

وضع الاختيار المتعدد ​

تعطيل الخيارات ​

الحجم والتعطيل والقراءة فقط ​

عرض المسار والبحث ​

الخصائص ​

الأحداث ​

بنية البيانات ​

تعريفات الأنواع ​

الفتحات ​