20260720172840

2026-07-20 17:28:47 +08:00
1 parent cda7f16d3a
commit 94207c77ff
@@ -0,0 +1,38 @@
+# _semantic
+
+## Source
+
+```vue
+<script setup lang="ts">
+import { HomeOutlined, UserOutlined } from '@antdv-next/icons'
+import { computed, h } from 'vue'
+import { SemanticPreview } from '@/components/semantic'
+import { useComponentLocale } from '@/composables/use-locale'
+import { locales } from '../locales'
+
+const { t } = useComponentLocale(locales)
+
+const semantics = computed(() => [
+  { name: 'root', desc: t('root'), version: '1.0.0' },
+  { name: 'item', desc: t('item'), version: '1.0.0' },
+  { name: 'separator', desc: t('separator'), version: '1.0.0' },
+])
+
+const items = [
+  { href: '', title: h(HomeOutlined) },
+  { href: '', title: [h(UserOutlined), h('span', 'Application List')] },
+  { title: 'Application' },
+]
+</script>
+
+<template>
+  <SemanticPreview
+    component-name="Breadcrumb"
+    :semantics="semantics"
+  >
+    <template #default="{ classes }">
+      <a-breadcrumb :items="items" :classes="classes" />
+    </template>
+  </SemanticPreview>
+</template>
+```
@@ -0,0 +1,32 @@
+# Basic Usage
+
+## Description (en-US)
+
+The simplest use.
+
+## Source
+
+```vue
+<script setup lang="ts">
+const items = [
+  {
+    title: 'Home',
+  },
+  {
+    title: 'Application Center',
+    href: '',
+  },
+  {
+    title: 'Application List',
+    href: '',
+  },
+  {
+    title: 'An Application',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb :items="items" />
+</template>
+```
@@ -0,0 +1,50 @@
+# Bread crumbs with drop down menu
+
+## Description (en-US)
+
+Breadcrumbs support drop down menu.
+
+## Source
+
+```vue
+<script setup lang="ts">
+import { h } from 'vue'
+
+const menuItems = [
+  {
+    key: '1',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.alipay.com/' }, 'General'),
+  },
+  {
+    key: '2',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.taobao.com/' }, 'Layout'),
+  },
+  {
+    key: '3',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.tmall.com/' }, 'Navigation'),
+  },
+]
+
+const items = [
+  {
+    title: 'Antdv Next',
+  },
+  {
+    title: 'Component',
+    href: '',
+  },
+  {
+    title: 'General',
+    href: '',
+    menu: { items: menuItems },
+  },
+  {
+    title: 'Button',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb :items="items" />
+</template>
+```
@@ -0,0 +1,44 @@
+# Configuring the Separator Independently
+
+## Description (en-US)
+
+Customize separator for each other.
+
+## Source
+
+```vue
+<script setup lang="ts">
+import type { BreadcrumbItemType } from 'antdv-next'
+
+const items: BreadcrumbItemType[] = [
+  {
+    title: 'Location',
+  },
+  {
+    type: 'separator',
+    separator: ':',
+  },
+  {
+    href: '',
+    title: 'Application Center',
+  },
+  {
+    type: 'separator',
+  },
+  {
+    href: '',
+    title: 'Application List',
+  },
+  {
+    type: 'separator',
+  },
+  {
+    title: 'An Application',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb separator="" :items="items" />
+</template>
+```
@@ -0,0 +1,32 @@
+# Configuring the Separator
+
+## Description (en-US)
+
+The separator can be customized by setting the separator property: `separator=">"`.
+
+## Source
+
+```vue
+<script setup lang="ts">
+const items = [
+  {
+    title: 'Home',
+  },
+  {
+    title: 'Application Center',
+    href: '',
+  },
+  {
+    title: 'Application List',
+    href: '',
+  },
+  {
+    title: 'An Application',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb separator=">" :items="items" />
+</template>
+```
@@ -0,0 +1,50 @@
+# SFC Mode
+
+## Description (en-US)
+
+Support SFC mode using `a-breadcrumb-item` and `a-breadcrumb-separator` with dropdown menu.
+
+## Source
+
+```vue
+<script setup lang="ts">
+import { h } from 'vue'
+
+const menuItems = [
+  {
+    key: '1',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.alipay.com/' }, 'General'),
+  },
+  {
+    key: '2',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.taobao.com/' }, 'Layout'),
+  },
+  {
+    key: '3',
+    label: h('a', { target: '_blank', rel: 'noopener noreferrer', href: 'http://www.tmall.com/' }, 'Navigation'),
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb separator="">
+    <a-breadcrumb-item>
+      Antdv Next
+    </a-breadcrumb-item>
+    <a-breadcrumb-separator>
+      >
+    </a-breadcrumb-separator>
+    <a-breadcrumb-item href="">
+      Component
+    </a-breadcrumb-item>
+    <a-breadcrumb-separator />
+    <a-breadcrumb-item href="" :menu="{ items: menuItems }">
+      General
+    </a-breadcrumb-item>
+    <a-breadcrumb-separator />
+    <a-breadcrumb-item>
+      Button
+    </a-breadcrumb-item>
+  </a-breadcrumb>
+</template>
+```
@@ -0,0 +1,72 @@
+# Custom semantic dom styling
+
+## Description (en-US)
+
+## Source
+
+```vue
+<script setup lang="ts">
+import type { BreadcrumbProps } from 'antdv-next'
+
+const classesObject = {
+  root: 'demo-breadcrumb-root',
+  item: 'demo-breadcrumb-item',
+  separator: 'demo-breadcrumb-separator',
+}
+
+const stylesObject: BreadcrumbProps['styles'] = {
+  root: { border: '1px solid #f0f0f0', padding: '8px', borderRadius: '4px' },
+  item: { color: '#1890ff' },
+  separator: { color: 'rgba(0, 0, 0, 0.45)' },
+}
+
+const stylesFn: BreadcrumbProps['styles'] = (info) => {
+  const items = info.props.items || []
+  if (items.length > 2) {
+    return {
+      root: { border: '1px solid #F5EFFF', padding: '8px', borderRadius: '4px' },
+      item: { color: '#8F87F1' },
+    }
+  }
+  return {}
+}
+
+const items = [
+  { title: 'Antdv Next' },
+  { title: 'Component' },
+  { title: 'Breadcrumb' },
+]
+</script>
+
+<template>
+  <a-flex vertical gap="middle">
+    <a-breadcrumb
+      :classes="classesObject"
+      :items="items.slice(0, 2)"
+      :styles="stylesObject"
+      aria-label="Breadcrumb with Object"
+    />
+    <a-breadcrumb
+      :classes="classesObject"
+      :items="items"
+      :styles="stylesFn"
+      aria-label="Breadcrumb with Function"
+    />
+  </a-flex>
+</template>
+
+<style scoped>
+.demo-breadcrumb-root {
+  padding: 8px;
+  border-radius: 4px;
+}
+
+.demo-breadcrumb-item {
+  color: #1890ff;
+}
+
+.demo-breadcrumb-separator {
+  color: rgba(0, 0, 0, 0.45);
+}
+</style>
+```
@@ -0,0 +1,40 @@
+# With an Icon
+
+## Description (en-US)
+
+The icon should be placed in front of the text.
+
+## Source
+
+```vue
+<script lang="ts" setup>
+import type { BreadcrumbItemType } from 'antdv-next'
+import { HomeOutlined, UserOutlined } from '@antdv-next/icons'
+
+const items: BreadcrumbItemType[] = [
+  {
+    href: '',
+  },
+  {
+    href: '',
+  },
+  {
+    title: 'Application',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb :items="items">
+    <template #titleRender="{ index }">
+      <template v-if="index === 0">
+        <HomeOutlined />
+      </template>
+      <template v-if="index === 1">
+        <UserOutlined />
+        <span>Application List</span>
+      </template>
+    </template>
+  </a-breadcrumb>
+</template>
+```
@@ -0,0 +1,27 @@
+# With Params
+
+## Description (en-US)
+
+With route params.
+
+## Source
+
+```vue
+<script setup lang="ts">
+import type { BreadcrumbItemType } from 'antdv-next'
+
+const items: BreadcrumbItemType[] = [
+  {
+    title: 'Users',
+  },
+  {
+    title: ':id',
+    href: '',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb :items="items" :params="{ id: 1 }" />
+</template>
+```
@@ -0,0 +1,119 @@
+---
+title: Breadcrumb
+description: Display the current location within a hierarchy. And allow going back to states higher up in the hierarchy.
+---
+
+## When To Use 
+- When the system has more than two layers in a hierarchy.
+- When you need to inform the user of where they are.
+- When the user may need to navigate back to a higher level.
+
+## Demos
+
+| Demo | Path |
+| --- | --- |
+| Basic Usage | demo/basic.md |
+| With an Icon | demo/withIcon.md |
+| With Params | demo/withParams.md |
+| Configuring the Separator | demo/separator.md |
+| Bread crumbs with drop down menu | demo/overlay.md |
+| Configuring the Separator Independently | demo/separator-component.md |
+| SFC Mode | demo/sfc.md |
+| Custom semantic dom styling | demo/style-class.md |
+
+## API
+
+Common props ref：[Common props](../../docs/vue/common-props.md)
+
+### Props
+
+| Property | Description | Type | Default | Version | [Global Config](../config-provider/docs.md#component-config) |
+| --- | --- | --- | --- | --- | --- |
+| dropdownIcon | Custom dropdown icon | VueNode | `<DownOutlined />` | - | ✓ |
+| itemRender | Custom item renderer, work with vue-router | (route, params, routes, paths) =&gt; VueNode | - | - | × |
+| params | Routing parameters | object | - | - | × |
+| items | The routing stack information of router | [ItemType\[\]](#itemtype) | - | - | × |
+| separator | Custom separator | VueNode | `/` | - | ✓ |
+
+### Events
+
+| Event | Description | Type | Version |
+| --- | --- | --- | --- |
+| clickItem | Triggered when clicking a breadcrumb item | (item: ItemType, event: MouseEvent) =&gt; void | - |
+
+### Slots
+
+| Slot | Description | Type | Version |
+| --- | --- | --- | --- |
+| itemRender | Custom item renderer, work with vue-router | (route: ItemType, params: AnyObject, routes: ItemType[], paths: string[]) =&gt; any | - |
+| titleRender | Custom title renderer | (params: \{ item: ItemType, index: number \}) =&gt; any | - |
+| separator | Custom separator | () =&gt; any | - |
+| menuLabelRender | Custom menu label renderer | (params: \{ item: ItemType, index: number, menu: MenuItem \}) =&gt; any | - |
+| menuExtraRender | Custom menu extra content renderer | (params: \{ item: ItemType, index: number, menu: MenuItem \}) =&gt; any | - |
+
+## Types 
+### ItemType 
+> type ItemType = Omit&lt;RouteItemType, 'title' | 'path'&gt; | SeparatorType
+
+### RouteItemType 
+| Property | Description | Type | Default | Version |
+| --- | --- | --- | --- | --- |
+| dropdownProps | The dropdown props | [Dropdown](../dropdown/docs.md) | - | - |
+| href | Target of hyperlink. Can not work with path | string | - | - |
+| path | Connected path. Each path will connect with prev one. Can not work with href | string | - | - |
+| menu | The menu props | [MenuProps](../menu/docs.md#api) | - | - |
+| onClick | Set the handler to handle click event | (e: MouseEvent) =&gt; void | - | - |
+| title | item name | VueNode | - | - |
+
+### SeparatorType 
+```ts
+const item = {
+  type: 'separator', // Must have
+  separator: '/',
+}
+```
+
+| Property | Description | Type | Default | Version |
+| --- | --- | --- | --- | --- |
+| type | Mark as separator | `separator` | - | - |
+| separator | Custom separator | VueNode | `/` | - |
+
+## Use with vue-router 
+The link of Breadcrumb item targets `#` by default, you can use `itemRender` slot to make a vue-router Link.
+
+```vue
+<script setup lang="ts">
+import type { BreadcrumbProps } from 'antdv-next'
+import { RouterLink } from 'vue-router'
+
+const items: BreadcrumbProps['items'] = [
+  {
+    path: '/index',
+    title: 'home',
+  },
+  {
+    path: '/first',
+    title: 'first',
+  },
+  {
+    path: '/second',
+    title: 'second',
+  },
+]
+</script>
+
+<template>
+  <a-breadcrumb :items="items">
+    <template #itemRender="{ route, paths }">
+      <RouterLink v-if="paths.length > 0" :to="`/${paths.join('/')}`">
+        {{ route.title }}
+      </RouterLink>
+      <span v-else>{{ route.title }}</span>
+    </template>
+  </a-breadcrumb>
+</template>
+```
+
+## Semantic DOM
+
+| _semantic | demo/_semantic.md |
@@ -0,0 +1,32 @@
+# breadcrumb Token
+
+Use these variables through `theme.components.Breadcrumb`. This document lists definitions only and does not include values.
+
+```vue
+<a-config-provider
+  :theme="{
+    token: {
+      // Global token configuration
+    },
+    components: {
+      Breadcrumb: {
+        // Token name: value
+      },
+    },
+  }"
+>
+  ...
+</a-config-provider>
+```
+
+## Token List
+
+| Token | Type | Description |
+| --- | --- | --- |
+| `itemColor` | `string` | Text color of Breadcrumb item |
+| `iconFontSize` | `number` | Icon size |
+| `linkColor` | `string` | Text color of link |
+| `linkHoverColor` | `string` | Color of hovered link |
+| `lastItemColor` | `string` | Text color of the last item |
+| `separatorMargin` | `number` | Margin of separator |
+| `separatorColor` | `string` | Color of separator |