快速上手：探索 Dreamhouse 示例应用

部署示例应用（01 Deploy the Sample App）

在探索 Dreamhouse 之前，你需要先把它部署到组织里。本单元你将了解这个应用能做什么、理解前置条件（Salesforce DX 工具）、创建全新的 Trailhead Playground、获取凭据、安装 Git，并用 Visual Studio Code 加 Salesforce CLI 从 GitHub 完成部署。这一单元涵盖环境搭建——把这个精致的 LWC 应用装进你的组织。

完成本项目后，你将能够：

• 部署 Dreamhouse 示例应用；
• 探索 Dreamhouse 示例应用；
• 探索其组件与示例代码。

认识 Dreamhouse 示例应用（一）：它是什么（Meet the Dreamhouse Sample App (1): What It Is）

Dreamhouse 是一家虚构的房地产公司，使用 Salesforce 管理房源（properties）和经纪人（brokers）。这个示例应用是 Trailhead 画廊里的旗舰项目之一，它演示了：

• Lightning Web Components（LWC）——现代 Salesforce UI 框架；
• Lightning Experience 特性——App Builder、记录页、自定义页面模板；
• 丰富的用户体验——动态筛选、地图、分页列表、照片轮播。

应用有两个主要页面：Property Explorer（以列表为中心，带筛选）和 Property Finder（以地图为中心，带地理位置）。它们完全由自定义 Lightning Web 组件构建。与只展示单个组件的简单教程不同，Dreamhouse 演示了多个 LWC 组件如何协同工作——通过 Lightning Message Service 通信、通过 wire adapter 共享数据、组合成一个完整应用。这就是生产级 LWC 架构的样子。

认识 Dreamhouse 示例应用（二）：关于与前置条件（Meet the Dreamhouse Sample App (2): About & Prerequisites）

这个项目会教你 Lightning Web Components 编程模型，并给你可用来启动自己 LWC 开发的代码。关于这个项目：

• 从 Trailhead Sample Gallery 安装；
• 包含帮助你学习 LWC 编程模型的示例；
• 提供能让你快速上手 LWC 开发的代码。

开始之前——前置条件：你必须先完成 Quick Start: Lightning Web Components 项目，它帮你搭好 Salesforce DX 开发环境：

• Salesforce CLI——组织管理与源码部署；
• Visual Studio Code + Salesforce Extension Pack——LWC 开发环境；
• Git——克隆仓库的版本控制。

没有这些工具，就无法部署应用。示例应用托管在 GitHub 上——你用 Git 克隆它，再用 Salesforce CLI 部署。

认识 Dreamhouse 示例应用（三）：你将构建什么（Meet the Dreamhouse Sample App (3): What You'll Build）

完成本项目后，你将：

• 把一个完整的 LWC 应用部署到 Trailhead Playground；
• 探索 Property Explorer 和 Property Finder 页面；
• 理解 Lightning Message Service 如何连接独立组件；
• 看到连接 Apex 与 Lightning Data Service 的 wire adapter 实战；
• 修改一个组件并用一条 CLI 命令重新部署；
• 学会自定义页面模板如何控制响应式布局。

本项目分三个单元，对应真实的开发工作流：部署 → 探索 → 深入代码。开始部署吧！

创建新的 Trailhead Playground（Create a New Trailhead Playground）

从一个干净的环境开始：

1. 滚动到本页底部；
2. 点击 Launch 旁的下箭头；
3. 选择 Create a Trailhead Playground；
4. 等待 3–4 分钟。

务必使用全新的 Playground！Dreamhouse 会部署自定义对象（Property、Broker）、Lightning Web 组件、自定义页面模板、Apex 类和静态资源——部署到已有自定义的组织里可能产生元数据冲突。全新的 Playground 能保证兼容；示例应用自带数据，你无需手动创建记录。

获取 Playground 用户名与密码（一）：查找凭据（Get Credentials (1): Find Credentials）

准备好登录凭据：

1. 点击本页底部的 Launch 打开 Playground；
2. 如果看到 Get Your Login Credentials 标签——点击它、记下用户名，然后点击 Reset My Password；
3. 如果没有，从 App Launcher 打开 Playground Starter 按步骤操作；
4. 查收邮件并点击重置链接；
5. 设置新密码并确认。

