迁移到更新的 SMUI 版本

本文档包含有关将代码从旧版 SMUI 迁移到新版 SMUI 的信息。您需要在现有代码中进行更改的内容将在此处写出。如果上游 MDC 版本在 SMUI 版本之间发生了变化，检查 MDC 变更日志也可能会有所帮助。

SMUI 6 -> SMUI 7

SMUI 7 从 13.0 迁移到上游 MDC 14.0：https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md#1400-2022-04-27

主题

我花了一天时间 锻炼了我所有的平面设计肌肉，并制作了一些主题！SMUI 7 现在可以使用自定义主题、默认主题或 全新的预制主题 进行样式设置。这使得 SMUI 的入门变得更加容易。

重大变更

• 工具现在 **必须** 了解 Svelte。这意味着将条件导出名称添加到 Rollup 和 Webpack 配置中。请参阅安装文档。
• SMUI 7（在 v7.0.0-beta.9 之后）不再与 Svelte 3 兼容。现在需要 Svelte 4。
• 如果您已开始使用 component={Svg}，则在 v7.0.0-beta.12 之后需要使用 tag="svg"。
• @smui/common/elements 中的组件已消失。现在只需在组件上设置 tag 属性（例如 <Button tag="div">）。
  • 在内部，它们被替换为从 @smui/common 导出的 SmuiElement 组件。它接受一个 tag 属性，并使用该标签名称动态创建一个元素。您不应该直接使用 SmuiElement。
• ”*ComponentDev” 类型（例如 MenuComponentDev）已消失。您现在可以使用组件作为其类型。可以接受 component 或 tag 属性的组件（例如 Button）具有必需的泛型参数，您可以使用它们来告诉它您正在使用哪个标签。
• 如果您使用的是 classAdderBuilder，则需要使用 keyof SmuiElementMap 而不是 string 作为其泛型参数。
• @smui/common 中的 dispatch 函数现在将在 Event 对象不可用或未提供 element 的情况下抛出错误。
• @smui/textfield 中的 Input 组件现在在输入为空时将 value 设置为 Number.NaN。

变更

组件

• 自动完成
  • SMUIAutocomplete:selected 事件现在可以取消。
• 横幅
  • 新的 autoClose 属性。
  • 新的 SMUIBanner:actionClicked 事件。当单击操作且 autoClose 为 false 时触发。
• 底部应用栏
  • 一个新组件！
• 对话框
  • 新的 sheet 属性。
  • 新的 noContentPadding 属性。
• FAB
  • 新的 focusRing 属性。使用它来支持在高对比度模式下渲染聚焦的 FAB。
• 列表
  • 新的 disabledItemsFocusable 属性。
  • 项目上的新 wrapper 属性。这应该用于仅作为嵌套列表容器的项目。
  • 新的 focusItemAtIndex 函数。
• 菜单
  • 新的 SMUIMenu:closedProgrammatically 事件。
• 菜单表面
  • 新的 SMUIMenuSurface:opening 事件。
  • 新的 openBottomBias 属性。
• 滑块
  • valueToAriaValueTextFn 现在获取一个 thumb 参数。
  • 新的 hideFocusStylesForPointerEvents 属性。来自 上游。
  • 新的 minRange 属性用于限制可选择的范围。
• 开关
  • 新的 focusRing 属性。使用它来支持在高对比度模式下渲染聚焦的开关。

SMUI 5 -> SMUI 6

SMUI 6 从 11.0 迁移到上游 MDC 13.0：https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md#1300-2021-09-24

重大变更

• 对于 @smui/common、@smui/textfield、@smui/select 和 @smui/snackbar，如果您导入类似于 @smui/snackbar/kitchen/index 或 @smui/textfield/helper-text/index 的内容，则需要从导入的末尾删除 /index。 （这不适用于 Sass 导入。）
  • 以下是一个可以在 VS Code 中用于搜索这些内容的正则表达式：@smui/(common|textfield|select|snackbar)/[\w-]+/index
• 已删除 “/styled” 导入端点。如果您使用的是高级样式方法，则需要自己从 Sass 导入 “/index” 端点。

组件

• 开关
  • 不再发出 “change” 事件，请改用 “SMUISwitch:change” 事件。

变更

• MDC 事件现在使用 “SMUI” 而不是 “MDC” 前缀进行分派。尽管它们以两种方式分派，但您的代码不会出现故障。您仍然应该更新代码以使用新的 “SMUI” 前缀。
• 不再需要任何 Vite 配置。非常感谢 Ben McCann 为 澄清我的误解并帮助我修复 package.json 文件。

组件

• 手风琴
  • 一个新组件！
• 自动完成
  • 一个新组件！特别感谢 Lorenzo Fiore，他最初编写了该组件！
• 徽章
  • 一个新组件！
