@composy/breadcrumb-core
v0.0.2
Published
LDesign breadcrumb framework-agnostic core library
Maintainers
Readme
@composy/breadcrumb-core
LDesign 面包屑导航框架无关核心:状态管理器、路由/路径工具、事件类型、样式契约、Engine 插件与 SSR 安全的 Web Component,供各框架适配层复用。
✨ 核心能力
- 状态管理器:
BreadcrumbManager统一管理面包屑项、展开态与可见性裁剪 - 历史快照:
createSnapshot()/restoreSnapshot()与undo()/redo()撤销重做 - 折叠策略:支持
ellipsis/dropdown/none三种折叠模式与前后保留数量预算 - 路径工具:
parsePath()、resolveItemHref()、serializeQuery()等路由辅助函数 - 样式契约:统一的类名前缀、CSS 变量生成器与默认主题变量表
- Web Component:SSR 安全的
<ldesign-breadcrumb>自定义元素 - Engine 插件:
createBreadcrumbEnginePlugin()适配上层 Engine 生态
resolveItemHref() rejects javascript:, data:, and vbscript: URLs (including those with
embedded ASCII control characters). BreadcrumbManager requires finite collapse and history limits;
invalid updates leave its current config unchanged.
📦 安装
pnpm add @composy/breadcrumb-core🚀 快速开始
import { BreadcrumbManager } from '@composy/breadcrumb-core'
const manager = new BreadcrumbManager({
items: [
{ key: 'workspace', label: 'Workspace', path: '/workspace' },
{ key: 'projects', label: 'Projects', path: '/workspace/projects' },
],
separator: 'chevron',
density: 'compact',
maxItems: 4,
collapseMode: 'dropdown',
enableHistory: true,
})
manager.addItem({
key: 'atlas',
label: 'Atlas Program',
path: '/workspace/projects/atlas',
})
manager.undo()
manager.redo()📖 Manager API
BreadcrumbManager 主要方法:
getConfig()、getState()、getItems()、getItem(key)、getItemIndex(key)getVisibleItems()、count、isExpanded、versionsetItems(items)、addItem(item, index?)、removeItem(key)、updateItem(key, updates)batch(callback)、toggleExpand()、setExpanded(expanded)updateConfig(config)on(event, handler)、once(event, handler)、off(event, handler)createSnapshot()、restoreSnapshot(snapshot)undo()、redo()、canUndo、canRedo、clearHistory()destroy()、isDestroyed
事件:
clickdropdownSelectexpandChange
🧱 数据结构
import type { BreadcrumbItem } from '@composy/breadcrumb-core'
const item: BreadcrumbItem = {
key: 'projects',
label: 'Projects',
path: '/workspace/projects/:project',
params: { project: 'atlas' },
query: { tab: 'overview' },
children: [
{ key: 'active', label: 'Active projects', path: '/workspace/projects?state=active' },
{
key: 'archived',
label: 'Archived projects',
path: '/workspace/projects?state=archived',
divider: true,
},
],
}⚙️ 配置参考
type BreadcrumbSeparator = 'slash' | 'arrow' | 'dot' | 'chevron' | string
type BreadcrumbSize = 'small' | 'medium' | 'large'
type BreadcrumbDensity = 'default' | 'compact' | 'comfortable'
type BreadcrumbCollapseMode = 'ellipsis' | 'dropdown' | 'none'常用配置字段:
| 字段 | 说明 |
| -------------------------------------------------------------------- | -------------------------- |
| items | 面包屑项列表 |
| separator | 分隔符样式 |
| size / density | 尺寸与密度 |
| maxItems | 最大可见项数 |
| itemsBeforeCollapse / itemsAfterCollapse | 折叠时首尾保留数 |
| collapseMode | 折叠模式 |
| showHome / homeItem | 是否展示首页项及自定义首页 |
| lastItemClickable | 末项是否可点击 |
| ariaLabel / expandLabel / collapsedDropdownLabel / moreLabel | 无障碍与文案 |
| enableHistory / maxHistoryLength | 历史记录开关与上限 |
🔧 工具函数
import {
calculateVisibleItems,
getSeparatorChar,
normalizeItems,
parsePath,
resolveItemHref,
serializeQuery,
} from '@composy/breadcrumb-core'
const items = parsePath('/workspace/projects/atlas/releases', {
includeRoot: true,
})
const href = resolveItemHref({
path: '/workspace/projects/:project/releases',
params: { project: 'atlas' },
query: { month: 'march' },
})
const query = serializeQuery({
page: 2,
filters: ['active', 'critical'],
})🎨 样式契约
核心导出共享的类名与 token 工具:
import {
BREADCRUMB_CLASS_PREFIX,
BREADCRUMB_CSS_VAR_PREFIX,
BREADCRUMB_DEFAULT_THEME_VARIABLES,
breadcrumbClassNames,
createBreadcrumbCssText,
createBreadcrumbCssVariables,
getBreadcrumbCssVariableName,
getBreadcrumbCssVariableReference,
} from '@composy/breadcrumb-core/styles'- 公共类名使用
ldesign-breadcrumb前缀;组件变量使用--ldesign-breadcrumb-*前缀 - 默认变量把颜色映射到
packages/color生成的--ld-*token,把尺寸、间距、圆角、字体、边框与模糊值映射到packages/size生成的--ld-*token
示例:
:root {
--ldesign-breadcrumb-text-color: var(--ld-text-secondary);
--ldesign-breadcrumb-current-color: var(--ld-text-primary);
--ldesign-breadcrumb-item-height: var(--ld-px-34);
--ldesign-breadcrumb-radius: var(--ld-radius-pill);
}🧩 Web Component
import { defineLDesignBreadcrumbElement } from '@composy/breadcrumb-core/web-components'
defineLDesignBreadcrumbElement()<ldesign-breadcrumb
items='[{"key":"home","label":"Home","path":"/"},{"key":"docs","label":"Docs","path":"/docs"}]'
></ldesign-breadcrumb>实现对 HTMLElement 的访问做了守卫,在 SSR 环境导入模块也是安全的。
📤 导出入口一览
import type { BreadcrumbItem } from '@composy/breadcrumb-core/types'
import { BreadcrumbManager } from '@composy/breadcrumb-core'
import { createBreadcrumbEnginePlugin } from '@composy/breadcrumb-core/engine'
import { breadcrumbClassNames } from '@composy/breadcrumb-core/styles'
import { parsePath } from '@composy/breadcrumb-core/utils'
import { defineLDesignBreadcrumbElement } from '@composy/breadcrumb-core/web-components'🔨 构建产物与验证
构建由本包 .ldesign/builder.config.ts 中的 @composy/builder / Rolldown 配置负责;TypeScript
canonical 配置位于 .ldesign/tsconfig.json 和 .ldesign/tsconfig.cjs.json,包根 tsconfig*.json
保留兼容转发。
构建产物目录:
dist/
es/
esm/
lib/pnpm run type-check # 类型检查
pnpm run build # 四产物构建(@composy/builder)
pnpm run test # 单元测试🔗 相关链接
📄 License
MIT License © LDesign Team