和所有基于 SFDX 的项目一样，你需要一个自己知道的密码。CLI 通过浏览器 OAuth 认证，会跳转到 Salesforce 登录页——你输入用户名和密码，Salesforce 生成访问令牌。自动生成的密码从不显示给你，所以必须重置。

获取 Playground 用户名与密码（二）：保存凭据（Get Credentials (2): Save Credentials）

重置后，把用户名和密码都安全地保存好——部署时 CLI 会打开浏览器登录页，届时需要它们。

CLI 使用 OAuth 认证：你直接登录 Salesforce，密码只在你和 Salesforce 之间，从不进入终端。如果弄丢了密码，重复重置流程即可。凭据就绪后，安装 Git 并部署应用。

获取 Git 命令行（Get Git Command Line）

安装 Git——用于克隆 Dreamhouse 仓库的版本控制系统：

1. 从 https://git-scm.com/downloads 下载并安装，全部接受默认设置；
2. 验证：在 Terminal/Command Prompt 中输入 git，应显示帮助列表。若报错，重启终端刷新 PATH。

Git 是一次性安装。链路是：GitHub → git clone → 本地文件 → VS Code → Salesforce CLI → 你的组织。Git 只克隆一次代码，之后的部署和修改都交给 CLI。

部署应用（一）：VS Code 设置（Deploy the App (1): VS Code Setup）

用 Visual Studio Code 部署 Dreamhouse：

1. 打开 Visual Studio Code；
2. 打开 Command Palette：View → Command Palette（或 Ctrl+Shift+P / Cmd+Shift+P）；
3. 打开终端：Terminal → New Terminal。

为什么用 VS Code + 集成终端？一个窗口里既能看代码又能部署；Salesforce Extension Pack 为 LWC（HTML、JS、CSS）、Apex 和元数据 XML 提供语法高亮；终端用于运行 CLI 命令（git clone、sf deploy）。接下来按项目 readme 克隆并部署。

部署应用（二）：克隆与部署（Deploy the App (2): Clone & Deploy）

按 github.com/trailheadapps/dreamhouse-lwc 上项目 README 的 "Installing Dreamhouse using a Developer Edition Org or a Trailhead Playground" 一节操作。典型流程：

1. git clone <dreamhouse 仓库地址>；
2. cd dreamhouse-lwc；
3. 用你的 Playground 认证 CLI——浏览器打开，用凭据登录；
4. 把源码部署到组织——sf project deploy start（或类似命令）。

部署完成后，打开 Playground，App Launcher 里会出现 Dreamhouse 应用，带 Property Explorer 和 Property Finder 标签。恭喜！Dreamhouse 已在你的组织里上线，接下来探索它能做什么。

了解示例应用（02 Get to Know the Sample App）

应用已部署，现在以一个最终用户的视角使用它。你将探索带动态筛选和分页列表的 Property Explorer 页面、以地图浏览为特色的 Property Finder、带自定义 LWC 组件的房源与经纪人记录页，甚至在手机上体验应用。这一单元让你在深入代码之前，先理解它作为产品的样子。

发现 Property Explorer（一）：浏览与筛选（Discover the Property Explorer (1): Browse & Filter）

Property Explorer 是一个用自定义 Lightning Web 组件构建的 Lightning 应用页面：

1. 从 App Launcher 选择 Dreamhouse 打开应用；
2. 点击 Property Explorer 标签。

页面包含四个顶层自定义组件：

• propertyFilter——按卧室数、价格等条件筛选；
• propertyTileList——符合筛选条件的分页房源列表；
• propertySummary——所选房源的详情；
• propertyMap——位置地图。

试试筛选：改变筛选值，房源列表动态更新；选中一个房源（比如 City Living），详情就出现在 summary 和地图里。所有组件实时相互响应，无需整页刷新——这就是 LWC + LMS 的力量。

发现 Property Explorer（二）：房源与经纪人记录（Discover the Property Explorer (2): Property & Broker Records）

继续探索单个房源和经纪人记录：

