MultiDatePick 用户指南

1. 三个组件：各自的适用场景

MultiDatePick 提供三个基于同一底层的 Lightning Web Components。选择与您的数据相符的那一个。

功能对比

功能逐级叠加。Date 的所有功能 Date Time 和 Booking 都有。Date Time 增加了时间，Booking 增加了资源和容量。

2. 记录结构：各自的适用场景

记录结构决定所选内容如何变成记录。它由三个相互独立的选择组成，任意组合都可行。

设置向导定义了六种结构：每个日期一条记录、每个日期范围一条记录、每个时间段一条记录、父记录加子块、单个资源和多个资源。

实例：回答这 3 个问题

每个场景回答三个问题，就能确定结构。设置向导问的也是这三个问题。

组合表：所有组合一览

按您对时间和资源的需求选择行。列取决于是否设置了 End Date Field API Name。每个单元格都是有效的设置。

总结：三个选择的任意组合都可行。如果您的场景不属于上面列出的模式，分别设置每个选择，其余交给组件即可。

3. 设置向导详解

设置向导只需保存一次配置。在任意页面或 Flow 屏幕的 Config Name（配置名称）中输入它的名称，该位置就会使用这个配置。修改配置后，所有使用它的位置都会随之更新。

1. 1 名称与类型
2. 2 对象与字段
3. 3 时间字段
4. 4 状态与显示
5. 5 审阅与保存

选择起点

新建选项卡提供两种方式。引导我完成设置会问三个问题，然后选好组件和结构。配置所有属性会打开所有设置。旁边还有两个选项卡：现有配置用于编辑已保存的配置，导入用于粘贴来自 Config Library 的配置。

步骤 1：名称与类型

选择组件（Date、Date Time 或 Booking）并为配置命名。这个名称就是之后在 Config Name 中输入的内容。此步骤还设置视图：默认视图、切换器提供哪些视图，以及时间轴和日程的选项。

步骤 2：对象与字段

最关键的一步。选择存放记录的对象、它的日期字段，以及指回父记录的关系字段。可选字段用于添加日期范围、资源、容量、子块和屏蔽日期。Booking 配置也在这里设置资源对象、容量字段和营业时间。

步骤 3：时间字段

仅限 Date Time 和 Booking。映射开始和结束时间字段，然后设置时间间隔（任意间隔均可，常用 15、30 或 60 分钟）、最早和最晚时间、显示模式，以及发生冲突时的处理方式。

步骤 4：状态与显示

状态字段和颜色、要隐藏的状态、用户可选的状态、悬停字段、编辑模式、记录命名、按钮标签、日历大小，以及 Max Dates Allowed（最大选择数） 等限制。

步骤 5：审阅与保存

检查摘要，试用实时预览，然后单击保存配置。向导会在 30 到 60 秒内为您部署配置。完成后可添加一段可选描述。

现有配置与导入

已保存的配置列在现有选项卡中：单击某个配置即可编辑或导出。导入选项卡接受任意 Config Library 卡片中的 JSON，或从其他组织导出的配置。

4. 权限集与访问权限

软件包附带四个权限集。在“设置”的“权限集”中分配。

组件以每个用户自己的权限运行，因此用户还需要拥有对您的对象和字段的访问权限：

• 对象：对保存记录的对象拥有“读取”和“创建”权限，并对日历读取的任何资源、闭馆或子对象拥有“读取”权限。
• 字段，读取：日历显示的每个字段（日期、状态、悬停字段）。
• 字段，编辑：组件写入的每个字段（日期、时间、状态、第二个选项列表、名称字段、父级查找字段）。只要有一个字段用户无法编辑，保存就会失败，即使读取正常。
• 被引用的记录：对新记录所指向的父记录和资源至少拥有“读取”权限。

每条错误消息及其原因见故障排除：访问错误。访客站点需要额外几个步骤：参阅公共访客页面。

5. 点击保存与 Flow 管理保存

保存方式有两种。根据放置位置选择合适的一种。

点击保存：四项设置

设置向导会自动填写这些设置。四项都有值时，“保存”按钮就会出现。

页面使用哪条父记录，以及何时改为在 Flow 中选择，请参阅应用程序页面、主页和 Experience 页面。

