在 SharePoint 框架解决方案中使用 CSS 的建议

2023-04-08

构建 SharePoint 框架解决方案时，可使用 CSS 定义自定义项应有的外观和行为。本文介绍了如何最大限度地利用 SharePoint 框架提供的功能，并以可靠的方式构建你的 CSS 样式。

SharePoint 框架自定义项是页面的一部分

使用外接程序模型构建 SharePoint 自定义项时，解决方案与页面上的其他元素彼此独立。可在 iframe 中将代码作为外接程序部件或作为控制整个页面的沉浸式应用程序执行。在这两种情况下，你的代码不会受到在页面上定义的其他元素或样式的影响。

SharePoint 框架解决方案是页面的一部分，并与页面的 DOM 完全集成。在此操作移除外接程序模型附带的大量限制时，它会将你的解决方案暴露在风险中。因为它是页面的一部分，除非显式隔离，否则页面上的所有 CSS 样式都适用于它，这可能会导致体验与预期的有所不同。若要避免此类风险，应采用此方法定义 CSS 样式，以使它们不会影响除自定义项以外的其他页面内容。

组织解决方案中的 CSS 文件

解决方案的 UI 通常包括多个构建基块。在许多 JavaScript 库中，这些构建基块被称为组件。一个组件可以很简单，仅定义演示文稿，也可以更复杂，包括状态和其他组件。将解决方案拆分为多个组件可以简化开发过程，轻松测试和重复使用解决方案中的组件。

由于组件具有演示文稿，它们通常需要 CSS 样式。在理想状态下，组件应隔离并且能单独使用。考虑到这一点，存储特定组件的 CSS 样式以及组件旁的所有其他资产文件就很有意义。以下是具有大量组件且每个组件都有自己的 CSS 文件的 React 应用程序的示例结构。

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

使用 Sass

在 SharePoint 框架中，可以使用 CSS 和 Sass。 Sass 是 CSS 的超集，它可向你提供变量、嵌套选择器或 mixin 等大量功能，从长期来看，所有功能都可简化 CSS 样式的使用和管理。

有关完整的功能集，请参阅 Sass 网站。所有有效 CSS 也是有效的 Sass，如果此前尚未使用过 Sass 并且想要逐步了解其功能，这会十分有用。

避免在标记中使用 ID

使用 SharePoint 框架，构建最终用户添加到 SharePoint 的自定义项。如果仅在页面上使用过一次特定自定义项或如果有多个自定义项实例，则无法提前告知。

若要避免发生问题，应始终假定同一页面上有多个自定义项实例。考虑到这一点，应避免在标记中使用任何 ID。 ID 在页面上必定是唯一的，如果用户将 Web 部件添加到页面两次，则其会违反此前提，可能会发生错误。

坏的做法

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