1. 选中 City Living 房源，注意右上角的房源详情组件；
2. 把 Beds 数量改成 5——详情立即更新（这是 LDS 的响应式！）；
3. 点击房源详情组件上的双箭头，打开 City Living 房源记录页。

这个记录页使用了四个自定义 LWC 组件：房源经纪人详情、上市天数计数器、位置地图、照片轮播。

接着点击 Broker 卡片上的双箭头，打开 Broker 记录页——它用的是标准组件，比如 Related List (Single)。

这演示了 LWC 不仅能用于独立应用页面，还能通过 Lightning App Builder 无缝集成到标准记录页。记录页上自定义 LWC + 标准组件 = 两全其美——需要独特功能的地方用自定义组件，其余用标准组件。

在 Property Finder 中地图找房（一）：以地图为中心（Map Properties in the Property Finder (1): Map-Centric View）

Property Finder 是第二个 Lightning 应用页面——以地图为中心而非列表：

1. 点击 Property Finder 标签。

四个顶层自定义组件：

• propertyFilter——与 Explorer 相同的筛选器；
• propertyListMap——房源地图（使用第三方库 Leaflet.js！）；
• propertySummary——所选房源详情；
• Days on Market——视觉指示器。

试试筛选，看地图动态更新标记；点击地图上的房源标记，详情出现在 summary 里。这是同一份数据的两种视图——列表视图（Explorer）和地图视图（Finder），同样的组件、不同的排列。真实应用中很常见：数据密集的任务用列表视图，空间浏览用地图视图。

在 Property Finder 中地图找房（二）：LMS 实战（Map Properties in the Property Finder (2): LMS in Action）

和 Property Explorer 一样，Property Finder 的组件也通过 Lightning Message Service（LMS） 通信：

• 筛选变化 → FiltersChange 消息 → propertyListMap 更新地图标记；
• 地图上选中房源 → PropertySelected 消息 → propertySummary 显示详情。

关键在于：两个页面使用相同的消息通道类型——FiltersChange 和 PropertySelected。propertyFilter 无论在哪个页面上都发布同样的消息；propertySummary 无论选中来自列表点击还是地图点击，都监听 PropertySelected。这种解耦意味着你可以随意在页面间重新排列组件、添加新页面、或创建响应相同消息的新组件——而无需改动现有组件代码。LMS 提供通信总线，组件只负责发布和订阅通道。

在手机上体验应用（一）：移动体验（Take a Look at the App on Mobile (1): Mobile Experience）

Dreamhouse 也能在移动设备上工作：

1. 打开 Salesforce mobile app，用 Playground 凭据登录；
2. 点击 App Launcher 打开应用菜单；
3. 选择 Dreamhouse 应用；
4. 探索各个标签——Property Explorer、Property Finder 和记录页都会自适应移动屏幕。

这靠的是：LWC 组件天生响应式，能在任意屏幕尺寸工作；自定义页面模板为桌面和移动端定义了不同布局（Unit 3 详述）；带自定义 LWC 的记录页自动在 Salesforce 移动应用中工作。写一次，桌面和移动端都能跑。

在手机上体验应用（二）：为什么重要（Take a Look at the App on Mobile (2): Why It Matters）

移动就绪的 LWC 意味着：

• 在外跑业务的房地产经纪人能用手机浏览房源；
• 经纪人能在客户会面之间快速查看房源详情；
• 地图视图在移动端尤其有用——能看到当前位置附近的房源；
• 无需单独的移动端开发——同样的组件处处可用。

对房地产应用来说，移动兼容是业务刚需。Dreamhouse 无需额外开发就能在移动端工作，正是 LWC 框架设计的体现。Unit 3 里，你将看到让这一切成为可能的代码——从响应式自定义页面模板，到高效加载数据的 wire adapter，再到连接一切的 Lightning Message Service。

深入示例应用组件（03 Dig into the Sample App Components）

现在揭开引擎盖看看内部。你将研究 Property Explorer 的四个组件如何通过 Lightning Message Service 通信、wire adapter 如何连接 Apex 和 Lightning Data Service、自定义页面模板如何控制响应式布局，以及第三方 JavaScript 库如何与 LWC 集成。你甚至要做一处小改动并重新部署——体验完整的 LWC 开发工作流。