• 通用
  • “internal” 导出中新增了 announce 函数。
• 纸张
  • 新增了变体！
• 开关
  • 不再需要 valueKey 属性。
  • 默认颜色现在为 “primary”。

SMUI 4 -> SMUI 5

重大变更

• TypeScript！！您不需要使用 TypeScript，但需要使用 Svelte 的 TypeScript 预处理器。
• 事件已从类似于 “SMUI:component:sub-component:event” 重命名为 “SMUIComponentSubComponent:event”。
• 元素组件（来自 @smui/common）应该从 @smui/common/elements 中以命名导入的方式导入，以便它们具有正确的类型。
• 已删除 “/bare” 导入路径。（默认导入路径自 v4 版本起未经样式化。）

SMUI 4.0 -> SMUI 4.1

• 事件修饰符已更改为使用 “$” 而不是 “:” (on:click$capture={handler})，以便所有事件（即使是 MDC 事件）都可以使用修饰符绑定。
  • 旧的 “:” 语法仍然可以使用，但它会在控制台中发出警告。

SMUI 3 -> SMUI 4

重大变更

组件不再从它们的 “index.js” 文件导入样式。如果您以前使用过 “/bare”，现在就不需要了。如果您依赖于导入的样式，那么现在需要对组件使用 “/styled” 端点。

查看新的 smui-theme 包。它可以帮助您设置主题。

SMUI 3.0 -> SMUI 3.1

SMUI 3.1 从 10.0 迁移到上游 MDC 11.0：https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md#1100-2021-04-15

您也应该将 MDC 依赖项更新到 11.0。

重大变更

主题，Sass

• MDC-Web 芯片尾随操作类已更改。
• MDC-Web 列表类已更改。

新功能

组件

• 横幅
  • 在横幅上添加焦点陷阱。
• 对话框
  • 新增 fullscreen 属性。
  • 新增 over 插槽。
• 菜单表面
  • 新增 maxHeight 属性。
  • 新增 horizontallyCenteredOnViewport 属性。
• 滑块
  • 根据 step 属性将值舍入到正确的十进制位数。
• 工具提示
  • 新增 attachScrollHandler 和 removeScrollHandler 函数，用于添加需要处理的其他可滚动元素。两者都接受函数。

SMUI 2 -> SMUI 3

您需要迁移到 Dart Sass。不再支持 node-sass，因为它已弃用，现在太旧了。

npm un -D node-sass
npm i -D sass

SMUI 3 从 4.0 迁移到上游 MDC 10.0：https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md#1000-2021-02-05

在 Sapper 中使用 SMUI 有新增的更新说明。

重大变更

主题，Sass

• MDC-Web 迁移到 “@use” 语法，因此混合、函数和变量现在由 “@use” 语句命名空间，而不是前缀。
• 主题已更改，因此您需要更新您的 “_smui-theme.scss” 文件。请遵循 本指南。

组件

• 芯片
  • 您现在需要在 set 上使用 let:chip，并将它传递给芯片，使用 {chip}。
  • 芯片现在导出 LeadingIcon、TrailingIcon 和 TrailingAction，而不是 Icon。
  • 已删除 Chip 上的 selected 属性。Chips 上的 selected 属性现在是设置选中芯片的唯一方法，它/它们应该与 chips 中的某一个/一些条目相同（按引用传递对象）。
  • 不要向任何 Chips、Texts 或 Set 提供任何 tabindex 属性。它们会管理自己的 tabindex。
  • 在 TrailingAction 上，使用 icon$class 向图标元素添加类。
• 数据表
  • Cell 上的 numeric 属性现在也应该在表头单元格上设置。
• 对话框
  • 打开状态现在由 open 属性控制，而不是 open 和 close 函数。还有 isOpen 和 setOpen 函数。
  • 列表现在应该放置在 Content 元素下方，而不是作为 Content 组件。对于从列表中进行选择，请使用对话框上的新 selection 属性。
  • 滑块对话框的样式略有不同。请参阅 演示。
• 图标按钮
  • 如果没有 toggle 属性，将不再发出 ‘MDCIconButtonToggle:change’ 事件。相反，请监听点击事件。
• 线性进度
  • 已删除 reversed 属性。
• 列表
  • radiolist 和 checklist 属性已重命名为 radioList 和 checkList。
• 菜单表面
  • 锚点操作现在接受 addClass 和 removeClass，而不是 classForward（如 Ripple）。
• 涟漪
  • Ripple 的选项 已发生很大变化。
• 选择
  • 这几乎是完全重写的。您需要迁移代码才能使用它。请查看演示页面。
  • 帮助文本不再是组件。相反，带有文本的 svelte:fragment 现在位于组件内的 “helper” 插槽中。它的 ID 和 ARIA 属性会自动设置。
  • 已删除 withLeadingIcon 和 selectedIndex 属性。
  • 您不再需要 withLeadingIcon。相反，将图标放入 “leadingIcon” 插槽中。
  • 您现在应该在 Select 上设置 required 属性，而不是 input$required。