Flow 管理保存：输出

将四项设置留空。“保存”按钮会隐藏，所选内容通过以下 Flow 输出传出：

将 JSON 传给 Parse Date Entries from JSON。它返回一个可以循环遍历的列表，每一项都包含开始日期、结束日期、开始时间、结束时间和资源 Id。分步说明见Flow 示例。

保存只会新增

点击保存只会创建新记录。取消选择日期绝不会删除已保存的记录，因此误点不会丢失数据。要修改或删除记录，请使用编辑模式或相关列表。

6. 状态颜色与编辑模式

状态颜色与筛选

按对象上的任意选项列表为记录着色，隐藏部分值，并限制终端用户可选的值。

编辑模式

开启启用编辑模式后，会出现编辑按钮。在编辑模式下，用户可以：

• 以卡片形式查看现有记录及其日期和状态
• 单击日期，将其记录加入编辑集合
• 修改日期、时间、资源或状态，记录随即更新
• 删除需两次点击确认，不会误删

7. 视图：一个组件，五种布局

每个组件都能呈现五种布局。它们通过相同的字段映射读取同一批记录，遵循相同的冲突规则、屏蔽日期和营业时间，保存方式也相同。切换视图只改变记录的外观，不改变记录的含义。

五种视图及其各自回答的问题

设置

每个页面使用不同的视图

视图是每个放置位置上的设置，因此同一批记录在不同位置可以呈现不同外观。只需安装一次，一套字段映射。

编辑模式在所有视图中都可用

开启启用编辑模式后，所有视图都会显示“编辑”按钮。在时间轴、周或日程视图中单击一条记录即可将其加入编辑集合，就像在月历上单击日期一样。在时间轴中批量更改状态，效果与在日历中完全相同。

时间轴：折叠行

当某个资源有重叠的预订时，它的行会折叠成一条，并显示同时 N 个标签。单击展开箭头，每个预订各占一道。折叠的行仍支持拖动、悬停和单击。

时间轴：拖动改期

开启启用编辑模式后，时间轴上的横条可以拖动。拖住中间可将预订移到其他日期；拖住边缘可更改开始或结束。横条会显示将落在何处，松开即保存。在“日”缩放级别下，同样的操作会更改时间。

不只排会议室，也能排人

Resource Object API Name（资源对象 API 名称）可以是任何对象。将其设为 User，时间轴就变成排班表，周视图变成班次网格，使用率变成团队容量仪表板。

• User 没有标准的容量字段。添加一个自定义字段（例如 Daily Capacity），即可以百分比查看使用率。
• 将 Business Hours Start Field（营业时间开始字段）和 Business Hours End Field（营业时间结束字段）映射到 User 字段，周网格就会按每个人自己的工作时间显示。

Config Library 中有两个现成示例：团队容量规划 和 员工排班表。

8. 资源预订与容量（Booking 组件）

单个资源

用户从下拉列表中选择一个资源，时间网格随即加载该资源的预订和容量。

多个资源

开启允许选择多个资源，下拉列表就会变成复选框。网格只显示所有勾选资源都空闲的时间段，单击“保存”即可一次性全部预订。

容量

允许多个预订共享同一时间段，并实时显示 3/5 这样的标记。时间段订满后不再接受预订。

冲突

冲突行为决定所选时间段已被占用时如何处理。Conflict Look-Ahead Days 设置向前检查多少天（默认 360 天）。

闭馆设置始终优先。即使设为 Allow，也无法在被屏蔽的时间段上保存。

9. 限制用户可选的内容

按日期数或时间段数，限制每个人最多能选多少。

10. 屏蔽日期、时间和资源（闭馆设置）

任何日历都可以从另一个对象读取闭馆记录，并将其覆盖的日期、时间段或资源置灰，这样用户只能在您营业时预订。将几项设置指向闭馆对象，其余交给组件即可。整天屏蔽适用于全部三个组件；按时间和按资源屏蔽需要 Date Time 或 Booking 的时间网格。

屏蔽与隐藏有什么区别？

两者听起来相似，作用却恰恰相反。屏蔽是减少可用性：时间段仍然显示，但无法预订。隐藏是把记录移出视图，从而释放其占用的时间段。

