Microsoft Graph 工具包中的文件列表组件

项目
11/07/2024

文件列表组件使用文件/文件夹名称、图标和指定的其他属性显示多个文件夹和文件的列表。此组件使用 mgt-file 组件。可以指定特定的驱动器或站点，根据见解类型显示文件列表， (趋势、使用或共享) ，或者提供对自定义文件列表的查询。组件还提供了允许用户将文件上传到 One Drive 或 SharePoint 中的指定位置的选项。

示例

以下示例使用 mgt-file-list 组件显示文件。可以使用代码编辑器来查看属性如何更改组件的行为。

HTML
React

[在 mgt.dev 中打开此示例] (https://mgt.dev/?path=/story/components-mgt-file-list-html--file-list&source=docs).

属性

可以使用多个属性来自定义组件。

属性	属性	说明
file-list-query	fileListQuery	包含要呈现的文件列表的驱动器或站点的完整查询或路径。
file-queries	fileQueries	组件呈现的文件查询数组。
-	files	要获取或设置组件呈现的文件列表的文件数组。使用此属性访问组件加载的文件。设置此值以加载自己的文件。
insight-type	insightType	设置为显示用户的趋势文件、已使用文件或共享文件。
drive-id	driveId	文件夹所属驱动器的 ID。还必须提供 `item-id` 或 `item-path`。
group-id	groupId	文件夹所属组的 ID。还必须提供 `item-id` 或 `item-path`。
site-id	siteId	文件夹所属站点的 ID。还必须提供 `item-id` 或 `item-path`。如果从特定列表引用文件，请提供 `list-id` 。
user-id	userId	文件所属用户的 ID。还必须提供 `item-id` 或 `item-path`。如果从特定列表引用文件，请提供 `list-id` 。
item-id	itemId	文件夹的 ID。默认查询为 `/me/drive/items`。提供 `drive-id`、 `group-id`、 `site-id`或 `user-id` 以查询特定位置。
item-path	itemPath	相对于根) 的文件夹 (的项路径。默认查询为 `/me/drive/root`。提供 `drive-id`、 `group-id`、 `site-id`或 `user-id` 以查询特定位置。
item-view	itemView	设置要仅 (文件图标呈现的数据，即 oneLine，twoLines threeLines) 。默认值为“threeLines”
page-size	pageSize	一个数字值，指示每个页面上要呈现的最大文件数。注意：`page-sizeinsight-type`不支持。
file-extensions	fileExtensions	用于筛选要显示的文件的文件扩展名数组。
hide-more-files-button	hideMoreFilesButton	布尔值，指示是否显示用于呈现更多文件的按钮。
enable-file-upload	enableFileUpload	用于启用或禁用文件上传功能的布尔值。默认值为 `false`。
excluded-file-extensions	excludedFileExtensions	要从文件上传中排除的文件扩展名的字符串数组。还必须将 `enable-file-upload` 属性设置为 `true`。
max-file-size	maxFileSize	表示最大文件上传大小 (KB) 的数字。还必须将 `enable-file-upload` 属性设置为 `true`。
max-upload-file	maxUploadFile	一个数字，表示允许上传的最大文件数。默认值 `10` 为 files。还必须将 `enable-file-upload` 属性设置为 `true`。
disable-open-on-click	disableOpenOnClick	布尔值，用于启用或禁用单击时在单独的浏览器选项卡中打开文件的默认行为。

以下示例更改组件的行为，以便从特定查询中提取文件列表。

<mgt-file-list
  file-list-query="/me/drive/items/01BYE5RZYJ43UXGBP23BBIFPISHHMCDTOY/children"
></mgt-file-list>

以下示例通过提供文件夹 ID 更改组件的行为，以从文件夹中提取文件列表。

<mgt-file-list item-id="01BYE5RZYJ43UXGBP23BBIFPISHHMCDTOY"></mgt-file-list>

以下示例通过提供组 ID 和文件夹路径更改组件从组提取文件列表的行为。

<mgt-file-list
  group-id="8090c93e-ba7c-433e-9f39-08c7ba07c0b3"
  item-path="/Design"
></mgt-file-list>

以下示例通过提供用户 ID 和文件夹 ID 更改组件从用户提取文件列表的行为。

<mgt-file-list
  user-id="48d31887-5fad-4d73-a9f5-3c356e68a038"
  item-id="01BYE5RZYFPM65IDVARFELFLNTXR4ZKABD"
></mgt-file-list>

以下示例通过提供见解类型来更改组件获取文件列表的行为。

<mgt-file-list insight-type="shared"></mgt-file-list>

以下示例启用文件上传功能。

<mgt-file-list enable-file-upload></mgt-file-list>

以下示例将可上载的最大文件数限制为 5。

<mgt-file-list max-upload-file="5" enable-file-upload></mgt-file-list>

以下示例将可上载的最大文件大小限制为 10,000 KB。

<mgt-file-list max-file-size="10000" enable-file-upload></mgt-file-list>

以下示例排除了文件扩展名为“.doc，.pdf”的文件上传。

<mgt-file-list
  excluded-file-extensions=".doc,.pdf"
  enable-file-upload
></mgt-file-list>

CSS 自定义属性

组件 mgt-file-list 定义以下 CSS 自定义属性。

<mgt-file-list class="file-list" insight-type="shared"></mgt-file-list>

.file-list {
  /** mgt-file-upload custom styling */
  --file-upload-background-color-drag: rgb(255, 0, 0, 0.5);
  --file-upload-border-drag: 2px groove black;
  --file-upload-button-background-color: orange;
  --file-upload-button-background-color-hover: green;
  --file-upload-button-text-color: whitesmoke;
  --file-upload-dialog-background-color: azure;
  --file-upload-dialog-text-color: yellow;
  --file-upload-dialog-replace-button-background-color: white;
  --file-upload-dialog-replace-button-background-color-hover: gray;
  --file-upload-dialog-replace-button-text-color: black;
  --file-upload-dialog-keep-both-button-background-color: black;
  --file-upload-dialog-keep-both-button-background-color-hover: gray;
  --file-upload-dialog-keep-both-button-text-color: white;
  --file-upload-button-border: 2px dotted yellow;
  --file-upload-dialog-replace-button-border: 2px dotted;
  --file-upload-dialog-keep-both-button-border: 2px dashed;
  --file-upload-dialog-border: 2px solid blue;
  --file-upload-dialog-width: 300px;
  --file-upload-dialog-height: 100px;
  --file-upload-dialog-padding: 36px;

  /** mgt-file custom styling */
  --file-type-icon-height: 30px;
  --file-border: 4px dotted #ffbdc3;
  --file-border-radius: 8px;
  --file-box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.1);
  --file-background-color: #e0f8db;
  --file-background-color-focus: yellow;
  --file-background-color-hover: green;
  --file-padding: 8px;
  --file-padding-inline-start: 12px;
  --file-margin: 3px 4px;
  --file-line1-font-size: 15px;
  --file-line1-font-weight: 500;
  --file-line1-color: gray;
  --file-line1-text-transform: capitalize;
  --file-line2-font-size: 14px;
  --file-line2-font-weight: 300;
  --file-line2-color: #e50000;
  --file-line2-text-transform: lowercase;
  --file-line3-font-size: 13px;
  --file-line3-font-weight: 500;
  --file-line3-color: purple;
  --file-line3-text-transform: capitalize;

  /** mgt-file-list CSS tokens */
  --file-list-background-color: #e0f8db;
  --file-list-box-shadow: none;
  --file-list-border: 4px dotted #ffbdc3;
  --file-list-border-radius: 10px;
  --file-list-padding: 0;
  --file-list-margin: 0;
  --show-more-button-background-color: #fef8dd;
  --show-more-button-background-color--hover: #ffe7c7;
  --show-more-button-font-size: 14px;
  --show-more-button-padding: 16px;
  --show-more-button-border-bottom-right-radius: 12px;
  --show-more-button-border-bottom-left-radius: 12px;
}

