ion-radio

shadow

单选按钮应在 单选按钮组 内部使用。点击一个单选按钮会选中它并取消选中之前选中的按钮（如果存在）。也可以通过编程方式选中，只需将父级单选按钮组的 value 属性设置为该单选按钮的值。

当单选按钮位于单选按钮组内时，任何时刻只能有一个被选中。如果需要同时选中多个项目，则应使用 复选框。可以对组内的单选按钮禁用，以防止用户与之交互。

基本用法

标签位置

开发者可以使用 labelPlacement 属性来控制标签相对于控件的位置。该属性与 flexbox 的 flex-direction 属性相对应。

标签换行

无论标签位置如何，默认情况下长文本不会自动换行。如果单选按钮的宽度受限，溢出的文本将被截断并以省略号显示。可以通过在包裹单选按钮文本的容器上添加 ion-text-wrap 类，或使用 ::part() 选择器对 label 阴影部件进行样式设置，来启用文本换行。

对象值引用

默认情况下，单选按钮组使用严格相等（===）来判断选项是否被选中。可以通过为 compareWith 属性提供属性名或函数来覆盖此行为。

Console

Console messages will appear here when logged from the example above.

对齐方式

开发者可以使用 alignment 属性来控制标签和控件在交叉轴上的对齐方式。该属性与 flexbox 的 align-items 属性相对应。

备注

堆叠排列的单选按钮可以使用 alignment 属性进行对齐。当标签和控件需要在水平方向上居中对齐时，这很有用。

布局方式

开发者可以使用 justify 属性来控制标签和控件在行内的排列方式。该属性与 flexbox 的 justify-content 属性相对应。

备注

ion-item 仅在演示中用于强调 justify 的工作原理。justify 正常工作并不需要 ion-item。

取消选中单选按钮

默认情况下，单选按钮一旦被选中就不能取消选中；再次点击它仍将保持选中状态。可以通过在父级单选按钮组上使用 allowEmptySelection 属性来修改此行为，该属性允许取消选中单选按钮。

主题定制

颜色

CSS 自定义属性

CSS 阴影部件

从旧版单选按钮语法迁移

Ionic 7.0 引入了一种更简洁的单选按钮语法。这种新语法减少了设置单选按钮所需的样板代码，解决了无障碍访问问题，并改善了开发者体验。

开发者可以逐个单选按钮进行迁移。虽然开发者可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

使用现代语法需要移除 ion-label 并将标签直接放在 ion-radio 内部。标签的位置可以通过 ion-radio 上的 labelPlacement 属性进行配置。标签和控件在行内的排列方式可以通过 ion-radio 上的 justify 属性来控制。

JavaScript

<!-- 基础用法 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label>单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio>单选标签</ion-radio>
</ion-item>

<!-- 固定标签 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label position="fixed">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio label-placement="fixed">单选标签</ion-radio>
</ion-item>

<!-- 单选框在行首，标签在行尾 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label slot="end">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio label-placement="end">单选标签</ion-radio>
</ion-item>

Angular

<!-- 基础用法 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label>单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio>单选标签</ion-radio>
</ion-item>

<!-- 固定标签 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label position="fixed">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio labelPlacement="fixed">单选标签</ion-radio>
</ion-item>

<!-- 单选框在行首，标签在行尾 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label slot="end">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio labelPlacement="end">单选标签</ion-radio>
</ion-item>

React

{/* 基础用法 */}

{/* 旧版写法 */}
<IonItem>
  <IonLabel>单选标签</IonLabel>
  <IonRadio></IonRadio>
</IonItem>

{/* 新版写法 */}
<IonItem>
  <IonRadio>单选标签</IonRadio>
</IonItem>

{/* 固定标签 */}

{/* 旧版写法 */}
<IonItem>
  <IonLabel position="fixed">单选标签</IonLabel>
  <IonRadio></IonRadio>
</IonItem>