屏蔽日期设置

三个屏蔽级别

1. 整天：不带时间的闭馆记录会将整个日期置灰。适用于全部三个组件。已关闭的日期即使已有预订，也保持关闭。
2. 部分时段：带开始和结束时间的闭馆记录只屏蔽这些时间段，当天其余时间仍可预订。选中日期后即可看到被屏蔽的时间段。
3. 单个资源：指向某个资源的闭馆记录只关闭该资源。在单资源视图中，该时间段带删除线；在合并视图中，它会显示一个小角标，并且在其他空闲资源上仍可预订。

使用时间网格？那就用部分时段屏蔽。整天屏蔽更适合只选日期的选择器。

闭馆对象的两种模式

• 同一对象，用状态标记：将屏蔽日期对象指向您的预订对象并筛选 Status = Cancelled，已取消的预订就兼作闭馆记录。这种方式最简单，但该对象上的所有日历都会共用这些记录。请参阅 Config Library 中的 避开节假日的预约排期 配置。
• 专用的闭馆对象：一个 Office Closure 对象，包含日期、可选的开始和结束时间、Region 字段以及可选的资源查找字段。每个日历按自己的区域筛选，闭馆记录也可以只针对某一个资源。请参阅 按小时关闭资源 配置。

如果想让员工自行屏蔽时间（比如负责人屏蔽某个上午），在内部页面或站点上放置一个保存到闭馆对象的 Date Time 组件即可。

被屏蔽时间段的表现

• 外观：完全关闭的时间段带删除线并置灰。只对部分所选资源关闭的时间段会显示角标。
• 选择：完全关闭的时间段无法单击，也无法拖过。
• 保存：任何内容都不会保存到已关闭的资源、日期和时间上。选择多个资源时，只排除已关闭的那个，其余空闲资源照常预订。

一张闭馆表，多个日历

为闭馆对象添加一个标签字段（Region、Location、Building），并在资源上添加同样的字段。每个日历随后用资源筛选字段 / 筛选值显示自己的资源，用屏蔽日期筛选字段 / 筛选值读取自己的闭馆记录。

11. 公共访客页面（Experience Cloud）

将组件放到 Experience Cloud 站点上，任何人无需登录即可预订。以访客身份测试前，请完成以下全部五个步骤。

1. 对象权限。为站点的访客用户授予每个对象的“读取”权限；如果访客要提交，还需授予“创建”权限。Salesforce 绝不允许访客编辑或删除记录，因此编辑、取消和删除页面应只给登录用户使用。
2. 为组件涉及的每个字段设置字段级安全性，包括资源的营业时间字段和闭馆时间字段。缺少任何一个字段，资源或闭馆查询都会失败。
3. 创建访客共享规则（读取），让访客能看到记录。对象的外部组织范围默认设置必须为私有，规则才会生效。以元数据部署的规则需要在“设置”的“共享设置”中单击一次重新计算。
4. 为站点的访客用户分配 MultiDatePick - Guest 权限集。它包含组件加载数据所需的 Apex 类访问权限。
5. 激活站点。发布和激活是两个独立的步骤。

• 访客看到哪条记录：公共页面使用 Static Parent Record Id，因此所有访客都针对同一条父记录预订（一个办公室、地点或资源）。如需每位访客对应一条记录，请用 Flow 配合 URL 参数来实现。真正的按用户日历需要登录用户。
• 联系人和客户：Salesforce 对访客访问这两个对象有严格限制。请将访客预订保存到自定义对象，或使用需要登录的站点。
• 同一页面上的多个组件：它们不会实时同步。请在组件之间加一个刷新提示，这样在一个组件中做的屏蔽才会显示在下一个组件中。

放置步骤见应用程序页面、主页和 Experience 页面。完整的站点示例见 Experience Cloud 预订。

12. 常见陷阱（FAQ）

看到横幅提示、找不到“保存”按钮或日历是空的？故障排除页面配有每条消息的截图和解决方法。

状态颜色没有生效

