企业官网建设流程全解析

• 示例工程

本指南以仓库中归档的 Touch Keyboard 示例 为线索，系统讲解 UWP 应用中触控键盘（输入面板 InputPane）的默认显示规则、Showing/Hiding事件订阅以及TryShow()/TryHide()编程控制方法。通过阅读本文，你将掌握触控键盘何时自动弹出、如何感知其显隐、如何主动接管显隐时机，并能直接复刻该示例的三个核心场景。

示例概述与场景总览

Touch Keyboard 示例展示了 UWP 应用中触控键盘的两种核心能力：默认显示行为与行为的自定义。官方描述为：

Shows both the default display behavior of the touch keyboard and how that behavior can be customized in a UWP app.

从 SampleConfiguration.cpp 的场景注册表可以看到，该示例由三个场景构成：

Platform::Array<Scenario>^ MainPage::scenariosInner = ref new Platform::Array<Scenario> { { "Display touch keyboard automatically", "SDKTemplate.Scenario1_Launch" }, { "Listen for Show/Hide events", "SDKTemplate.Scenario2_ShowHideEvents" }, { "Programmatically Show/Hide\nthe touch keyboard", "SDKTemplate.Scenario3_ShowHideMethods" } };

三个场景分别对应 README 中列出的四条能力：

• XAML 文本控件（TextBox、RichTextBox、PasswordBox）默认显示触控键盘；
• 从 XAML 文本控件派生的控件默认同样显示触控键盘；
• 应用可以订阅触控键盘显示/隐藏的事件；
• 应用可以主动请求显示或隐藏触控键盘。

系统要求

依据 README 中 "System requirements" 一节，本示例的运行环境要求为：

• 客户端（Client）：Windows 10
• 服务器（Server）：Windows Server 2016 Technical Preview
• 手机（Phone）：Windows 10，但注意KeyboardEnabledTextBox在手机端不受支持（详见下文说明）

另外需要强调两点前提：

• Windows universal samples 需要Visual Studio进行编译、需要Windows 10才能运行；
• 示例中的 C++ 版本依赖 Windows 10 通用 SDK，其 Package.appxmanifest 中声明了TargetDeviceFamily Name="Windows.Universal" MinVersion="10.0.10240.0" MaxVersionTested="10.0.18362.0"，即最低适配 Windows 10 10240（RTM 版本），实测兼容到 18362（Windows 10 1903）。

构建与运行示例

按照 README 的 "Build the sample" 与 "Run the sample" 两节，操作步骤如下：

构建：

1. 启动 Visual Studio，选择File→Open→Project/Solution；
2. 进入解压后示例目录中对应语言（C++ / C# / JavaScript）的子目录，双击.sln解决方案文件（本仓库中 C++ 版为 TouchKeyboard.sln）；
3. 按Ctrl+Shift+B，或选择Build→Build Solution完成编译。

运行：

• 仅部署：选择Build→Deploy Solution；
• 部署并调试运行：按F5或选择Debug→Start Debugging；
• 不调试直接运行：按Ctrl+F5或选择Debug→Start Without Debugging。

场景一：默认显示行为（Scenario 1）

场景一的 XAML 页面位于 Scenario1_Launch.xaml，对应后台代码 Scenario1_Launch.xaml.cpp（仅完成页面初始化，说明默认行为无需任何代码介入）。页面中放置了三类控件来演示默认行为：

• 原生TextBox（提示文字 "The keyboard displays when you tap here."）；
• 自定义控件local:CustomTextBox——从TextBox派生的控件，证明派生自文本控件的类型同样继承默认触控键盘行为；
• 一个普通Button，用于演示点击非文本区域时键盘隐藏。

XAML 中的说明文字明确了默认规则：当触摸或触笔将焦点设置到 XAML 文本控件（如 TextBox、RichTextBox、PasswordBox）或从文本控件派生的控件时，触控键盘会显示。

自动显示的两条硬性条件

页面中特别以加粗列表形式给出了自动显示的前提条件，这同样是 README 中 "Note" 段的核心内容：

1. 未激活硬件键盘；
2. 且满足以下任一条件：
   • 2a. 设备处于平板模式（Tablet mode）；或
   • 2b. 在Settings → Devices → Typing中开启了 "Show the touch keyboard when not in tablet mode and there's no keyboard attached"（非平板模式下且无外接键盘时显示触控键盘）。

换言之，如果外接硬件键盘处于激活状态，或设备处于桌面模式且上述设置项为 "Off"，触控键盘不会自动弹出。这是开发者在真机调试时最常见的"键盘不出来"原因，属于系统级策略而非应用缺陷。

场景二：监听 Showing / Hiding 事件（Scenario 2）

场景二展示如何感知触控键盘的显隐状态。页面 Scenario2_ShowHideEvents.xaml 包含一个用于唤起键盘的TextBox、一个普通按钮以及一个文本Run（x:Name="LastInputPaneEventRun"）用于显示最近一次事件。

后台逻辑 Scenario2_ShowHideEvents.xaml.cpp 完整演示了InputPane事件的生命周期管理：