Property Explorer 代码亮点（一）：LMS 架构（Property Explorer Code Highlights (1): LMS Architecture）

Property Explorer 页面有四个组件，全部通过 Lightning Message Service 通信：

• propertyFilter——用户改变筛选值时发布 FiltersChange 消息；
• propertyTileList——订阅 FiltersChange 更新分页列表，用户点击房源时发布 PropertySelected；
• propertySummary——订阅 PropertySelected，通过 LDS getRecord wire adapter 获取房源详情；
• propertyMap——订阅 PropertySelected，通过 LDS getRecord 获取地址并渲染地图标记。

每个组件只知道它发布或订阅的消息，不直接引用其它组件。两个组件（summary 和 map）用同一个 LDS adapter 获取同一条记录——LDS 自动缓存数据，只取一次。这是教科书级的松耦合：即使再加第五个订阅 PropertySelected 的组件，也无需改动任何现有代码。

Property Explorer 代码亮点（二）：LMS 的好处（Property Explorer Code Highlights (2): LMS Benefits）

为什么用 Lightning Message Service？

• 组件可以跨越任意 DOM 层级通信——LWC 到 LWC、LWC 到 Aura、甚至 LWC 到 Visualforce；
• 无需父子关系——同一页面上的组件通过消息通道以对等方式通信；
• 每个组件独立开发、测试和部署；
• 你可以在页面上重新排列、添加或移除组件，而无需改动任何组件的代码。

LMS 解决了组件化 UI 开发中最难的问题之一：同一页面上互不相关的组件如何通信？没有 LMS，你需要父组件协调一切，或让自定义事件沿 DOM 树向上冒泡。有了 LMS，组件通过命名消息通道通信——向通道发布消息、订阅关心的通道，框架负责投递。Dreamhouse 只用了 LWC 到 LWC，但架构可扩展到混合组件类型的页面。

Property Filter 组件（一）：基础组件与 LMS（Property Filter Component (1): Base Components & LMS）

propertyFilter 组件用 Base Lightning Components 获取用户输入：

• lightning-input——文本和数字字段（卧室数、浴室数、价格）；
• lightning-slider——范围输入（价格区间滑块）。

为什么用 Base Components？免费获得 SLDS 样式（无需写 CSS 就专业美观）、内置可访问性（键盘导航、屏幕阅读器支持）、行为一致（所有 Lightning 页面同样的 UX）。

当任何筛选值改变时：propertyFilter 收集所有当前筛选值到一个对象里，通过 LMS 发布一条 FiltersChange 消息。订阅者收到的是完整的筛选状态，而不只是改变的那一个字段——因为订阅者可能需要应用全部筛选条件。这是发布者的职责：每条消息都提供完整状态。

Property Filter 组件（二）：动手练习（Property Filter Component (2): Hands-On Exercise）

现在动手——实际修改代码并重新部署，体验完整的 LWC 开发周期：

1. 在 VS Code 中打开 force-app/main/default/lwc/propertyFilter/propertyFilter.html；
2. 找到用于输入价格的 lightning-slider；
3. 把它的 label 属性改为 Max to Spend；
4. 保存文件；
5. 部署到组织：运行 CLI 部署命令，或右键文件选择 SFDX: Deploy This Source to Org；
6. 刷新 Property Explorer 页面（可能需要清缓存）；
7. 看到更新后的滑块标签！

编辑 → 部署 → 刷新 → 看结果——这就是 LWC 开发周期。改一处、推到组织、几秒内看到效果。没有漫长的构建流程，没有部署队列，只有快速迭代。这正是开发者热爱 LWC + Salesforce DX 工作流的原因。

Property Tile List 组件（一）：连接 Apex 的 Wire Adapter（Property Tile List Component (1): Wire Adapter to Apex）

propertyTileList 组件演示了 LWC 如何连接服务端 Apex：

