使用 Xamarin 中的 tvOS 按钮Working with tvOS Buttons in Xamarin

使用 UIButton 类的实例在 tvOS 窗口中创建可获得焦点的可选择按钮。Use an instance of the UIButton class to create a focusable, selectable button in a tvOS window. 当用户选择一个按钮时,它将向目标对象发送一个操作消息,以允许你的 tvOS 应用响应用户的输入。When the user selects a button, it sends an Action message to the target object allow your Xamarin.tvOS app respond to the user's input.

若要详细了解如何使用 Siri 遥控器并进行导航,请参阅使用导航和焦点Siri 远程和蓝牙控制器文档。For more information on working with Focus and navigating with the Siri Remote, please see our Working with Navigation and Focus and Siri Remote and Bluetooth Controllers documentation.

关于按钮About Buttons

在 tvOS 中,按钮用于特定于应用程序的操作,并且可能包含标题、图标或两者。In tvOS, Buttons are used for app-specific actions and may contain a title, a icon or both. 当用户使用Siri 远程浏览应用程序的用户界面时,焦点将移到给定按钮,使其更改文本和背景色。As the user navigates the app's User Interface using the Siri Remote, Focus shifts to the given Button making it change text and background colors. 阴影还适用于添加三维效果的按钮,使其看起来比用户界面的其余部分更高。A shadow is also applied to the Button adding a 3D effect making it appear to rise above the rest of the User Interface.

Apple 对于使用按钮有以下建议:Apple has the following suggestions for working with Buttons:

  • 使用 "标题" 或 "图标"-当按钮中同时包含一个图标和标题时,空间会受到限制,因此请不要将两者组合在一起。Use Either a Title or an Icon - While the both an icon and a title can be included in a Button, space is limited so try not to combine both.
  • 清晰标记破坏性按钮-如果按钮执行破坏性操作(如删除文件),请使用文本和/或图标清楚地将其标记为。Clearly Mark Destructive Buttons - If the Button performs a destructive action (such as deleting a file), clearly mark it as such using text and/or icon. 破坏性操作应始终向用户发出警报,要求用户限制该操作。Destructive actions should always present an Alert asking the user to confine the action.
  • 不要使用后退按钮-Siri 遥控器上的菜单按钮用于返回到上一屏幕。Don't Use Back Buttons - The Menu button on the Siri Remote is used to return to the previous screen. 此规则的例外情况是用于应用内购买或应显示 "取消" 按钮的破坏性操作。The one exception to this rule is for In-App Purchases or destructive actions where a Cancel button should be displayed.

有关使用焦点和导航的详细信息,请参阅使用导航和焦点文档。For more information on working with Focus and Navigation, please see our Working with Navigation and Focus documentation.

按钮图标Button Icons

Apple 建议你为按钮图标使用简单、高度可识别的图像。Apple suggests that you use simple, highly recognizable images for your Button icons. 很难在床上的房间内的电视屏幕上识别过于复杂的图标,因此,请尽可能使用最简单的表示形式。Overly complex icons are hard to recognize on a TV screen across the room on a couch, so try to use the simplest representation possible to get the idea across. 尽可能使用图标的标准、清楚的图像(如搜索的放大镜)。Whenever possible, use standard, well-know images for icons (such as a magnifying glass for search).

按钮标题Button Titles

创建按钮标题时,Apple 提供以下建议:Apple has the following suggestions when creating the titles for your Buttons:

  • 图标按钮下方显示描述性文本-如有可能,请将下面的描述性文本替换为仅图标按钮,以便进一步获取按钮的用途。Show Descriptive Text Below Icons Buttons - Where possible, place clear, descriptive text below icon only Buttons to further get the Button's purpose across.
  • 谓词或谓词短语用于标题-清楚地陈述当用户单击按钮时将发生的操作。Use Verbs or Verb Phrases for the Title - Clearly state the action that will take place when the user clicks the Button.
  • 使用 Title 样式大小写-除了文章、连词或介词(4个字母或更少)以外,按钮标题的每个单词都应大写。Use Title-Style Capitalization - With the exception of articles, conjunctions or prepositions (four letters or less), every word of the Button's title should be capitalized.
  • 使用简短的到点标题-使用最短的措辞来描述按钮的操作。Use a Short, To-The-Point Title - Use the shortest possible verbiage to describe the Button's action.

按钮和情节提要Buttons and Storyboards