void Scenario2_ShowHideEvents::OnNavigatedTo(NavigationEventArgs^ e) { auto inputPane = InputPane::GetForCurrentView(); // Subscribe to Showing/Hiding events showingEventToken = inputPane->Showing += ref new TypedEventHandler<InputPane^, InputPaneVisibilityEventArgs^>(this, &Scenario2_ShowHideEvents::OnShowing); hidingEventToken = inputPane->Hiding += ref new TypedEventHandler<InputPane^, InputPaneVisibilityEventArgs^>(this, &Scenario2_ShowHideEvents::OnHiding); } void Scenario2_ShowHideEvents::OnNavigatedFrom(NavigationEventArgs^ e) { auto inputPane = Windows::UI::ViewManagement::InputPane::GetForCurrentView(); // Unsubscribe from Showing/Hiding events inputPane->Showing -= showingEventToken; inputPane->Hiding -= hidingEventToken; }

实现要点：

• API 入口：Windows::UI::ViewManagement::InputPane::GetForCurrentView()，返回当前视图关联的输入面板实例，全程无需获取页面控件；
• 事件类型：Showing与Hiding，事件参数为InputPaneVisibilityEventArgs，本例未使用参数内容，仅用于区分事件来源；
• 订阅/退订配对：+=返回事件令牌（token），在OnNavigatedFrom中用-=退订，避免页面导航离开后继续收到事件造成泄漏或空指针访问——这是 UWP C++/CX 事件处理的推荐模式；
• 事件处理器中仅更新LastInputPaneEventRun->Text为L"Showing"或L"Hiding"，页面据此实时回显最后一次键盘显隐动作。

场景三：TryShow / TryHide 编程控制（Scenario 3）

场景三演示应用主动接管键盘显隐，解决"键盘遮挡内容"的经典问题。页面 Scenario3_ShowHideMethods.xaml 定义了一个名为FadeOutResults的 Storyboard：对结果文本ResultsTextBlock的Opacity执行 0→1 的DoubleAnimation（时长 1 秒、AutoReverse="True"、QuarticEase EaseOut 缓动），动画完成后触发OnFadeOutCompleted。

后台逻辑 Scenario3_ShowHideMethods.xaml.cpp 的核心代码如下：

void Scenario3_ShowHideMethods::WordListBox_OnKeyUp(Object^ /*sender*/, KeyRoutedEventArgs^ e) { if (e->Key == Windows::System::VirtualKey::Enter) { String^ text = WordListBox->Text; if (!text->IsEmpty()) { InputPane::GetForCurrentView()->TryHide(); ResultsTextBlock->Text = text; FadeOutResults->Begin(); } } } void Scenario3_ShowHideMethods::OnFadeOutCompleted(Object^ /*sender*/, Object^ /*e*/) { ResultsTextBlock->Text = L""; InputPane::GetForCurrentView()->TryShow(); }

工作流程与设计意图：

1. 用户在文本框中输入并按下Enter（通过KeyDown事件WordListBox_OnKeyUp捕获VirtualKey::Enter）；
2. 调用InputPane::GetForCurrentView()->TryHide()立即隐藏触控键盘，避免其遮挡下方将要显示的大字号结果文本（FontSize="150"）；
3. 将输入内容写入结果文本并播放淡入动画；
4. 动画结束后（OnFadeOutCompleted），清空结果文本并调用TryShow()重新唤起触控键盘，恢复输入流程。

这里体现了两个核心 API 的语义：

• TryHide()：尝试隐藏输入面板，返回bool表示是否成功执行；
• TryShow()：尝试显示输入面板，同样返回bool。

与事件订阅不同，这两个方法允许应用在任意时机（不限于用户触摸文本控件时）决定键盘的显隐，典型场景即本示例演示的"提交输入时收起键盘、展示结果后重新唤出"。页面还保留了OnNavigatedFrom中对FadeOutResults->Stop()的调用，防止页面导航离开时动画仍在运行。

扩展阅读：CustomEditControl 示例

README 中专门提示：Custom text edit control sample展示了如何在自定义文本编辑控件中以编程方式管理触控键盘的可见性。该示例位于 Samples/CustomEditControl 目录下，与本示例形成互补：本示例使用标准的 XAML 文本控件演示默认行为与事件/方法控制，而 CustomEditControl 则将同样的InputPane控制逻辑下沉到自定义控件内部实现。

关键结论

• 默认行为零代码：标准 XAML 文本控件及其派生控件的触控键盘唤起由系统自动完成，前提是未激活硬件键盘且满足平板模式或系统设置项开启；
• 事件驱动感知：通过InputPane::GetForCurrentView()订阅Showing/Hiding事件即可获知键盘显隐，注意在页面退出时退订；
• 编程控制兜底：TryShow()/TryHide()让应用在需要时主动收起或唤起键盘，是处理"键盘遮挡内容""提交后收起输入法"等交互的推荐手段；
• 运行前提：Windows 10 + Visual Studio，C++ 版本对应 SDK 版本要求见 Package.appxmanifest。

如需在自有 UWP 项目中复现，可直接参考本仓库 archived/TouchKeyboard/cpp 目录下的三组 XAML/代码文件，它们是理解Windows.UI.ViewManagement.InputPane体系最简练的入门范例。

• 示例工程