ion-action-sheet

操作表是一个显示一组选项的对话框。它会出现在应用内容的顶部，并且用户必须手动关闭它，才能继续与应用互动。破坏性选项在 ios 模式下显而易见。关闭操作表有多种方式，包括点击背景或在桌面上按下 Esc 键。

🌐 An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in ios mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop.

内联操作表（推荐）

🌐 Inline Action Sheets (Recommended)

ion-action-sheet 可以通过直接在你的模板中编写组件来使用。这减少了你为展示操作表需要连接的处理程序数量。

使用 `isOpen`

🌐 Using isOpen

ion-action-sheet 上的 isOpen 属性允许开发者从其应用状态控制操作表的渲染状态。这意味着当 isOpen 设置为 true 时，操作表将被渲染，而当 isOpen 设置为 false 时，操作表将被关闭。

🌐 The isOpen property on ion-action-sheet allows developers to control the presentation state of the Action Sheet from their application state. This means when isOpen is set to true the Action Sheet will be presented, and when isOpen is set to false the Action Sheet will be dismissed.

isOpen 使用单向数据绑定，这意味着在操作表被解除时，它不会自动设置为 false。开发者应当监听 ionActionSheetDidDismiss 或 didDismiss 事件，并将 isOpen 设置为 false。这样做的原因是为了防止 ion-action-sheet 的内部实现与应用的状态紧密耦合。使用单向数据绑定时，操作表只需要关心响应式变量提供的布尔值。使用双向数据绑定时，操作表需要同时关心布尔值及响应式变量本身的存在。这可能导致非确定性行为，使应用更难调试。

控制器操作表

🌐 Controller Action Sheets

actionSheetController 可用于需要更好控制操作表何时渲染和关闭的情况。

🌐 The actionSheetController can be used in situations where more control is needed over when the Action Sheet is presented and dismissed.

按钮

🌐 Buttons

按钮的 role 属性可以是 destructive 或 cancel。没有角色属性的按钮将具有平台的默认外观。具有 cancel 角色的按钮无论在数组中的位置如何，都将始终作为底部按钮加载。所有其他按钮将按添加到 buttons 数组中的顺序显示。注意：我们建议 destructive 按钮总是数组中的第一个按钮，使其成为顶部按钮。此外，如果通过点击背景来关闭操作表，则会触发具有取消角色的按钮的处理程序。

🌐 A button's role property can either be destructive or cancel. Buttons without a role property will have the default look for the platform. Buttons with the cancel role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the buttons array. Note: We recommend that destructive buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role.

按钮也可以通过 ActionSheetButton 上的 data 属性传递数据。这将填充 onDidDismiss 方法返回值中的 data 字段。

🌐 A button can also be passed data via the data property on ActionSheetButton. This will populate the data field in the return value of the onDidDismiss method.

收集退出时的角色信息

🌐 Collecting Role Information on Dismiss

当 didDismiss 事件被触发时，可以使用事件详情中的 data 和 role 字段来收集有关操作表如何被关闭的信息。

🌐 When the didDismiss event is fired, the data and role fields of the event detail can be used to gather information about how the Action Sheet was dismissed.

Console

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

主题化

🌐 Theming

Action Sheet 使用了作用域封装，这意味着它会在运行时通过在每个样式后附加一个额外的类来自动限定其 CSS。在 CSS 中覆盖作用域选择器需要一个更高特异性的选择器。

🌐 Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector.

样式

🌐 Styling

我们建议在 create 方法中将自定义类传递给 cssClass，并使用它为宿主和内部元素添加自定义样式。该属性也可以接受用空格分隔的多个类。

🌐 We recommend passing a custom class to cssClass in the create method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces.

/* DOES NOT WORK - not specific enough */
.action-sheet-group {
  background: #e5e5e5;
}

/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .action-sheet-group {
  background: #e5e5e5;
}

CSS 自定义属性

🌐 CSS Custom Properties

可以使用任何已定义的 CSS 自定义属性来为操作表样式，而无需针对单个元素进行设置。

🌐 Any of the defined CSS Custom Properties can be used to style the Action Sheet without needing to target individual elements.

无障碍

🌐 Accessibility

屏幕阅读器

🌐 Screen Readers

操作表设置了 aria 属性，以便对屏幕阅读器可访问，但如果这些属性描述性不足或与操作表在应用中的使用方式不一致，则可以被覆盖。

🌐 Action Sheets set aria properties in order to be accessible to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app.

角色

🌐 Role

操作表被赋予一个 dialog 的 role。为了与 ARIA 规范保持一致，必须设置 aria-label 或 aria-labelledby 属性。

🌐 Action Sheets are given a role of dialog. In order to align with the ARIA spec, either the aria-label or aria-labelledby attribute must be set.

动作表说明

🌐 Action Sheet Description

