访问 Salesforce 资源 — LWC @salesforce 模块完全指南

访问 Salesforce 资源

LWC 提供丰富的 @salesforce 作用域模块来访问平台全局资源——包括静态资源、内容资产文件、SVG、标签、国际化属性、用户信息、站点数据、权限和客户端外形尺寸。所有 @salesforce 导入在编译时针对组织元数据验证，提供类型安全的错误检测。

静态资源 —— 创建与上传

静态资源支持归档文件（.zip/.jar）、图片、样式表、JavaScript 等。Setup → Static Resources → New。命名规则：仅字母数字和下划线、字母开头、无空格、无连续下划线、组织内唯一。文件最大 5 MB，组织上限 250 MB。

缓存控制：Private——缓存不跨用户共享（仅当前会话）；Public——跨用户共享缓存，缓存后对所有互联网流量（包括未认证用户）开放。DX 项目中位于 /force-app/main/default/staticresources，每个资源需 .resource-meta 文件。

导入静态资源

import myResource from "@salesforce/resourceUrl/resourceReference";
// 托管包：import ... from "@salesforce/resourceUrl/namespace__resourceReference";

// 示例——单个文件 + 归档文件
import TRAILHEAD_LOGO from "@salesforce/resourceUrl/trailhead_logo";
import TRAILHEAD_CHARACTERS from "@salesforce/resourceUrl/trailhead_characters";

trailheadLogoUrl = TRAILHEAD_LOGO;                          // 直接 URL
einsteinUrl = TRAILHEAD_CHARACTERS + "/images/einstein.png"; // 归档内路径

<img src={trailheadLogoUrl} />
<img src={einsteinUrl} />

归档文件通过字符串拼接路径访问嵌套文件。模板中用标准 {property} 绑定。参考 lwc-recipes miscStaticResource。

访问内容资产文件

import myAsset from "@salesforce/contentAssetUrl/contentAssetReference";

import SALES_WAVE_LOGO from "@salesforce/contentAssetUrl/SalesWaveLogo";
import PARTNER_LOGOS from "@salesforce/contentAssetUrl/PartnerLogos";

goldPartnerLogoUrl = PARTNER_LOGOS + "pathinarchive=images/gold_partner.png";
// 归档内文件用 pathinarchive 参数而非直接拼接

内容资产文件专为自定义应用和 Experience Builder 模板设计。命名规则同静态资源。DX 项目中位于 /force-app/main/default/contentassets，配 .asset-meta 文件。归档嵌套文件使用 pathinarchive 参数。参考 lwc-recipes miscContentAsset。

使用 SVG 资源

方式一 —— 直接嵌入模板：将 SVG 标记直接写在 <template> 内——适合小型简单图标。

方式二 —— 作为静态资源导入：① SVG 文件加 id 属性 ② 上传为静态资源 ③ JS 中导入并拼接 #id ④ 模板中用 <use href={svgURL}>——适合大型 SVG、跨组件重用。

import SVG_LOGO from "@salesforce/resourceUrl/logo";
svgURL = `${SVG_LOGO}#logo`;
<svg><use href={svgURL}></use></svg>

LWC 支持的 SVG 标签

LWC 出于安全原因限制允许的 SVG 标签。容器：svg, g, defs, symbol, use, a, switch, view。形状：circle, ellipse, line, path, polygon, polyline, rect。文本：text, tspan, tref, title, desc, altGlyph 系列。渐变：linearGradient, radialGradient, stop, pattern, marker, mask, filter。媒体：image, audio, video, canvas。动画：animateColor, animateMotion, animateTransform, mpath。字体：font, glyph, glyphRef, hkern, vkern。

不支持的安全敏感元素：script、foreignObject、iframe、事件处理器属性——Locker 和 LWS 自动剥离。

访问标签（Labels）

自定义标签是存储在 Salesforce 中的可翻译文本值——用于创建多语言应用，以用户母语呈现信息。

import labelName from "@salesforce/label/labelReference";  // 格式：namespace.labelName

import greeting from "@salesforce/label/c.greeting";
import salesforceLogoDescription from "@salesforce/label/c.salesforceLogoDescription";

label = { greeting, salesforceLogoDescription };

<img src={logoUrl} alt={label.salesforceLogoDescription} />
{label.greeting}

标签文件格式（.labels-meta.xml）：<CustomLabels> 根元素，包含 fullName, value, language, protected, shortDescription。在 DX 项目中可放在 force-app/main/default 的任意子目录。

国际化属性 —— 概述

从 @salesforce/i18n 导入国际化属性，使组件适应全球用户——跨语言、货币和时区。推荐优先使用 lightning-input、lightning-formatted-* 等基础组件（自动适应）。