检查三点。(a) Status Field（状态字段）是否是准确的选项列表 API 名称？区分大小写。(b) Status Colors 是否使用 Value:#hex, Value:#hex 格式且不带引号？写成 'Confirmed':'#22C55E' 会在不报错的情况下失效。(c) 记录在该选项列表中是否真的有值？

保存的记录名称和预期不同

检查 Record Name Field（记录名称字段）：如果字段长度较短，长名称会被截断。检查 Append Date to Record Name：开启后，每个名称都会附加所选日期和时间。

如何在容量网格中隐藏 Cancelled 记录？

将 Ignored Statuses 设为 Cancelled，或 Cancelled,Rejected 这样的列表。这些记录将从日历和容量统计中移除。

屏蔽和隐藏有什么区别？

屏蔽（闭馆设置）让日期、时间或资源保持可见但不可预订：节假日、维护、关闭的会议室。隐藏则把 Cancelled 等记录从日历和容量中移除，从而释放时间段。请参阅屏蔽与隐藏。

没有出现“编辑”按钮

开启启用编辑模式即可，这是三个组件唯一的要求。状态字段是可选的，它只会在编辑器中添加一个状态下拉列表。如果按钮仍然不显示，说明页面或配置中关闭了“启用编辑模式”。

我只想显示部分资源（会议室，不要设备）

使用资源筛选字段和资源筛选值。单个值：字段 Active__c，值 true。多个值（或）：North,South。多个字段（且）：字段 Type__c;Active__c，值 Conference Room;true。

Date Time 总是显示一个共用的时间选择器

应使用的设置是时间显示模式：网格或下拉。在网格模式下，所有日期共用一个网格。如需每个日期各自设置时间，请选择下拉，并开启允许每个日期使用不同时间。

如何从 Flow 管理保存改为点击保存？

填写 Parent Record Id、Child Object API Name、Date Field API Name（日期字段 API 名称）和 Relationship Field API Name（关系字段 API 名称）。删除 Parse Date Entries from JSON 操作以及创建记录的循环。之后由组件自带的“保存”按钮写入记录。

弹出了错误提示，但没有任何详细信息

打开浏览器的开发者控制台，查找以 [MDP:ERROR] 开头的行。即使提示很简短，完整错误也一定会记录在那里。

13. Flow 示例

以下内容全部在 Flow Builder 中完成，无需 Apex。

循环遍历所选日期

1. 添加一个带 Date Time 组件的屏幕，将点击保存相关设置留空。
2. 在屏幕之后添加 Parse Date Entries from JSON 操作，并传入 Dates With Times JSON (Output)。
3. 循环遍历该操作返回的列表。每一项都包含开始日期、结束日期、开始时间和结束时间。
4. 在循环内将值赋给记录变量，并加入一个集合。循环结束后一次性创建记录。

将最早和最晚日期汇总到父记录

想让父记录显示子记录的最早和最晚日期？根据您的数据选择合适的无代码方式。

更多 Flow 模式：屏幕 Flow 指南。

14. 对象与字段映射

每个组件页面都有完整的对象与字段映射图：

• Date：对象映射
• Date Time：对象映射
• Booking：对象映射

组件适用于任何对象。软件包中的示例对象（Schedule、Event、Resource、Sub Block）只是默认值。将设置指向您自己的、带有合适字段的自定义对象或标准对象即可。

15. 全部属性参考

三个组件的每一项设置，按您在 Lightning App Builder、Experience Builder 和 Flow Builder 中看到的标签列出。每个标签下方是其 API 名称。

16. 安全性与无障碍

• 已通过 Salesforce AppExchange 安全审查。
• 100% 原生。您的数据始终留在您的 Salesforce 组织中。没有外部服务器，也没有外部调用 (callout)。请参阅信任与安全。
• 始终遵循您的权限。每次读取和保存都以用户自己的访问权限运行，因此每条记录都会强制执行对象权限、字段级安全性和共享规则。
• 无障碍。符合 WCAG 2.1 AA，已使用 axe-core 测试。提供完整的 VPAT 2.5。
• 9 种语言：英语、西班牙语、法语、德语、日语、印地语、葡萄牙语（巴西）、意大利语、简体中文。

17. 有问题或发现错误？

发现本指南有遗漏，或有功能出错？请发送电子邮件至 support@multidatepick.com。