扩展设置页面_add-extension-settings

以下为本文档的中文说明add-extension-settings 是微软官方提供的专门为 Visual Studio Code 命令面板扩展Command Palette Extension添加用户可配置设置页面的开发技能。VS Code 是目前最流行的跨平台代码编辑器之一其功能扩展Extension生态是其成功的关键因素。为用户提供直观且规范的配置界面是提升扩展的易用性、灵活性和用户满意度的重要途径。使用场景包括为正在开发的 VS Code 扩展添加用户可以通过图形化设置界面调整的配置项和选项开关、创建扩展的设置页面并定义配置的 Schema 约束包括类型、默认值、枚举选项等、在扩展代码中实现配置项的读取、验证、变更监听和默认值回退的完整管理逻辑。核心特点包括详细指导开发者如何在扩展项目的 package.json 清单文件的 contributes.configuration 贡献点中正确定义 JSON Schema 格式的设置项结构支持丰富多彩的设置值类型覆盖字符串String用于文本输入、数字Number用于数值调节、布尔值Boolean用于开关切换、枚举Enum用于下拉选择、数组Array和对象Object用于复杂结构化数据提供细粒度的设置作用域Scope控制全局Application范围、窗口Window范围、工作区Resource范围和机器级Machine范围支持为每个设置项提供本地化的描述名称和详细说明文字支持多语言 Localization提供对设置值的约束条件声明能力包括数值的最小值minimum和最大值maximum限制、字符串的 pattern 正则验证、枚举值列表enum的候选选项等高级校验规则包含通过 vscode.workspace.onDidChangeConfiguration 事件监听设置项变更的动态响应方案。该技能遵循 VS Code 官方扩展 API 的最佳实践确保扩展的设置页面与编辑器原生设置界面保持完全一致的用户体验。Add Extension SettingsAdd a settings page to your Command Palette extension using the built-in settings helpers. Settings are automatically persisted and restored by the extension host.When to Use This SkillAdding user-configurable options to your extensionCreating toggle switches for featuresAdding text input fields for configurationCreating dropdown menus for option selectionPersisting user preferences across sessionsQuick StartStep 1: Create a Settings ManagerCreate a new fileSettingsManager.cs:usingMicrosoft.CommandPalette.Extensions;usingMicrosoft.CommandPalette.Extensions.Toolkit;namespaceYourExtension;internalsealedclassSettingsManager{privatereadonlySettings_settings;publicSettingsManager(){_settingsnewSettings();varmaxResultsnewTextSetting(maxResults,Maximum Results,Maximum number of results to display,10);varshowSubtitlesnewToggleSetting(showSubtitles,Show Subtitles,Display subtitle text under each result,true);varsortOrdernewChoiceSetSetting(sortOrder,Sort Order,How to sort results,[newChoiceSetSetting.Choice(Alphabetical,alpha),newChoiceSetSetting.Choice(Most Recent,recent),newChoiceSetSetting.Choice(Most Used,frequent),],alpha);_settings.AddSetting(maxResults);_settings.AddSetting(showSubtitles);_settings.AddSetting(sortOrder);// React to settings changes_settings.SettingsChangedOnSettingsChanged;}publicICommandSettingsSettings_settings;publicintMaxResultsint.TryParse(_settings.GetSettingstring(maxResults),outvarval)?val:10;publicboolShowSubtitles_settings.GetSettingbool(showSubtitles);publicstringSortOrder_settings.GetSettingstring(sortOrder)??alpha;privatevoidOnSettingsChanged(object?sender,EventArgse){// React to settings changes (e.g., refresh data)}}Step 2: Wire into CommandProviderIn yourCommandsProvider, expose the settings:publicpartialclassMyCommandsProvider:CommandProvider{privatereadonlySettingsManager_settingsManagernew();privatereadonlyICommandItem[]_commands;publicMyCommandsProvider(){DisplayNameMy Extension;IconIconHelpers.FromRelativePath(Assets\\\\StoreLogo.png);Settings_settingsManager.Settings;// This exposes settings to CmdPal_commands[newCommandItem(newMyPage(_settingsManager)){TitleDisplayName},];}publicoverrideICommandItem[]TopLevelCommands()_commands;}Step 3: Use Settings in PagesinternalsealedpartialclassMyPage:ListPage{privatereadonlySettingsManager_settings;publicMyPage(SettingsManagersettings){_settingssettings;}publicoverrideIListItem[]GetItems(){varitemsGetAllItems();returnitems.Take(_settings.MaxResults).ToArray();}}Setting TypesTypeUI ControlValue TypeConstructor ParametersToggleSettingToggle switchbool(id, label, description, defaultValue)TextSettingText inputstring(id, label, description, defaultValue)ChoiceSetSettingDropdownstring(id, label, description, choices[], defaultValue)Key PointsSettings are automatically persisted by the CmdPal hostUseSettingsChangedevent to react to changes in real-timeAccess values viaGetSettingT(id)with the setting’s string idPass the settings manager to pages/commands that need configurationSettings page appears automatically whenSettingsis set onCommandProviderGrouping SettingsFor extensions with many settings, organize them into logical groups:publicSettingsManager(){_settingsnewSettings();// Appearance groupvarthemenewChoiceSetSetting(theme,Theme,UI theme,[newChoiceSetSetting.Choice(Light,light),newChoiceSetSetting.Choice(Dark,dark),newChoiceSetSetting.Choice(System,system),],system);varfontSizenewTextSetting(fontSize,Font Size,Display font size,14);// Behavior groupvarautoRefreshnewToggleSetting(autoRefresh,Auto-Refresh,Automatically refresh results,true);varrefreshIntervalnewTextSetting(refreshInterval,Refresh Interval,Seconds between auto-refreshes,30);_settings.AddSetting(theme);_settings.AddSetting(fontSize);_settings.AddSetting(autoRefresh);_settings.AddSetting(refreshInterval);}Reacting to ChangesUse theSettingsChangedevent to update behavior when the user modifies settings:privatevoidOnSettingsChanged(object?sender,EventArgse){// Invalidate cached data_cachedItemsnull;// Notify pages to refreshOnItemsChanged?.Invoke(this,EventArgs.Empty);}DocumentationSampleSettingsPage.cs3c:[“ , ,,L3f”,null,{“content”:“$40”,“frontMatter”:{“name”:“add-extension-settings”,“description”:“Add a settings page to your Command Palette extension. Use when asked to add settings, preferences, configuration options, toggles, text inputs, dropdowns, or user-customizable behavior. Covers ToggleSetting, TextSetting, ChoiceSetSetting, and persistence.”}}]3d:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“ , h 2 , n u l l , i d : r e l a t e d − s k i l l s − h e a d i n g , c l a s s N a m e : t e x t − 2 x l f o n t − s e m i b o l d t r a c k i n g − n o r m a l t e x t − f o r e g r o u n d , c h i l d r e n : 同仓库更多 S k i l l s ] , [ ,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L 41 , L41,L41,L42”,“L 43 , L43,L43,L44”,“L 45 , L45,L45,L46”]}]]}]]}]47:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]