核心属性：lang（"en-US"）、dir（"ltr"/"rtl"）、locale（"en-CA"）、currency（"CAD"）、timeZone（"America/Los_Angeles"）、firstDayOfWeek。日期时间格式模式（short/medium/long 各三种）。数字/货币格式化（currencyFormat、decimalSeparator、groupingSeparator、percentFormat 等）。日历数据（defaultCalendar、calendarData、showJapaneseCalendar）。

LWR 站点注意：lang/locale 映射到站点语言、timeZone 来自浏览器（非用户设置）、currency 相关属性不支持。站点语言配置变更后必须重新发布。

国际化 —— 日期与货币格式化

// 日期格式化 —— 使用 Intl.DateTimeFormat
import LOCALE from "@salesforce/i18n/locale";
formattedDate = new Intl.DateTimeFormat(LOCALE).format(new Date(2020, 6, 7));
// en-US → "7/7/2020"  |  en-GB → "07/07/2020"

// 货币格式化 —— 使用 Intl.NumberFormat
import CURRENCY from "@salesforce/i18n/currency";
formattedNumber = new Intl.NumberFormat(LOCALE, {
  style: "currency", currency: CURRENCY, currencyDisplay: "symbol",
}).format(123456.78);
// en-US → "$123,456.78"  |  de-DE → "123.456,78 €"

Intl API 内置于所有现代浏览器——无需外部库。也可用 lightning-formatted-date-time 和 lightning-formatted-number 基础组件替代。

国际化 —— HTML 属性

import LANG from "@salesforce/i18n/lang";
import DIR from "@salesforce/i18n/dir";

lang = LANG;  dir = DIR;

<p lang={lang} dir={dir}>本地化文本</p>

lang 属性告诉屏幕阅读器正确的发音；dir 控制文本方向（RTL 语言如阿拉伯语/希伯来语）；CSS 可用 [dir="rtl"] 进行方向性样式设置。属性值遵循 Unicode LDML 规范。

获取当前用户信息

import Id from '@salesforce/user/Id';        // 当前用户 18 位 Salesforce 记录 ID
import isGuest from '@salesforce/user/isGuest'; // 是否为访客用户（未认证）

用途：传给 Apex 方法、按所有者过滤记录、基于认证状态条件渲染、个性化体验。编译时验证——组件加载时用户 ID 始终可用。TypeScript 支持：@salesforce/lightning-types 中的 user.d.ts。

Experience Builder 站点 —— @salesforce/community

重要：导入 @salesforce/community 或 @salesforce/site 的组件只能用于 Experience Builder 页面——不能用于其他 Salesforce 容器。

import Id from "@salesforce/community/Id";           // 站点 Network ID
import basePath from "@salesforce/community/basePath"; // URL 路径段（域名后部分）

// 用 community Id 限定 Feed 范围
@wire(getFeedElementPageForCommunity, { networkId: "$Id" }) feedElementPage;

basePath 示例：UniversalTelco.force.com/myPartnerSite/s → basePath = "myPartnerSite/s"。用于动态构建跨站点链接。

Experience Builder 站点 —— @salesforce/site

import Id from "@salesforce/site/Id";                     // 站点 ID
import activeLanguages from "@salesforce/site/activeLanguages"; // 活跃语言列表

// 示例数据：[{ code: 'en-US', label: 'English (US)' }, { code: 'fr', label: 'Français' }]
// 按 label 字母排序，仅包含 Experience Builder → Settings → Languages 中活跃的语言

完整语言选择器示例：填充 combobox → 选择变更时替换 URL 中的 locale 段 → 重定向。注意：LWR 站点中 Locker 可能限制 window 全局对象——此重定向模式需要禁用 Locker。

检查权限

// 标准权限
import hasViewSetup from '@salesforce/userPermission/ViewSetup';
// 自定义权限（同命名空间）
import hasPermission from "@salesforce/customPermission/PermissionName";
// 托管包自定义权限
import hasPermission from "@salesforce/customPermission/namespace__PermissionName";

// 值为 true（有权限）或 undefined（无权限）——布尔上下文自然工作
get isSetupEnabled() { return !hasViewSetup; }  // 无权限时禁用按钮
get isReportVisible() { return hasViewReport; }  // 有权限时显示报告

最佳实践：用静态引用替换父 Aura 组件中的动态权限检查。更高效——无需网络调用。参考 lwc-recipes miscPermissionBasedUI。

访问客户端外形尺寸

import FORM_FACTOR from '@salesforce/client/formFactor';
// 值：'Large'（桌面）、'Medium'（平板）、'Small'（手机）

// 传递给 getRecordCreateDefaults 获取正确的布局
@wire(getRecordCreateDefaults, { objectApiName: ACCOUNT_OBJECT, formFactor: FORM_FACTOR })

// 条件渲染
get isDesktop() { return FORM_FACTOR === 'Large'; }

编译时常量——在组件加载时确定。TypeScript 支持：@salesforce/lightning-types 中的 client.d.ts。

感谢阅读本指南。如需继续学习，请参阅下一章：组件无障碍访问。