1. 订阅 FiltersChange 消息，用 handleFilterChange() 跟踪当前筛选条件和页码；
2. 用 wire adapter 调用 Apex：@wire(getPagedPropertyList, {...})；
3. getPagedPropertyList 从 PropertyController.cls（带 @AuraEnabled 方法的 Apex 类）导入；
4. Apex 方法用应用中的筛选条件运行 SOQL 查询，返回带当前页结果的 PagedResult 对象；
5. 结果在客户端缓存——切换到已加载过的页面是即时的。

Wire adapter = 响应式的 Apex 调用。当参数变化时（筛选改变、翻页），框架自动重新调用 Apex 并更新组件。数据更新是自动的。

Property Tile List 组件（二）：分页与缓存（Property Tile List Component (2): Pagination & Cache）

wire adapter 实现的关键细节：

• 页面大小可通过 pageSize 属性配置，控制每页显示多少房源；
• 结果分批分页——只把当前页的数据发给客户端（对大数据集高效）；
• 客户端缓存让之前看过的页面再次访问时即时加载；
• 筛选条件改变时缓存自动失效——为新的筛选组合重新获取数据。

模式是：用户操作 → LMS 消息 → wire adapter 参数变化 → 调用 Apex → 缓存结果 → 组件重渲染。这就是 LWC 处理大数据集的方式：服务端分页 + 客户端缓存，无论数据集多大都能提供流畅体验。

Property Summary 组件（Property Summary Component）

propertySummary 组件用 Lightning Data Service（LDS） 而不是 Apex：

1. 订阅 PropertySelected 消息；
2. 用 @wire(getRecord, { recordId, fields })——这是 LDS wire adapter，不是 Apex 方法；
3. getRecord 由 lightning/uiRecordApi 模块提供。

为什么这里用 LDS 而不是 Apex？

• 声明式——单条记录查询无需写 Apex 代码；
• LDS 自动处理缓存、CRUD 安全和字段级安全；
• 开发更快——无需编写 Apex 类；
• propertyMap 组件用同一个 adapter——两者拿到同一条缓存的记录，数据只取一次，组件间共享。

经验法则：单条记录读取用 LDS，自定义查询和复杂逻辑用 Apex wire adapter。

Property Map 组件（一）：地图集成（Property Map Component (1): Map Integration）

propertyMap 组件把房源位置渲染到地图上：

1. 订阅 PropertySelected 消息；
2. 用 LDS getRecord wire adapter 获取房源地址；
3. 渲染一个以房源位置为中心的 lightning-map Base Component。

lightning-map 是 Base Lightning Component：无需自定义 JavaScript 就能渲染地图，处理标记、缩放和平移，桌面和移动端都能用。

这个组件之所以简单，是因为它委托给 Base Components：LDS 负责数据、lightning-map 负责显示。LWC 开发的哲学就是：关注让你组件独特的部分——业务逻辑，把通用 UI 交给 Base Components。

Property Map 组件（二）：共享缓存模式（Property Map Component (2): Shared Caching Pattern）

两个组件、同一条记录、一次 API 调用：

• propertySummary → getRecord(propertyId)；
• propertyMap → getRecord(propertyId)。

LDS 检测到重复请求后：从服务器只取一次记录，缓存在客户端，把同一份缓存数据提供给两个组件；若任一组件更新记录，缓存失效，两个组件一起重渲染。

这一切是自动的，你无需配置，LDS 处理去重和同步。结果是：更少的 API 调用（性能更好）、组件间数据一致（不会一处新一处旧）、更少的代码（无需手动管理缓存）。这就是为什么单条记录要用 LDS，而不是自己写 Apex callout。

自定义页面模板（一）：布局控制（Custom Page Template (1): Layout Control）

Dreamhouse 用的是自定义页面模板，而不是标准 Lightning 页面模板：

• 标准模板给你固定的区域，自定义模板给你完全的控制；
• Dreamhouse 模板把页面分成 12 等列（标准 CSS 网格模式）；
• 定义三个区域：Region 1 = 2 列（筛选器）、Region 2 = 7 列（主内容）、Region 3 = 3 列（详情/地图）；
• 桌面端并排布局，移动端三个区域垂直堆叠、各占全宽。