• 滑块
  • displayMarkers 属性已重命名为 tickMarks。
  • step 现在默认为 1（与 range HTML 输入相同）。
• 选项卡
  • 已删除 active 和 focusOnActivate 属性。（不再需要，因为 TabBar 会控制它们。）
• 选项卡栏
  • 已删除 activeIndex 属性。active 属性现在是设置活动选项卡的唯一方法，它应该与 tabs 中的某一个条目相同（按引用传递对象）。
• 文本字段
  • 这几乎是完全重写的。您需要迁移代码才能使用它。请查看演示页面。
  • 帮助文本和字符计数器现在位于组件内的 “helper” 插槽中。它们的 ID 和 ARIA 属性会自动设置。
  • textarea 文本字段中的字符计数器位于 “internalCounter” 插槽中。
  • 已删除 fullwidth、dense、withLeadingIcon 和 withTrailingIcon 属性。
  • 您不再需要 withLeadingIcon 或 withTrailingIcon。相反，将图标放入 “leadingIcon” 和 “trailingIcon” 插槽中。
  • 您现在应该在 Textfield 上设置 required 属性，而不是 input$required。
  • 手动设置现在需要将子组件使用 input、floatingLabel、lineRipple 和 notchedOutline 属性传递给 Textfield。

新功能。

主题，Sass

• 纸张
  • 新增 paper-color 混合。
• 开关
  • 新增 color 属性。

组件

• 所有组件都具有一个 getElement 函数，该函数将返回它们的顶级 DOM 元素。
• 所有组件现在转发**所有**事件，并且仅在绑定时监听它们。
• 它们还可以使用 “:” 语法而不是 “|” (on:click:capture={handler}) 接受事件修饰符。

新增组件

• 横幅
• 圆形进度
• 布局网格
• 分段按钮
• 工具提示
• 触摸目标包装器

现有组件中的新功能

• 芯片
  • Set 上新增 nonInteractive 属性。
  • Chip 上新增 shouldFocusPrimaryActionOnClick 属性。
• 通用
  • Icon 现在接受 component 属性。
• 数据表
  • 新增 stickyHeader 属性。
  • Cell 上新增 columnId 属性（默认为自动 ID）。
  • Row 上新增 rowId 属性（默认为自动 ID）。
  • 分页
  • 进度指示器
  • 列排序按钮
• 对话框
  • 新增 selection 属性。
• 抽屉
  • 新增 fixed 属性（默认为 true）。
  • 新增 isOpen 函数。
• FAB
  • 新增 touch 属性。
• 表单字段
  • 新增 noWrap 属性。
• 图标按钮
  • 新增 ariaLabelOn 和 ariaLabelOff 属性，用于切换按钮。
• 菜单
  • 新增 isOpen 函数。
  • 新增 setOpen 函数。
  • 新增 setDefaultFocusState 函数。
• 菜单表面
  • 新增 fullWidth 属性。
  • 新增 anchorMargin 属性。
  • 新增 MDCMenuSurface:closing 事件。
• 选择
  • 新增 hiddenInput 属性。
  • 新增 key 属性，用于将对象用作选项。
• 滑块
  • 新增 range、start、end 属性，用于范围滑块。
  • 新增 valueToAriaValueTextFn 属性，用于更新 ARIA value 属性。
• 选项卡栏
  • 新增 tabScroller$align 属性。
• 文本字段
  • 新增 prefix 和 suffix 属性。
  • 新增 validateOnValueChange 属性。
  • 新增 input$resizable={false} 属性，用于禁用文本区域大小调整。
  • 新增 helperLine$ “$” 属性，传递给帮助线。
• 顶部应用栏
  • 新增 scrollTarget 属性。

如果您在使用这些说明进行升级时遇到问题，可以在 GitHub 上提交问题。

SMUI 1 -> SMUI 2

SMUI 2 从 3.0 迁移到上游 MDC 4.0：https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md#400-2019-11-02-1

• 芯片
  • 现在需要 Text 组件。
  • 现在使用它们自己的 Text 和 Icon 组件。通用的组件将无法使用。
  • Icon 不再需要 trailing 属性。这是默认值。
  • 不再需要 Checkmark 组件。它会自动添加。
• 菜单和菜单表面
  • 已删除 hoistMenuToBody 函数。
• 选择
  • 已删除 enchanced 属性。所有选择现在都已增强。
  • 选项上的 selected 属性不再是必需的，可能不应该使用。
  • 您现在需要将带有宽度值的类传递到 anchor$class 和 menu$class 中。
• 按钮
  • 不再具有 dense 属性。请使用 MDC 中的混合。