若要在 tvOS 应用中使用按钮,最简单的方法是使用 Xamarin Designer for iOS 将它们添加到应用的 UI。The easiest way to work with buttons in a Xamarin.tvOS app is to add them to the app's UI using the Xamarin Designer for iOS.

  1. 解决方案资源管理器中,双击 Main.storyboard 文件,然后将其打开进行编辑。In the Solution Explorer, double-click the Main.storyboard file and open it for editing.

  2. 将一个按钮中拖放到视图上:Drag a Button from the Library and drop it on the View:

  3. 在 "属性资源管理器" 中,您可以调整按钮的几个属性,例如其标题文本颜色In the Properties Explorer, you can adjust several properties of the button such as its Title and Text Color:

  4. 接下来,切换到 "事件" 选项卡并将事件连接到按钮,并将其调用 ButtonPressedNext, switch to the Events Tab and wire-up an Event from the Button and call it ButtonPressed:

  5. 系统会自动切换到 "ViewController.cs" 视图,在该视图中,可以使用向上向下箭头键在代码中放置新操作:You will be automatically switched to the ViewController.cs view where you can place the new Action in your code using the Up and Down arrow keys:

  6. enter选择位置:Press the Enter to select the location:

  7. 保存对所有文件所做的更改。Save the changes to all files.

只要 true 按钮的 Enabled 属性,且该属性未被另一个控件或视图所覆盖,就可以使用 Siri Remote 使其成为焦点项。As long as a button's Enabled property is true and it is not covered by another control or view, it can be made the in-focus item using the Siri Remote. 如果用户选择该按钮并单击触摸面,则将执行上面定义的 ButtonPressed 操作。If the user selects the button and clicks the Touch Surface, the ButtonPressed action defined above would be executed.

重要

尽管可以在创建事件处理程序时在 IOS 设计器中将 TouchUpInside 分配到 UIButton,但永远不会调用该操作,因为 Apple TV 没有触摸屏或支持触控事件。While it is possible to assign actions such as TouchUpInside to a UIButton in the iOS Designer when creating an Event Handler, it will never be called because Apple TV doesn't have a touch screen or support touch events. 为 tvOS 用户界面元素创建操作时,应始终使用默认操作类型You should always use the default Action Type when creating Actions for tvOS user interface elements.

有关使用情节提要的详细信息,请参阅tvOS 快速入门指南For more information on working with Storyboards, please see our Hello, tvOS Quick Start Guide.

按钮和代码Buttons and Code

或者,可以在代码中创建 UIButton C# ,并将其添加到 tvOS 应用的视图中。Optionally, a UIButton can be created in C# code and added to the tvOS app's view. 例如:For example:

var button = new UIButton(UIButtonType.System);
button.Frame = new CGRect (25, 25, 300, 150);
button.SetTitle ("Hello", UIControlState.Normal);
button.AllEvents += (sender, e) => {
    // Do something when the button is clicked
    ...
};
View.AddSubview (button);

在代码中创建新的 UIButton 时,请将其 UIButtonType 指定为以下内容之一:When you create a new UIButton in code, you specify its UIButtonType as one of the following:

  • 系统-这是 tvOS 提供的标准类型按钮,是最常使用的类型。System - This is the standard type of button presented by tvOS and is the type that you will use most often.
  • DetailDisclosure -显示用于隐藏或显示详细信息的 "关闭" 按钮类型。DetailDisclosure - Presents a "turn down" type of button used to hide or show detailed information.
  • InfoDark -"深色详细信息" 按钮在圆圈中显示为 "i"。InfoDark - A dark detailed info button displayed an "i" in a circle.
  • InfoLight -在圆圈中显示一个 "i"。InfoLight - A light detailed info button displayed an "i" in a circle.
  • AddContact -将按钮显示为 "添加联系人" 按钮。AddContact - Display the button as an Add Contact button.
  • 自定义-允许你自定义按钮的多个特性。Custom - Allows you to customize several traits of the button.

接下来,定义按钮的屏幕大小和位置。Next, you define the on-screen size and location of the button. 示例:Example:

button.Frame = new CGRect (25, 25, 300, 150);

然后,设置按钮的标题。Then, set the title for the button. UIButtons 不同于大多数 UIKit 控件,因为它们具有状态,因此您不能只是更改标题,而必须针对给定的 UIControlState进行更改。UIButtons are different than most UIKit controls in that they have a State so you can't just simply change the title, you have to change it for a given UIControlState. 例如:For example:

button.SetTitle ("Hello", UIControlState.Normal);

接下来,使用 AllEvents 事件来查看用户单击了该按钮的时间。Next, use the AllEvents event to see when the user has clicked the button. 示例:Example:

