★ FEATURED ARTICLE 前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载Drawer抽屉在 TDesign 组件体系中承担「一组平行关系页面/内容切换器」的职责相比 Tab 能在同屏展示更多选项数量常用于设置页、筛选面板与导航菜单场景。本文以packages/uniapp-components/drawer/README.en-US.md的 API 文档为主体结合 drawer.vue、props.ts 与 type.ts 等源码完整讲解 Drawer 组件的属性、事件、插槽与样式定制方案帮助你掌握其受控用法与底层实现原理。组件定位与引入方式Drawer 组件位于 packages/uniapp-components/drawer核心文件包括drawer.vue组件模板与逻辑实现内部基于t-popup二次封装props.ts全部属性的默认值与校验规则脚本自动生成勿手动修改type.tsTdDrawerProps、DrawerItem、DrawerTriggerSource等 TypeScript 类型定义drawer.less样式实现其中以var(--td-drawer-*)形式声明了全部可定制 CSS 变量。推荐在 uniapp 项目中通过 easycom 模式引入配置后无需手动import即可直接使用t-drawer /。如需手动引入可参照仓库中 基础示例 的写法import TDrawer from tdesign/uniapp/drawer/drawer.vue;基础使用受控的 visibleDrawer 的visible是受控属性需要手动设置为true才会开启抽屉。以 基础示例 为例通过按钮触发开启、事件回写状态t-drawer :visiblevisible :placementplacement :itemssidebar :using-custom-navbar!isMPAlipay :custom-navbar-heightgCustomNavbarHeight update:visible(e) (visible e) overlay-clickoverlayClick item-clickitemClick /其中visible支持v-model:visible语法糖数据层只需维护一个布尔变量点击蒙层、关闭后组件会通过update:visible事件把新状态同步回父组件避免出现「界面已关闭、数据仍为 true」的状态不同步问题。Drawer Props 属性详解下表完整收录自 API 文档并补充了 props.ts 中的默认值与校验逻辑| 名称 | 类型 | 默认值 | 说明 | | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式CSS | | close-on-overlay-click | Boolean | true | 点击蒙层时是否触发抽屉关闭事件 | | destroy-on-close | Boolean | false | 抽屉关闭时是否销毁节点 | | items | Array | - | 抽屉里的列表项TS 类型为DrawerItem[]| | overlay-props | Object | {} | 遮罩层属性透传至 overlayTS 类型为OverlayProps| | placement | String | right | 抽屉方向可选 left / right | | show-overlay | Boolean | true | 是否显示遮罩层 | | title | String | - | 抽屉的标题 | | using-custom-navbar | Boolean | false | 是否使用了自定义导航栏 | | visible | Boolean | false | 组件是否可见支持语法糖v-model:visible| | z-index | Number | 11500 | 抽屉层级样式默认为 11500 |对几个关键属性做源码级展开items列表项数据items接收一个DrawerItem[]数组类型定义见 type.tsexport interface DrawerItem { title: string; icon: string; }模板中通过v-for渲染每一项icon存在时会在标题前渲染一个t-icon图标见 drawer.vue 的__sidebar-item-icon分支。参考 带图标示例每个菜单项形如{ title: 菜单一, icon: app, }placement抽屉方向placement仅支持left与right两个取值props.ts中通过validator做了运行时校验validator(val: TdDrawerProps[placement]): boolean { if (!val) return true; return [left, right].includes(val); }该值在模板中会映射到底层t-popup的placement属性placement right ? right : left从而决定抽屉从屏幕左侧还是右侧滑入。close-on-overlay-click 与 show-overlay蒙层行为show-overlay为false时不渲染蒙层此时点击蒙层相关的事件overlay-click不会触发close-on-overlay-click为true时点击蒙层会关闭抽屉。两者的联动关系可以从 drawer.vue 的onVisibleChange方法看出——只有关闭动作发生时才会发出close事件。overlay-props透传遮罩属性overlay-props透传给t-overlay组件类型为OverlayProps定义见 overlay/type.ts可配置的能力包括| 属性 | 类型 | 默认值 | 说明 | | -- | -- | -- | -- | | backgroundColor | String | | 遮罩层背景色 | | duration | Number | 300 | 背景色过渡时间毫秒 | | preventScrollThrough | Boolean | true | 防止滚动穿透即不允许点击和滚动 | | zIndex | Number | 11000 | 遮罩层级 | | visible | Boolean | false | 是否展示 |destroy-on-close是否销毁节点destroy-on-close默认为false。设为true后组件根节点只在dataVisible为真时挂载模板中的v-if!destroyOnClose || dataVisible关闭抽屉即从页面销毁内部节点适合需要彻底清理内部状态或减少常驻节点数量的场景。z-index层级控制z-index默认值为11500用于控制抽屉浮层在页面中的堆叠顺序该值同时传给底层t-popup。若页面中存在其他浮层如弹窗、消息条可通过该属性调节 Drawer 的显示优先级。Drawer Events 事件详解API 文档定义的事件及其参数如下| 名称 | 参数 | 描述 | | -- | -- | -- | | close |(context: { trigger: DrawerTriggerSource })| 关闭时触发type DrawerTriggerSource overlay| | item-click |(context: { index: number; item: DrawerItem })| 点击抽屉里的列表项 | | overlay-click | - | 如果蒙层存在点击蒙层时触发 | | update-visible |(context: { visible: boolean })| 更新可见性 |事件触发链路源码分析在 drawer.vue 中Drawer 将自身事件挂到内层t-popup上构成如下调用链点击蒙层t-popup内部判断closeOnOverlayClick后发出visible-changeDrawer 的onVisibleChange收拢该事件依次执行同步dataVisible为false!visible时$emit(close, { trigger: overlay })——这就是DrawerTriggerSource目前唯一取值overlay的来源showOverlay为真时$emit(overlay-click, { visible })最后$emit(update:visible, visible)配合v-model:visible实现状态回写。点击列表项模板中每个__sidebar-item绑定clickonItemClick通过detail.currentTarget.dataset取出index与item发出item-click事件。可参考 基础示例 中itemClick(e)对事件对象的消费。注意只有当close-on-overlay-click为true时popup 的visible-change才会在点击蒙层时触发因此close事件也依赖该开关。事件与 Props 的对应关系组件内部同时支持onClose、onItemClick、onOverlayClick、onUpdateVisible四个 Function 型属性见 props.ts与事件一一对应可根据使用习惯选择事件监听或属性回调。Drawer Slots 插槽API 文档定义的插槽如下| 名称 | 描述 | | -- | -- | | 默认插槽 | 自定义抽屉的底部 | | footer | 抽屉的底部 | | title | 自定义title显示内容 |从模板结构drawer.vue看title插槽优先级高于title属性插槽存在时渲染插槽内容否则渲染{{ title }}底部区域同时放置了默认插槽与footer插槽适合放入操作按钮。参考 底部插槽示例t-drawer ... title标题 template #footer view classbutton-host t-button sizelarge block variantoutline 操作 /t-button /view /template /t-drawerCSS Variables 样式定制Drawer 组件提供了以下 CSS 变量用于自定义样式默认值中引用的是 TDesign 主题变量见 drawer.less| 名称 | 默认值 | | -- | -- | | --td-drawer-bg-color | bg-color-container | | --td-drawer-border-color | border-level-1-color | | --td-drawer-footer-padding-bottom | 40rpx | | --td-drawer-hover-color | bg-color-secondarycontainer | | --td-drawer-item-icon-color | drawer-title-color | | --td-drawer-item-icon-size | 48rpx | | --td-drawer-item-padding | 32rpx | | --td-drawer-sidebar-height | 70vh | | --td-drawer-title-color | text-color-primary | | --td-drawer-title-font | font-title-large | | --td-drawer-title-padding | 48rpx 32rpx 16rpx | | --td-drawer-width | 560rpx |样式的实现方式是「变量 兜底值」双层声明例如drawer-width: var(--td-drawer-width, 560rpx);这意味着不传变量时使用默认宽度560rpx传了变量则完全覆盖默认值。实际定制时在 Drawer 组件作用域内覆盖对应变量即可例如收窄抽屉宽度、调整标题字号或侧栏高度.t-drawer { --td-drawer-width: 480rpx; --td-drawer-sidebar-height: 60vh; --td-drawer-title-padding: 40rpx 24rpx 12rpx; }其中--td-drawer-hover-color对应列表项点击按压态的背景色模板中通过hover-classt-drawer--hover生效--td-drawer-item-icon-color的默认值直接引用了标题色变量说明图标默认与标题同色。自定义导航栏适配using-custom-navbar用于适配使用自定义导航栏的页面。Drawer 将其透传给底层 popup/overlay并通过 mixins/using-custom-navbar.js 混入计算顶部安全距离启用时调用uni.getMenuButtonBoundingClientRect()计算胶囊按钮位置结合状态栏高度得到distanceTop兜底逻辑为Math.max(distance, customNavbarHeight statusBarHeight)保证在无法获取胶囊按钮信息的平台也能正确避让。在使用示例中通常配合:using-custom-navbar!isMPAlipay与:custom-navbar-heightgCustomNavbarHeight使用按平台差异化传参。小结TDesign Drawer 组件以「受控visible 事件回写」为使用核心通过items快速构建侧边导航、以placement控制滑入方向并借助overlay-props精细化调整遮罩行为。本文完整梳理了 API 文档 中的全部 Props、Events、Slots 与 CSS 变量并结合 drawer.vue、props.ts、type.ts 与 drawer.less 揭示了事件触发链路与样式变量机制。实际开发中可对照 仓库示例目录基础、带图标、带标题、带底部插槽四种场景快速验证各 API 组合效果。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐TDesign Uniapp Chat 组件 ChatSender对话输入框 Props、Events 与 Slots 全解析TDesign Uniapp Chat 组件 ChatSender对话输入框 Props、Events 与 Slots 全解析 导读 t chat sende前端UI组件小程序设计系统移动开发TDesign Uniapp ColorPicker 颜色选择器组件全解析从 Props、Events 到 CSS 变量定制TDesign Uniapp ColorPicker 颜色选择器组件全解析从 Props、Events 到 CSS 变量定制 导读 本文以 TDesign U前端UI组件小程序设计系统移动开发Nuxt UI 4 Drawer 组件实战指南滑动抽屉的 Props、Slots 与主题定制Nuxt UI 4 Drawer 组件实战指南滑动抽屉的 Props、Slots 与主题定制 导读 UDrawer 是 Nuxt UI 4 中一个基于 vau前端UI组件设计系统上一篇asdf 版本管理完全指南安装、筛选、切换与 Shims 机制深度解析下一篇Dapp-Learning 深度拆解 Uniswap V3 合约架构与核心流程Core / Periphery 双仓库导读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