注意：自定义页面模板仍以 Aura 组件构建（遗留技术），但用来托管 LWC 组件。Aura 提供模板基础设施，LWC 提供内容——这种混合方式是当前自定义页面布局的标准。

自定义页面模板（二）：为什么自定义模板重要（Custom Page Template (2): Why Custom Templates Matter）

什么时候用自定义页面模板：

• 页面需要内置模板无法实现的非标准布局；
• 你想精确控制列宽、响应式断点和区域行为；
• 设计要求特定比例（如 Dreamhouse 的 2-7-3 划分）。

什么时候用标准模板：简单布局（header + main + sidebar）、布局能套用内置选项、无需响应式定制。

自定义模板是进阶但强大的工具。响应式行为也至关重要——桌面端三区域并排，移动端堆叠，你可以精确控制布局在何时、以何种方式随断点变化。虽然模板用 Aura 语法，但里面的组件完全是现代 LWC。这是 Aura 在新开发中仍扮演角色的唯一地方。

Property Finder 代码亮点（Property Finder Code Highlights）

Property Finder 页面遵循与 Property Explorer 相同的架构模式：

• propertyFilter——发布 FiltersChange；
• propertyListMap——订阅 FiltersChange，用 Leaflet.js 渲染地图；
• propertySummary——订阅 PropertySelected，用 LDS getRecord。

区别在于：propertyListMap 取代了 propertyTileList——地图视图代替列表视图。但它们用相同的 LMS 消息通道（FiltersChange、PropertySelected），组件可互换。架构允许在不改动其它任何东西的情况下替换组件：列表视图 ↔ 地图视图，同样的数据、同样的消息、不同的呈现。这就是基于 LMS 架构真正的威力——你可以再建第三个视图（数据表格、日历、看板），插入同一架构，而无需修改任何现有组件。

Property List Map 组件（Property List Map Component）

propertyListMap 组件演示了把第三方 JavaScript 库与 Lightning Web Components 集成：

• 使用 Leaflet.js——流行的开源 JavaScript 地图库；
• Leaflet 作为 Static Resource 上传，导入到 LWC 中；
• 组件创建 Leaflet 地图实例并为房源添加标记。

第三方 JS + LWC 的模式：

1. 把库作为 Static Resource 上传；
2. 在 LWC 的 JS 文件中导入；
3. 在 renderedCallback() 或组件 DOM 就绪后使用；
4. 在 disconnectedCallback() 中清理。

这个模式适用于任何 JavaScript 库：Chart.js、D3、Moment.js……只要能在浏览器运行，就能在 LWC 里运行。

接下来（一）：你学到了什么（What's Next? (1): What You Learned）

你已经从三个视角探索了 Dreamhouse 示例应用：

部署（Deploy）——Salesforce DX 工作流：CLI + VS Code + Git → 部署到组织。

探索（Explore）——用户体验：Property Explorer（列表视图）、Property Finder（地图视图）、移动响应式设计。

代码（Code）——LWC 架构模式：

• Lightning Message Service（LMS）——组件间松耦合；
• Wire adapters——响应式 Apex 调用 + 单条记录访问的 LDS；
• Base Lightning Components——预置 UI；
• 自定义页面模板——响应式布局；
• 第三方 JS 集成——Leaflet.js。

这些模式适用于任何你构建的 LWC 应用，不只是 Dreamhouse。它们是整个 Salesforce 生态里生产级 LWC 应用通用的标准模式。

接下来（二）：进一步探索（What's Next? (2): Explore Further）

导览已完成，但还有更多可以自己探索：

• 研究源码里的所有组件——远不止我们覆盖的这些；
• 修改组件并重新部署——改标签、样式、行为。改坏再修好，这是最好的学习方式；
• 探索 Trailhead Sample Gallery 里的其它示例应用：E-Bikes（LWC + Heroku）、LWC Recipes（聚焦 LWC 示例）、Visualforce to LWC（迁移模式）；
• 看看 "Discover Trailhead Sample Apps" 学习路径获取更多引导项目。

每个示例应用都在 GitHub 上开源。克隆、研究、修改、学习——这就是你成为 LWC 专家的路径。

---

文章来源：Trailhead - Quick Start: Explore the Dreamhouse Sample App