button.AllEvents += (sender, e) => {
    // Do something when the button is clicked
    ...
};

最后,将该按钮添加到视图以显示该按钮:Finally, you add the button to the view to display it:

View.AddSubview (button);

重要

虽然可以将 TouchUpInside 操作(如)分配给 UIButton,但永远不会调用它,因为 Apple TV 没有触摸屏或支持触控事件。While it is possible to assign actions such as TouchUpInside to a UIButton, it will never be called because Apple TV doesn't have a touch screen or support touch events. 应始终使用AllEventsPrimaryActionTriggered等事件。You should always use events such as AllEvents or PrimaryActionTriggered.

设置按钮样式Styling a Button

tvOS 提供 UIButton 的多个属性,这些属性可用于提供其标题并使用背景色和图像之类的样式。tvOS provides several properties of a UIButton that can be used to provide its title and style it with things like background color and images.

按钮标题Button Titles

如前文所述,UIButtons 不同于大多数 UIKit 控件,因为它们具有状态,因此您不能只是更改标题,而是必须针对给定的 UIControlState进行更改。As we saw above, UIButtons are different than most UIKit controls in that they have a State so you can't just simply change the title, you have to change it for a given UIControlState. 例如:For example:

button.SetTitle ("Hello", UIControlState.Normal);

您可以使用 SetTitleColor 方法设置按钮的标题颜色。You can set the title color for the button using the SetTitleColor method. 例如:For example:

button.SetTitleColor (UIColor.White, UIControlState.Normal);

您可以使用 SetTitleShadowColor调整标题的阴影。And you can adjust the title's shadow using the SetTitleShadowColor. 例如:For example:

button.SetTitleShadowColor(UIColor.Black, UIControlState.Normal);

使用以下代码突出显示按钮时,可以将标题阴影设置为从文更改为浮凸You can set the title shadow to change from Engraved to Embossed when the button is highlighted using the following code:

button.ReverseTitleShadowWhenHighlighted = true;

此外,您还可以使用特性化文本作为按钮的标题。Additionally, you can use attributed text as the button's title. 例如:For example:

var normalAttributedTitle = new NSAttributedString (buttonTitle, foregroundColor: UIColor.Blue, strikethroughStyle: NSUnderlineStyle.Single);
myButton.SetAttributedTitle (normalAttributedTitle, UIControlState.Normal);

var highlightedAttributedTitle = new NSAttributedString (buttonTitle, foregroundColor: UIColor.Green, strikethroughStyle: NSUnderlineStyle.Thick);
myButton.SetAttributedTitle (highlightedAttributedTitle, UIControlState.Highlighted);

按钮图像Button Images

UIButton 可以附加一个图像,并可以使用图像作为其背景。A UIButton can have an image attached to it and can use an image as its background.

若要为给定 UIControlState设置按钮的背景图像,请使用以下代码:To set the background image of a button for a given UIControlState, use the following code:

button.SetBackgroundImage(UIImage.FromFile("my image.png"), UIControlState.Normal);

AdjustsImageWhenHiglighted 属性设置为 "true 可在按钮突出显示时将图像绘制为较浅(这是默认值)。Set the AdjustsImageWhenHiglighted property to true to draw the image lighter when the button is highlighted (this is the default). AdjustsImageWhenDisabled 属性设置为 "true 以便在按钮被禁用时将图像绘制为较暗(这是默认值)。Set the AdjustsImageWhenDisabled property to true to draw the image darker when the button is disabled (again, this is the default).

若要设置按钮上显示的图像,请使用以下代码:To set the image displayed on the button, use the following code:

button.SetImage(UIImage.FromFile("my image.png"), UIControlState.Normal);

使用 "TintColor" 属性可设置应用于标题和按钮图像的颜色色调。Use the TintColor property to set a color tint that is applied to both the title and the button's image. 对于 Custom 类型的按钮,此属性不起作用,你必须自行实现 TintColor 行为。For buttons of the Custom type, this property has no effect, you must implement the TintColor behavior yourself.

总结Summary

本文介绍了如何设计和使用 tvOS 应用程序中的按钮。This article has covered designing and working with buttons inside of a Xamarin.tvOS app. 它演示了如何使用 iOS 设计器中的按钮,以及如何在代码中C#创建按钮。It showed how to work with buttons in the iOS Designer and how to create buttons in C# code. 最后,它演示了如何修改按钮的标题,并更改其样式和外观。Finally, it showed how to modify a button's title and change its style and appearance.