{/* 新版写法 */}
<IonItem>
  <IonRadio labelPlacement="fixed">单选标签</IonRadio>
</IonItem>

{/* 单选框在行首，标签在行尾 */}

{/* 旧版写法 */}
<IonItem>
  <IonLabel slot="end">单选标签</IonLabel>
  <IonRadio></IonRadio>
</IonItem>

{/* 新版写法 */}
<IonItem>
  <IonRadio labelPlacement="end">单选标签</IonRadio>
</IonItem>

Vue

<!-- 基础用法 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label>单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio>单选标签</ion-radio>
</ion-item>

<!-- 固定标签 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label position="fixed">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio label-placement="fixed">单选标签</ion-radio>
</ion-item>

<!-- 单选框在行首，标签在行尾 -->

<!-- 旧版写法 -->
<ion-item>
  <ion-label slot="end">单选标签</ion-label>
  <ion-radio></ion-radio>
</ion-item>

<!-- 新版写法 -->
<ion-item>
  <ion-radio label-placement="end">单选标签</ion-radio>
</ion-item>

备注

在 Ionic 的旧版本中，ion-radio 需要配合 ion-item 才能正常工作。从 Ionic 7.0 开始，仅当 ion-item 放置在 ion-list 中时，才需要在其中使用 ion-radio。此外，ion-radio 正常工作不再需要 ion-item。

使用旧版语法

Ionic 使用启发式方法来检测应用是否在使用现代单选按钮语法。在某些情况下，可能更倾向于继续使用旧版语法。开发者可以将 ion-radio 上的 legacy 属性设置为 true，以强制该单选按钮实例使用旧版语法。

属性

alignment

Description	How to control the alignment of the radio and label on the cross axis. "start": The label and control will appear on the left of the cross axis in LTR, and on the right side in RTL. "center": The label and control will appear at the center of the cross axis in both LTR and RTL.
Attribute	alignment
Type	"center" ｜ "start"
Default	'center'

color

Description	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

disabled

Description	If true, the user cannot interact with the radio.
Attribute	disabled
Type	boolean
Default	false

justify

Description	How to pack the label and radio within a line. "start": The label and radio will appear on the left in LTR and on the right in RTL. "end": The label and radio will appear on the right in LTR and on the left in RTL. "space-between": The label and radio will appear on opposite ends of the line with space between the two elements.
Attribute	justify
Type	"end" ｜ "space-between" ｜ "start"
Default	'space-between'

labelPlacement

Description	Where to place the label relative to the radio. "start": The label will appear to the left of the radio in LTR and to the right in RTL. "end": The label will appear to the right of the radio in LTR and to the left in RTL. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). "stacked": The label will appear above the radio regardless of the direction. The alignment of the label can be controlled with the alignment property.
Attribute	label-placement
Type	"end" ｜ "fixed" ｜ "stacked" ｜ "start"
Default	'start'

legacy

Description	Set the legacy property to true to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the aria-label attribute or the default slot that contains the label text. As a result, the legacy property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
Attribute	legacy
Type	boolean ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

name

Description	The name of the control, which is submitted with the form data.
Attribute	name
Type	string
Default	this.inputId

value

Description	the value of the radio.
Attribute	value
Type	any
Default	undefined

事件

Name	Description	Bubbles
ionBlur	Emitted when the radio button loses focus.	true
ionFocus	Emitted when the radio button has focus.	true

方法

No public methods available for this component.

CSS 阴影部件

Name	Description
container	The container for the radio mark.
label	The label text describing the radio.
mark	The checkmark or dot used to indicate the checked state.

CSS 自定义属性

Name	Description
--border-radius	Border radius of the radio
--color	Color of the radio
--color-checked	Color of the checked radio
--inner-border-radius	Border radius of the inner checked radio

插槽

Name	Description
``	The label text to associate with the radio. Use the "labelPlacement" property to control where the label is placed relative to the radio.