好的做法

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles.helloWorld}">
        Hello world
      </div>`;
  }

  // ...
}

使用 CSS 模块以避免样式冲突

SharePoint 框架解决方案是页面的一部分。若要确保一个组件的 CSS 样式不会影响页面上的其他元素，应以仅应用于解决方案的 DOM 的方式定义 CSS 选择器。手动执行此操作非常繁琐且容易出错，但SharePoint 框架可以自动执行此操作。

为了帮助避免样式冲突，SharePoint 框架使用 CSS 模块。构建项目时，SharePoint 框架工具链会处理所有具有 .module.scss 扩展名的文件。对于每个文件，它会读取所有类选择器并将唯一哈希值追加到它们身上。完成后，它会将已更新选择器写入包括在生成的 Web 部件捆绑包之中的中间 CSS 文件。

接着上面的示例，假定有以下两个 Sass 文件：

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

生成项目后，在 lib 文件夹中，将看到生成的以下两个 CSS 文件（添加了换行符和缩进以提高可读性）：

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

尽管在这两个 Sass 文件夹中均定义了 .text 类，但请注意，在生成的 CSS 文件中存在着两个追加到它的不同的哈希值，使其变为特定于每个组件的唯一类名。

CSS 模块中的 CSS 类名称是动态生成的，因此无法在代码中直接引用它们。相反，在处理 CSS 模块时，SharePoint 框架工具链会生成一个 JavaScript 文件，其中包含对生成的类名的引用。

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

若要在代码中使用生成的类名，首先导入组件样式，然后使用指向该特定类的属性：

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

为使 CSS 模块正常工作，需满足以下条件：

Sass 文件必须具有 .module.scss 扩展名。如果使用不含 .module 的 .scss 扩展名，你会在生成过程中收到警告。 Sass 文件被转换为中间 CSS 文件，但类名不会设为唯一。在需要替代第三方 CSS 样式的情况下，这样做是有原因的。
CSS 类名必须是有效的 JavaScript 变量名称。例如，它们不能包含连字符：todoList 正确，todo-list 不正确。
我们建议（但不强制）为类使用 camelCase 命名。

将 CSS 样式包装在以组件命名的类中

通过将 CSS 模块与 Sass 对嵌套规则集的支持进行组合，可以简化 CSS 样式并确保其不会影响页面上的其他元素。

构建组件的 CSS 样式时，将其包装在以组件命名的类中。在组件中，将类分配到组件的根元素。

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

在转换后，生成的 CSS 文件类似于：

.todoList_3e9d35f0 a {
  display: block;
}

因为选择器从特定于组件的唯一类名开始，所以另一演示文稿仅适用于组件内的超链接。

CSS 供应商前缀处理

在 SharePoint 框架中，项目的 Sass 或 CSS 文件中不一定必须有供应商前缀样式属性。如果一些支持 SharePoint 框架的浏览器要求必须有前缀，也是在将 Sass 编译为 CSS 后自动添加前缀。这种方法亦称为“自动添加前缀”，也是 SharePoint 框架中 CSS 生成链的基本组成部分。

在 Web 部件应使用 display: flex 声明定义的新弹性方框模型的情况下，一些较旧的基于 WebKit 和 Internet Explorer 版本需要在 CSS 中定义的特定供应商前缀。

.container{
  display: flex;
}

在 SharePoint 框架项目的 Sass 代码中，无需添加供应商前缀。将 Sass 编译为 CSS 后，会自动添加前缀，生成下面的 CSS 声明。

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

删除已应用的前缀不仅可以简化项目的代码，还可以增加代码的易读性，以供今后使用。此过程还配置为仅支持 SharePoint 框架支持的浏览器，这样可以减少错误。

如果 Web 部件已在 Sass 文件中添加了不再需要的供应商前缀，将会执行相同的过程来自动删除这些声明。

以下示例使用 border-radius 属性，此属性不需要受支持系统上的供应商前缀。

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

将包中生成的 CSS 转换为以下代码。

.container_9e54c0b0 {
  border-radius: 7px
}

有关自动添加前缀的详细信息，请参阅自动前缀程序 GitHub 存储库。是否可以使用__？中提供了此过程的数据库。

集成 Office UI Fabric

通过使自定义项外观和行为类似于 SharePoint 和 Office 365 的标准功能，可以使最终用户更轻松地使用它们。 Office UI Fabric 为你提供一组控件和样式，可使自定义项与现有用户体验无缝集成。

有关在 SharePoint 框架中使用 Office UI Fabric 的详细信息，请参阅在 SharePoint 框架中使用 Office UI Fabric Core 和 Fabric React。

使用主题颜色

SharePoint 允许用户为其网站选择主题颜色。在 SharePoint 框架自定义项中，你应当使用用户选择的主题，以便自定义项看起来像是网站的一部分，而不会出现不必要的突出效果。

因为用户在其网站上设置主题，你无法提前告知自定义项应使用的颜色，但 SharePoint 框架可自动为你动态加载当前处于活动状态的配色方案。

有关此功能的详细信息，请参阅在 SharePoint 框架自定义项中使用主题颜色。

通过

在 SharePoint 框架解决方案中使用 CSS 的建议

SharePoint 框架自定义项是页面的一部分

组织解决方案中的 CSS 文件

使用 Sass

避免在标记中使用 ID

坏的做法

好的做法

使用 CSS 模块以避免样式冲突

todoList.module.scss

todoItem.module.scss

todoList.module.css

todoItem.module.css

todoList.module.scss.js

将 CSS 样式包装在以组件命名的类中

todoList.module.scss

TodoList.tsx

CSS 供应商前缀处理

集成 Office UI Fabric

使用主题颜色

其他资源