若要了解详细信息，请参阅设置组件样式。

方法

方法	说明
重新加载 (clearCache = false)	调用方法以根据组件的属性重新加载具有潜在新数据的组件。传递 `true` 以在重新加载之前清除缓存。

重新加载示例

可以通过从 DOM 获取mgt-file-list引用并使用事件在按钮click中触发方法，来使用reload()公开mgt-file-list的方法。

<mgt-file-list insight-type="shared"></mgt-file-list>

<button id="reload-btn">Reload Files</button>

const fileList = document.querySelector("mgt-file-list");
document.getElementById("reload-btn").addEventListener("click", () => {
  // passing true will clear file cache before reloading
  fileList.reload(true);
});

事件

事件	何时发出	自定义数据	可取消	泡沫	使用自定义模板
`itemClick`	当用户选择文件时触发。	所选文件	否	否	是，使用自定义文件模板。

有关处理事件的详细信息，请参阅事件。

模板

组件 mgt-file-list 支持许多模板，可用于替换组件的某些部分。若要指定模板，请在组件中包含元素 <template> ， data-type 并将值设置为下表中列出的数据类型之一。

数据类型	数据上下文	说明
违约	`files`：文件对象列表	默认模板将整个组件替换为你自己的组件。
file	`file`：file 对象	用于呈现每个文件的模板。
no-data	未传递任何数据上下文	在没有可用数据时使用的模板。
装载	未传递任何数据上下文	组件加载状态时使用的模板。

