Materialize CHANGELOG 深度解读从 v0.9 到 v1.0.0 的组件 API 演进与破坏性变更全景【免费下载链接】materializeMaterialize, a CSS Framework based on Material Design项目地址: https://gitcode.com/gh_mirrors/ma/materialize本篇技术指南以 CHANGELOG.md 为骨架结合仓库内的 v1-changelog.md、v1-upgrade-guide.md 以及js/目录下的组件源码完整梳理 Materialize CSS 框架从 v0.9 到 v1.0.0 的演进脉络。读完本文你将掌握v1.0.0 中全部破坏性变更的来龙去脉类名重命名、插件调用方式变化、选项与回调的迁移、M.AutoInit手动初始化模型的工作原理以及 Dropdown、Sidenav、Select、Tooltip 等核心组件在源码层面的最终 API 形态与默认参数从而能够安全地把基于 v0.x 的既有项目升级到 v1.0.0。一、CHANGELOG 的总体结构与阅读方法CHANGELOG.md 采用倒序时间线记录最新版本在最前头部明确注明加粗并用 emoji 包裹的样式标记表示破坏性变更breaking change。例如:sparkles: **Rewrote Modal Plugin** :sparkles:、:no_good: **Autocomplete: renamed and moved options toautocompleteOptions** :no_good:这类条目意味着升级时可能需要改动既有代码。整个文件的版本演进可以划分为两大阶段阶段版本区间核心特征v0.x 经典阶段v0.9 ~ v0.100.1依赖 jQuery 插件体系、HTML 属性data-*自动初始化、部分组件仍在半自动状态v1.0.0 现代化阶段1.0.0-alpha.1 ~ 1.0.0全面重写为 ES6 Class 组件、M.*命名空间、统一init()静态方法、手动初始化 M.AutoInit值得注意的是CHANGELOG.md 中 1.0.02018-09-09正式版条目只给出了一个链接指向 v1-changelog.md后者才是 1.0.0 全部变更的权威明细同时 v1-upgrade-guide.md 提供了从 v0.100.2 升级到 v1.0.0 的逐组件操作清单。本文将以这两个文件为细则以js/源码为最终事实依据展开解读。二、v1.0.0 的两大革命性架构变更2.1 初始化模型从自动初始化到M.AutoInitv1.0.0 之前Materialize 在document.load时会自动扫描 DOM 并初始化所有组件。这一行为在 1.0.0 中被彻底移除改为所有组件不再自动初始化新增全局函数M.AutoInit()可一次性初始化所有组件单个组件可通过统一的静态方法M.Component.init(el, options)手动初始化。源码 js/global.js 中M.AutoInit的实现维护了一个组件注册表按 CSS 选择器扫描上下文中的元素let registry { Autocomplete: root.querySelectorAll(.autocomplete:not(.no-autoinit)), Carousel: root.querySelectorAll(.carousel:not(.no-autoinit)), Chips: root.querySelectorAll(.chips:not(.no-autoinit)), Collapsible: root.querySelectorAll(.collapsible:not(.no-autoinit)), Datepicker: root.querySelectorAll(.datepicker:not(.no-autoinit)), Dropdown: root.querySelectorAll(.dropdown-trigger:not(.no-autoinit)), Materialbox: root.querySelectorAll(.materialboxed:not(.no-autoinit)), Modal: root.querySelectorAll(.modal:not(.no-autoinit)), Parallax: root.querySelectorAll(.parallax:not(.no-autoinit)), Pushpin: root.querySelectorAll(.pushpin:not(.no-autoinit)), ScrollSpy: root.querySelectorAll(.scrollspy:not(.no-autoinit)), FormSelect: root.querySelectorAll(select:not(.no-autoinit)), Sidenav: root.querySelectorAll(.sidenav:not(.no-autoinit)), Tabs: root.querySelectorAll(.tabs:not(.no-autoinit)), TapTarget: root.querySelectorAll(.tap-target:not(.no-autoinit)), Timepicker: root.querySelectorAll(.timepicker:not(.no-autoinit)), Tooltip: root.querySelectorAll(.tooltipped:not(.no-autoinit)), FloatingActionButton: root.querySelectorAll(.fixed-action-btn:not(.no-autoinit)) };关键用法M.AutoInit()无参数时以document.body为根节点扫描全部 18 类组件M.AutoInit(context)传入 DOM 元素时只扫描该子树适合动态加载内容后的局部初始化任何元素加上.no-autoinit类即可被AutoInit跳过这是给我要手动精细控制的场景预留的逃生舱。2.2 初始化代码的统一从new M.Tooltip(el, options)到M.Tooltip.init(el, options)CHANGELOG 1.0.0-alpha.3 记录了一次影响所有组件的 API 变更new M.Tooltip(el, options)→M.Tooltip.init(el, options)其动机在 CHANGELOG 中写得很清楚同一套初始化代码可以同时用于单个元素、NodeList 以及 jQuery 元素对象。源码 js/component.js 中的Component.init静态方法正是这一能力的实现static init(classDef, els, options) { let instances null; if (els instanceof Element) { instances new classDef(els, options); } else if (!!els (els.jquery || els.cash || els instanceof NodeList)) { let instancesArr []; for (let i 0; i els.length; i) { instancesArr.push(new classDef(els[i], options)); } instances instancesArr; } return instances; }传入单个 Element返回单个实例传入NodeList / jQuery / cash 对象遍历初始化并返回实例数组构造函数内部component.js会自动检测已存在的实例并先destroy()再重建避免重复初始化。此外 js/global.js 的M.initializeJqueryWrapper(plugin, pluginName, classRef)为每个组件在 jQuery 上注册同名插件方法传入方法名则调用实例方法以get开头的方法视为 getter作用于首个元素并返回值传入对象或无参则执行初始化。由此$(.dropdown-trigger).dropdown(options)与M.Dropdown.init(el, options)完全等价。三、核心组件 API 变更逐项解读附源码默认值以下按组件逐一说明 v1.0.0 的破坏性变更并给出源码中_defaults的真实默认值方便对照升级。3.1 Dropdown类名、属性、选项全面重命名CHANGELOG1.0.0-alpha.1、alpha.4、rc.1与 v1-changelog 共同记录了 Dropdown 的最大规模变更旧写法v0.x新写法v1.0.0插件挂在.dropdown-button上插件挂在.dropdown-trigger上.dropdown-content为面板属性data-activates属性data-target选项belowOrigin选项coverTrigger选项gutter已移除改用margin相关内部定位逻辑选项stopPropagation已移除无键盘操作新增键盘支持方向键/Enter/Esc/字母过滤无回调新增onOpenStart/onOpenEnd/onCloseStart/onCloseEndHTML 属性配置选项已移除统一走初始化 options源码 js/dropdown.js 的_defaultslet _defaults { alignment: left, autoFocus: true, constrainWidth: true, container: null, coverTrigger: true, closeOnClick: true, hover: false, inDuration: 150, outDuration: 250, onOpenStart: null, onOpenEnd: null, onCloseStart: null, onCloseEnd: null, onItemClick: null };v1.0.0 的初始化方式已确认源码 dropdown.js 与 global.js 中M.getIdFromTrigger依赖data-target或hrefa classdropdown-trigger>M.Dropdown.init(document.querySelector(.dropdown-trigger), { coverTrigger: false, // 旧版 belowOrigin: false 的替代 alignment: right, autoFocus: false }); // 等价 jQuery 写法 $(.dropdown-trigger).dropdown({ coverTrigger: false });几个值得注意的源码细节coverTrigger的语义为true时下拉面板覆盖在触发器上方_getDropdownPosition中定位偏移量为 0为false时面板位于触发器正下方偏移量取触发器高度见 dropdown.jscontainer选项alpha.4 新增可将面板 DOM 移动到指定容器内_moveDropdown在初始化时即执行dropdown.js键盘支持_handleDropdownKeydown实现了方向键移动焦点、Enter 激活、Esc 关闭以及输入字母快速过滤选项filterQuery累积字母并在 1000ms 后重置见 dropdown.jsrecalculateDimensions方法在面板尺寸变化如动态加载内容后重新计算定位dropdown.js。3.2 Select插件名material_select→formSelectCHANGELOG 记录了 Select 组件的三重身份变更alpha.4插件类名改为FormSelectjQuery 插件方法改为formSelect1.0.0 正式版v1-changelogdropdownOptions选项用于定制 Select 内部使用的 Dropdown移除 option 元素上的active类1.0.0-rc.1修复重复选择同一选项时不再触发 onchange。源码 js/select.jslet _defaults { classes: , dropdownOptions: {} };用法变化// v0.x 旧写法 $(select).material_select(); // v1.0.0 新写法 $(select).formSelect(); // 或原生方式 M.FormSelect.init(document.querySelectorAll(select));dropdownOptions是 Select 内部 Dropdown 实例的透传配置。源码 select.js 显示 FormSelect 会接管onOpenEnd回调下拉打开后自动将选中项滚动到可视区域中央dropdownOptions.scrollTop计算同时保留用户传入的回调并强制closeOnClick: false防止过早关闭。因此M.FormSelect.init(document.querySelectorAll(select), { dropdownOptions: { alignment: left, autoFocus: true } });其他细节destroy()会完整清理包装 DOM移除 caret、input、dropdown 面板并把原生 select 移回原位见 select.js支持optgroup、data-icon图片选项、多选multiple自动生成复选框新增getSelectedValues()方法返回当前选中值数组。3.3 Sidenav从.side-nav/.button-collapse到.sidenav/.sidenav-triggerSidenav 的变更清单v1-changelog 与 upgrade-guide 高度一致旧写法新写法类.side-nav类.sidenav触发器类.button-collapse 插件.sideNav()触发器类.sidenav-trigger 插件.sidenav()属性data-activates属性data-target类.userView类.user-view类fixed类sidenav-fixed方法show()/hide()方法open()/close()选项menuWidth已移除改用 CSS 控制宽度选项closeOnClick已移除改为给元素加.sidenav-close类回调onOpen/onClose回调onOpenEnd/onCloseEnd并新增 onOpenStart / onCloseStart无新增preventScrolling选项源码 js/sidenav.js 的_defaultslet _defaults { edge: left, draggable: true, inDuration: 250, outDuration: 200, onOpenStart: null, onOpenEnd: null, onCloseStart: null, onCloseEnd: null, preventScrolling: true };标准 v1.0.0 用法ul idslide-out classsidenav lidiv classuser-view…/div/li lia classsidenav-close href#!菜单项点击后自动关闭/a/li /ul a href#>M.Sidenav.init(document.querySelector(#slide-out), { edge: right });源码实现要点isFixed通过检测元素是否包含sidenav-fixed类判定sidenav.jsdestroy()会移除 overlay、拖拽目标并恢复 body 滚动对应 rc.2 的修复项v1.0.0-rc.1 修复了destroy未正确清除 style 属性的问题。需要点击后关闭的菜单项只需在元素上添加.sidenav-close类无需再配置closeOnClick选项。3.4 Tooltipdelay拆分、html取代tooltipv1-changelog 记录的 Tooltip 变更移除delay选项新增enterDelay与exitDelay移除tooltip选项改用html设置提示内容新增margin、inDuration、outDuration、transitionMovement选项新增键盘支持focus/blur 触发见 tooltip.js 的 focus/blur 监听HTML 属性选项大幅精简仅保留data-tooltip与data-position。源码 js/tooltip.js 的_defaultslet _defaults { exitDelay: 200, enterDelay: 0, html: null, margin: 5, inDuration: 250, outDuration: 200, position: bottom, transitionMovement: 10 };用法M.Tooltip.init(document.querySelectorAll(.tooltipped), { html: b自定义提示内容/b, position: top, enterDelay: 100, exitDelay: 300, margin: 8 });HTML 侧仍可通过data-tooltip文案和data-positiontop配置基础属性其余能力一律在初始化 options 中设置。3.5 Modalready/complete回调移除统一为 onOpen/onClose 四段回调v1.0.0-alpha.3 移除了ready与complete回调代之以统一的onOpenStart/onOpenEnd/onCloseStart/onCloseEndv0.100.0 重写插件后要求触发器必须带modal-trigger类并修复了modal open 不再重新初始化插件与使用已初始化选项的问题。源码 js/modal.js 的_defaultslet _defaults { opacity: 0.5, inDuration: 250, outDuration: 250, onOpenStart: null, onOpenEnd: null, onCloseStart: null, onCloseEnd: null, preventScrolling: true, dismissible: true, startingTop: 4%, endingTop: 10% };用法a classmodal-trigger>M.Modal.init(document.querySelectorAll(.modal), { dismissible: true, startingTop: 8%, onOpenEnd: (el) console.log(modal opened, el), onCloseEnd: (el) console.log(modal closed, el) });升级对照旧代码的ready回调请迁移到onOpenEndcomplete回调请迁移到onCloseEnd。v1.0.0-beta 还引入了焦点锁定——焦点保持在打开的 modal 内rc.1 修复了嵌套 modal 的焦点问题rc.2 修复了 IE11 下类移除问题。CHANGELOG 还提到嵌套 modal 自 alpha.4 起得到改进支持。3.6 Chipsmaterial_chip→chips事件改回调变更要点v1-changelog upgrade-guide插件名从material_chip改为chips移除autocompleteData、autocompleteLimit选项改为嵌套在autocompleteOptions中传入移除事件触发器改用onChipAdd、onChipSelect、onChipDelete回调新增limit选项限制最大 chip 数量。M.Chips.init(document.querySelectorAll(.chips), { limit: 5, autocompleteOptions: { data: { Apple: null, Microsoft: null, Google: null }, limit: Infinity }, onChipAdd: (el, chip) console.log(added, chip), onChipDelete: (el, chip) console.log(deleted, chip), onChipSelect: (el, chip) console.log(selected, chip) });v0.98.2 还记录过把自动补全相关选项迁移到autocompleteOptions的破坏性变更1.0.0 延续了这一命名约定。3.7 ToastsM.toast参数对象化v1-changelogM.toast的入参从参数列表改为与其他插件一致的 options 对象className改名为classes新增activationPercent选项。// v0.x Materialize.toast(Hello, 4000, rounded); // v1.0.0 M.toast({ html: Hello bworld/b, classes: rounded, displayLength: 4000, activationPercent: 80 });v0.100.0 还新增了M.Toast.dismissAll()类方法一键关闭全部 toast与实例级移除方法。3.8 Tabs、Datepicker、Timepicker 与其他组件要点Tabs移除自动初始化插件方法select_tab改名为select新增duration选项指示条动画时长新增updateTabIndicator()方法修正指示条位置对应 rc.2 修复的滚动条场景下指示条错位问题v0.98.0 新增 swipeable可滑动tabsalpha.2 修复了无内容 tab 导致插件崩溃的问题。Datepicker / TimepickerDatepicker 在 v1.0.0 中完全重写v1-changelog插件调用从.pickadate()改为.datepicker()clear/close按钮文案迁移到i18n.clear/i18n.doneTimepicker 的default选项改名defaultTimefromnow改名fromNow1.0.0-beta 标注为破坏性变更移除ampmclickable选项clear/close同样迁入i18n两者均新增autoClose选项rc.1 与 alpha.2 相关修复。其余组件变更速查组件变更内容Collapsible移除自动初始化与 HTML 属性选项新增键盘支持与 onOpenStart/onOpenEnd/onCloseStart/onCloseEnd 回调destroy 时完整移除事件监听rc.2Carousel新增numVisible选项beta与onCycleTo回调修复 noWrap 选项 bugrc.2Materialbox新增 inDuration/outDuration 与 open/close 四段回调destroy 移除初始化时包装的元素rc.2修复 width/height/max-width/max-height 引发的布局问题alpha.4Autocomplete改用 Dropdown 渲染候选列表beta新增open()/close()方法与updateData方法、sortFunction选项移除点击后立即关闭的 bugrc.1Parallax新增responsiveThreshold选项低于指定屏幕宽度禁用视差与 destroy 方法修复无限循环 bugalpha.4Pushpin新增onPositionChange回调在 pinned/stuck 等状态切换时触发Scrollfire插件整体移除v1.0.0官方建议改用其他开源滚动监听方案Scrollspy新增throttle选项TapTargetFeature Discovery1.0.0-beta 一度更名为 FeatureDiscovery随后回滚为 TapTarget新增 onOpen/onClose 回调data-activates改为data-target动画引擎alpha.2 起用 anime.js 替换 velocity.js四、破坏性变更总表升级 v1.0.0 的逐项检查清单以下清单合并自 v1-upgrade-guide.md可直接作为迁移验收表使用变更对象v0.x 写法v1.0.0 写法初始化自动初始化M.AutoInit()或M.Component.init(el, options)实例化new M.Tooltip(el, options)M.Tooltip.init(el, options)Dropdown 触发器.dropdown-button.dropdown-triggerDropdown/Modal/Sidenav/TapTarget 关联属性data-activatesdata-targetDropdown 定位选项belowOrigincoverTriggerSelect 插件.material_select().formSelect()Sidenav 类名.side-nav/.userView/fixed.sidenav/.user-view/.sidenav-fixedSidenav 触发器.button-collapse/.sideNav().sidenav-trigger/.sidenav()Sidenav 方法show()/hide()open()/close()Sidenav 关闭策略closeOnClick选项元素上加.sidenav-close类文本域自适应.trigger(autoresize)M.textareaAutoResizeModal 回调ready/completeonOpenEnd/onCloseEndToast 入参参数列表M.toast(html, time, classes)options 对象className→classesTooltip 选项delay/tooltipenterDelayexitDelay/htmlTimepickerdefault/fromnowdefaultTime/fromNowDatepicker 插件.pickadate().datepicker()表单校验提示data-error/data-success直接挂在 input 上迁移到 label 之后的 Helper Text 元素Chips 自动补全autocompleteData/autocompleteLimit统一收进autocompleteOptions五、测试与构建变更如何被验证CHANGELOG v0.97.4 记录项目引入了Jasmine 测试 Travis CI。仓库 tests/spec 下每个组件都有对应的 Fixture 与 Spec例如 tests/spec/dropdown/dropdownSpec.js 对应的 Fixture 位于 tests/spec/dropdown/dropdownFixture.htmlselect 的测试位于 tests/spec/select/selectSpec.jsmodal 的测试位于 tests/spec/modal/modalSpec.js。这些测试直接验证了 v1.0.0 的新 API如M.FormSelect.init、M.Dropdown.init、open/close方法等是确认升级后行为正确的第一手参考。构建体系方面package.json 显示本项目使用 Grunt 完成 Sass 编译、Babeles2015转译、Jasmine 测试与 Uglify 压缩开发命令为npm run devgrunt monitor测试命令为npm testgrunt travis要求 Node 6。js/目录下的组件源码均为 ES6 Class 写法通过M.initializeJqueryWrapper同时暴露原生与 jQuery 两套接口如 js/select.js。六、小结CHANGELOG.md 完整呈现了 Materialize 从依赖自动初始化的 jQuery 时代走向显式初始化的原生 ES6 组件时代的整个过程。升级到 v1.0.0 时最需要记住的三条主线是① 一切初始化改为M.*.init()或M.AutoInit()② 触发器类名与data-target属性全面统一③ 回调与选项命名规范化onOpenStart/onOpenEnd 四段式、coverTrigger、enterDelay/exitDelay、defaultTime等。结合本文提供的 v1-upgrade-guide.md 检查清单与js/各组件源码中的_defaults默认值你可以逐项核对并平滑迁移既有代码。【免费下载链接】materializeMaterialize, a CSS Framework based on Material Design项目地址: https://gitcode.com/gh_mirrors/ma/materialize创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考