强烈建议每个操作表都定义 header 属性，因为 Ionic 会自动将 aria-labelledby 设置为指向头部元素。然而，如果你选择不包含 header，一个替代方法是使用 htmlAttributes 属性提供一个描述性的 aria-label 或设置一个自定义的 aria-labelledby 值。

🌐 It is strongly recommended that every Action Sheet have the header property defined, as Ionic will automatically set aria-labelledby to point to the header element. However, if you choose not to include a header, an alternative is to use the htmlAttributes property to provide a descriptive aria-label or set a custom aria-labelledby value.

Angular
Javascript
React
Vue

const actionSheet = await this.actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

const actionSheet = await this.actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

useIonActionSheet({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

const actionSheet = await actionSheetController.create({
  htmlAttributes: {
    'aria-label': 'action sheet dialog',
  },
});

操作表按钮说明

🌐 Action Sheet Buttons Description

包含文本的按钮将被屏幕阅读器读取。如果按钮仅包含图标，或者希望提供与现有文本不同的描述，应通过将 aria-label 传递给按钮的 htmlAttributes 属性来为按钮分配标签。

🌐 Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing aria-label to the htmlAttributes property on the button.

Angular
Javascript
React
Vue

const actionSheet = await this.actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const actionSheet = await this.actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

useIonActionSheet({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const actionSheet = await actionSheetController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

接口

🌐 Interfaces

ActionSheetButton

interface ActionSheetButton<T = any> {
  text?: string;
  role?: 'cancel' | 'destructive' | 'selected' | string;
  icon?: string;
  cssClass?: string | string[];
  id?: string;
  htmlAttributes?: { [key: string]: any };
  handler?: () => boolean | void | Promise<boolean | void>;
  data?: T;
}

ActionSheetOptions

interface ActionSheetOptions {
  header?: string;
  subHeader?: string;
  cssClass?: string | string[];
  buttons: (ActionSheetButton | string)[];
  backdropDismiss?: boolean;
  translucent?: boolean;
  animated?: boolean;
  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;
  htmlAttributes?: { [key: string]: any };

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

属性

🌐 Properties

animated

Description	If `true`, the action sheet will animate.
Attribute	`animated`
Type	`boolean`
Default	`true`

backdropDismiss

Description	If `true`, the action sheet will be dismissed when the backdrop is clicked.
Attribute	`backdrop-dismiss`
Type	`boolean`
Default	`true`

buttons

Description	An array of buttons for the action sheet.
Attribute	`undefined`
Type	`(string ｜ ActionSheetButton<any>)[]`
Default	`[]`

cssClass

Description	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attribute	`css-class`
Type	`string ｜ string[] ｜ undefined`
Default	`undefined`

enterAnimation

Description	Animation to use when the action sheet is presented.
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

Description	Title for the action sheet.
Attribute	`header`
Type	`string ｜ undefined`
Default	`undefined`

htmlAttributes

Description	Additional attributes to pass to the action sheet.
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

isOpen

Description	If `true`, the action sheet will open. If `false`, the action sheet will close. Use this if you need finer grained control over presentation, otherwise just use the actionSheetController or the `trigger` property. Note: `isOpen` will not automatically be set back to `false` when the action sheet dismisses. You will need to do that in your code.
Attribute	`is-open`
Type	`boolean`
Default	`false`

keyboardClose

Description	If `true`, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	`keyboard-close`
Type	`boolean`
Default	`true`

leaveAnimation

Description	Animation to use when the action sheet is dismissed.
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ 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`

subHeader

Description	Subtitle for the action sheet.
Attribute	`sub-header`
Type	`string ｜ undefined`
Default	`undefined`

translucent

Description	If `true`, the action sheet will be translucent. Only applies when the mode is `"ios"` and the device supports `backdrop-filter`.
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	An ID corresponding to the trigger element that causes the action sheet to open when clicked.
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

事件

🌐 Events

Name	Description	Bubbles
`didDismiss`	Emitted after the action sheet has dismissed. Shorthand for ionActionSheetDidDismiss.	`true`
`didPresent`	Emitted after the action sheet has presented. Shorthand for ionActionSheetWillDismiss.	`true`
`ionActionSheetDidDismiss`	Emitted after the action sheet has dismissed.	`true`
`ionActionSheetDidPresent`	Emitted after the action sheet has presented.	`true`
`ionActionSheetWillDismiss`	Emitted before the action sheet has dismissed.	`true`
`ionActionSheetWillPresent`	Emitted before the action sheet has presented.	`true`
`willDismiss`	Emitted before the action sheet has dismissed. Shorthand for ionActionSheetWillDismiss.	`true`
`willPresent`	Emitted before the action sheet has presented. Shorthand for ionActionSheetWillPresent.	`true`

方法

🌐 Methods

dismiss

Description	Dismiss the action sheet overlay after it has been presented. This is a no-op if the overlay has not been presented yet. If you want to remove an overlay from the DOM that was never presented, use the remove method.
Signature	`dismiss(data?: any, role?: string) => Promise<boolean>`
Parameters	data: Any data to emit in the dismiss events. role: The role of the element that is dismissing the action sheet. This can be useful in a button handler for determining which button was clicked to dismiss the action sheet. Some examples include: `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.

onDidDismiss

Description	Returns a promise that resolves when the action sheet did dismiss.
Signature	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

Description	Returns a promise that resolves when the action sheet will dismiss.
Signature	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

Description	Present the action sheet overlay after it has been created.
Signature	`present() => Promise<void>`

CSS 阴影部分

🌐 CSS Shadow Parts

No CSS shadow parts available for this component.

CSS 自定义属性

🌐 CSS Custom Properties

Name	Description
`--backdrop-opacity`	Opacity of the backdrop
`--background`	Background of the action sheet group
`--button-background`	Background of the action sheet button
`--button-background-activated`	Background of the action sheet button when pressed. Note: setting this will interfere with the Material Design ripple.
`--button-background-activated-opacity`	Opacity of the action sheet button background when pressed
`--button-background-focused`	Background of the action sheet button when tabbed to
`--button-background-focused-opacity`	Opacity of the action sheet button background when tabbed to
`--button-background-hover`	Background of the action sheet button on hover
`--button-background-hover-opacity`	Opacity of the action sheet button background on hover
`--button-background-selected`	Background of the selected action sheet button
`--button-background-selected-opacity`	Opacity of the selected action sheet button background
`--button-color`	Color of the action sheet button
`--button-color-activated`	Color of the action sheet button when pressed
`--button-color-disabled`	Color of the selected action sheet button when disabled
`--button-color-focused`	Color of the action sheet button when tabbed to
`--button-color-hover`	Color of the action sheet button on hover
`--button-color-selected`	Color of the selected action sheet button
`--color`	Color of the action sheet text
`--height`	height of the action sheet
`--max-height`	Maximum height of the action sheet
`--max-width`	Maximum width of the action sheet
`--min-height`	Minimum height of the action sheet
`--min-width`	Minimum width of the action sheet
`--width`	Width of the action sheet

Name	Description
`--backdrop-opacity`	Opacity of the backdrop
`--background`	Background of the action sheet group
`--button-background`	Background of the action sheet button
`--button-background-activated`	Background of the action sheet button when pressed. Note: setting this will interfere with the Material Design ripple.
`--button-background-activated-opacity`	Opacity of the action sheet button background when pressed
`--button-background-focused`	Background of the action sheet button when tabbed to
`--button-background-focused-opacity`	Opacity of the action sheet button background when tabbed to
`--button-background-hover`	Background of the action sheet button on hover
`--button-background-hover-opacity`	Opacity of the action sheet button background on hover
`--button-background-selected`	Background of the selected action sheet button
`--button-background-selected-opacity`	Opacity of the selected action sheet button background
`--button-color`	Color of the action sheet button
`--button-color-activated`	Color of the action sheet button when pressed
`--button-color-disabled`	Color of the selected action sheet button when disabled
`--button-color-focused`	Color of the action sheet button when tabbed to
`--button-color-hover`	Color of the action sheet button on hover
`--button-color-selected`	Color of the selected action sheet button
`--color`	Color of the action sheet text
`--height`	height of the action sheet
`--max-height`	Maximum height of the action sheet
`--max-width`	Maximum width of the action sheet
`--min-height`	Minimum height of the action sheet
`--min-width`	Minimum width of the action sheet
`--width`	Width of the action sheet

插槽

🌐 Slots

No slots available for this component.

内联操作表（推荐）​

使用 isOpen​

控制器操作表​

按钮​

收集退出时的角色信息​

主题化​

样式​

CSS 自定义属性​

无障碍​

屏幕阅读器​

角色​

动作表说明​

操作表按钮说明​

接口​

ActionSheetButton​

ActionSheetOptions​

属性​

animated​

backdropDismiss​

buttons​

cssClass​

enterAnimation​

header​

htmlAttributes​

isOpen​

keyboardClose​

leaveAnimation​

mode​

subHeader​

translucent​

trigger​

事件​

方法​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录

内联操作表（推荐）

使用 `isOpen`

控制器操作表

按钮

收集退出时的角色信息

主题化

样式

CSS 自定义属性

无障碍

屏幕阅读器

角色

动作表说明

操作表按钮说明

接口

ActionSheetButton

ActionSheetOptions

属性

animated

backdropDismiss

buttons

cssClass

enterAnimation

header

htmlAttributes

isOpen

keyboardClose

leaveAnimation

mode

subHeader

translucent

trigger

事件

方法

dismiss

onDidDismiss

onWillDismiss

present

CSS 阴影部分

CSS 自定义属性

插槽