模板用法示例

<mgt-file-list insight-type="shared">
  <template data-type="loading">
    <p>Getting files</p>
  </template>
  <template data-type="no-data">
    <p>No files found</p>
  </template>
  <template data-type="file">
    <p>File name{{file.name}}</p>
  </template>
</mgt-file-list>

Microsoft Graph 权限

此组件使用以下Microsoft Graph API。对于每个 API 调用，需要列出的权限之一。

配置	权限	API
默认 (未提供任何标识符或查询)	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /me/drive/root/children`
提供 `{drive-id}` AND `{item-id}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /drives/{drive-id}/items/{item-id}/children`
提供 `{group-id}` AND `{item-id}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /groups/{group-id}/drive/items/{item-id}/children`
仅提供 `{item-id}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /me/drive/items/{item-id}/children`
提供 `{site-id}` AND `{item-id}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /sites/{site-id}/drive/items/{item-id}/children`
提供 `{user-id}` AND `{item-id}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /users/{user-id}/drive/items/{item-id}/children`
提供 `{drive-id}` AND `{item-path}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /drives/{drive-id}/root:/{item-path}:/children`
提供 `{group-id}` AND `{item-path}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /groups/{group-id}/root:/{item-path}:/children`
提供 `{site-id}` AND `{item-path}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /sites/{site-id}/root:/{item-path}:/children`
提供 `{user-id}` AND `{item-path}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /users/{user-id}/root:/{item-path}:/children`
仅提供 `{item-path}`	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Group.Read.All、Group.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All	`GET /me/drive/root:/{item-path}:/children`
`insight-type` 设置为 `trending`	Sites.Read.All、Sites.ReadWrite.All	`GET /me/insights/trending`
`insight-type` 设置为 `used`	Sites.Read.All、Sites.ReadWrite.All	`GET /me/insights/used`
`insight-type` 设置为 `shared`	Sites.Read.All、Sites.ReadWrite.All	`GET /me/insights/shared`
提供 `enable-file-upload` 额外的要求	Files.ReadWrite、Files.ReadWrite.All、Sites.ReadWrite.All	`PUT /me/drive/root:/{filename}:/content` `POST /me/drive/root:/{filename}:/createUploadSession`

子组件

该 mgt-file-list 组件由一个或多个子组件组成，这些子组件可能需要除前面列出的子组件以外的权限。有关详细信息，请参阅每个子组件的文档： mgt-file。

身份验证

控件使用身份验证文档中所述的全局身份验证提供程序来提取所需的数据。

缓存

对象存储	缓存的数据	备注
`fileLists`	文件列表列表	用于存储文件列表的默认缓存列表。
`insightfileLists`	见解文件列表列表	在提供时 `insightType` 使用。

注意

提供时fileQueries，组件mgt-file-list还使用 fileQueries IndexedDB 中的mgt-file对象存储来缓存文件。

有关如何配置缓存的详细信息，请参阅缓存。

本地化

控件公开以下可本地化的变量。有关如何设置本地化的详细信息，请参阅本地化组件。

字符串名称	默认值
showMoreSubtitle	`Show more items`
filesSectionTitle	`Files`
sharedTextSubtitle	`Shared`

通过