mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
docs: initial overview docs for button - dialog (#2290)
* docs: initial overview docs for button - dialog * Corrections from proofreading * Fix improper plural
This commit is contained in:
Jeremy Elbourn
@@ -0,0 +1,22 @@
|
||||
Button-toggles are on/off toggles with the appearance of a button. These toggles can be configured
|
||||
to behave as either radio-buttons or checkboxes. While they can be standalone, they are typically
|
||||
part of a `md-button-toggle-group`.
|
||||
|
||||
|
||||
<!-- example(button-toggle-overview) -->
|
||||
|
||||
### Exclusive selection vs. multiple selection
|
||||
By default, `md-button-toggle-group` acts like a radio-button group- only one item can be selected.
|
||||
In this mode, the `value` of the `md-button-toggle-group` will reflect the value of the selected
|
||||
button and `ngModel` is supported.
|
||||
|
||||
Adding the `multiple` attribute allows multiple items to be selected (checkbox behavior). In this
|
||||
mode the values of the the toggles are not used, the `md-button-toggle-group` does not have a value,
|
||||
and `ngModel` is not supported.
|
||||
|
||||
### Accessibility
|
||||
The button-toggles will present themselves as either checkboxes or radio-buttons based on the
|
||||
presence of the `multiple` attribute.
|
||||
|
||||
### Orientation
|
||||
The button-toggles can be rendered in a vertical orientation by adding the `vertical` attribute.
|
||||
@@ -0,0 +1,25 @@
|
||||
Angular Material buttons are native `<button>` or `<a>` elements enhanced with Material Design
|
||||
styling and ink ripples.
|
||||
|
||||
<!-- example(button-overview) -->
|
||||
|
||||
Native `<button>` and `<a>` elements are always used in order to provide the most straightforward
|
||||
and accessible experience for users. A `<button>` element should be used whenever some _action_
|
||||
is performed. An `<a>` element should be used whenever the user will _navigate_ to another view.
|
||||
|
||||
|
||||
There are five button variants, each applied as an attribute:
|
||||
|
||||
| Attribute | Description |
|
||||
|--------------------|-----------------------------------------------------------------------------|
|
||||
| `md-button` | Rectangular button w/ no elevation. |
|
||||
| `md-raised-button` | Rectangular button w/ elevation |
|
||||
| `md-icon-button` | Circular button with a transparent background, meant to contain an icon |
|
||||
| `md-fab` | Circular button w/ elevation, defaults to theme's accent color |
|
||||
| `md-mini-fab` | Same as `md-fab` but smaller |
|
||||
|
||||
|
||||
### Theming
|
||||
Buttons can be colored in terms of the current theme using the `color` property to set the
|
||||
background color to `primary`, `accent`, or `warn`. By default, only FABs are colored; the default
|
||||
background color for `md-button` and `md-raised-button` matches the theme's background color.
|
||||
@@ -0,0 +1,45 @@
|
||||
Cards are content containers for text, photos, and actions. Cards are intended to provide
|
||||
information on a single subject.
|
||||
|
||||
<!-- example(card-overview) -->
|
||||
|
||||
|
||||
### Basic card sections
|
||||
The most basic card needs only an `<md-card>` element with some content. However, Angular Material
|
||||
provides a number of preset sections that you can use inside of an `<md-card>`:
|
||||
|
||||
|
||||
| Element | Description |
|
||||
|-----------------------|--------------------------------------------------------------------------|
|
||||
| `<md-card-title>` | Card title |
|
||||
| `<md-card-subtitle>` | Card subtitle |
|
||||
| `<md-card-content>` | Primary card content. Intended for blocks of text |
|
||||
| `<img md-card-image>` | Card image. Stretches the image to the container width |
|
||||
| `<md-card-actions>` | Container for buttons at the bottom of the card |
|
||||
| `<md-card-footer>` | Section anchored to the bottom of the card |
|
||||
|
||||
These elements primary serve as pre-styled content containers without any additional APIs.
|
||||
However, the `align` property on `<md-card-actions>` can be used to position the actions at the
|
||||
`'start'` or `'end` of the container.
|
||||
|
||||
|
||||
### Card headers
|
||||
In addition to the aforementioned sections, `<md-card-header>` gives the ability to add a rich
|
||||
header to a card. This header can contain:
|
||||
|
||||
| Element | Description |
|
||||
|------------------------|-------------------------------------------------------------------------|
|
||||
| `<md-card-title>` | A title within the header |
|
||||
| `<md-card-subtitle>` | A subtitle within the header |
|
||||
| `<img md-card-avatar>` | An image used as an avatar within the header |
|
||||
|
||||
|
||||
### Title groups
|
||||
An `<md-title-group>` can be used to combine a title, subtitle, and image into a single section.
|
||||
This element can contain:
|
||||
* `<md-card-title>`
|
||||
* `<md-card-subtite>`
|
||||
* One of:
|
||||
* `<img md-card-sm-image>`
|
||||
* `<img md-card-md-image>`
|
||||
* `<img md-card-lg-image>`
|
||||
@@ -0,0 +1,28 @@
|
||||
`<md-checkbox>` provides the same functionality as a native `<input type="checkbox">`
|
||||
enhanced Material Design styling and animations.
|
||||
|
||||
<!-- example(checkbox-overview) -->
|
||||
|
||||
### Checkbox label
|
||||
The checkbox label is provided as the content to the `<md-checkbox>` element. The label can be
|
||||
positioned before or after the checkbox by setting the `labelPosition` property to `'before'` or
|
||||
`'after'`.
|
||||
|
||||
If you don't want the label to appear next to the checkbox, you can use
|
||||
[`aria-label`](https://www.w3.org/TR/wai-aria/states_and_properties#aria-label) or
|
||||
[`aria-labelledby`](https://www.w3.org/TR/wai-aria/states_and_properties#aria-labelledby) to
|
||||
specify an appropriate label.
|
||||
|
||||
### Use with `@angular/forms`
|
||||
`<md-checkobx>` is compatible with `@angular/forms` and supports both `FormsModule`
|
||||
and `ReactiveFormsModule`.
|
||||
|
||||
### Indeterminate state
|
||||
`<md-checkbox>` supports an `indeterminate` state, similar to the native `<input type="checkbox">`.
|
||||
While the `indeterminate` property of the checkbox is true, it will render as indeterminate
|
||||
regardless of the `checked` value. Any interaction with the checkbox by a user (i.e., clicking) will
|
||||
remove the indeterminate state.
|
||||
|
||||
### Theming
|
||||
The color of a `<md-checkbox>` can be changed by using the `color` property. By default, checkboxes
|
||||
use the theme's accent color. This can be changed to `'primary'` or `'warn'`.
|
||||
@@ -0,0 +1,39 @@
|
||||
The `MdDialog` service can be used to open modal dialogs with Material Design styling and
|
||||
animations.
|
||||
|
||||
<!-- example(dialog-overview) -->
|
||||
|
||||
A dialog is opened by calling the `open` method with a component to be loaded and an optional
|
||||
config object. The `open` method will return an instance of `MdDialogRef`:
|
||||
|
||||
```ts
|
||||
let dialogRef = dialog.open(UserProfileComponent, {
|
||||
height: '400px',
|
||||
width: '600px',
|
||||
});
|
||||
```
|
||||
|
||||
The `MdDialogRef` provides a handle on the opened dialog. It can be used to close the dialog and to
|
||||
recieve notification when the dialog has been closed.
|
||||
```ts
|
||||
dialogRef.afterClosed.then(result => {
|
||||
console.log(`Dialog result: ${result}`); // Pizza!
|
||||
});
|
||||
|
||||
dialogRef.close('Pizza!');
|
||||
|
||||
```
|
||||
|
||||
Components created via `MdDialog` can _inject_ `MdDialogRef` and use it to close the dialog
|
||||
in which they are contained. When closing, an optional result value can be provided. This result
|
||||
value is forwarded as the result of the `afterClosed` promise.
|
||||
|
||||
### Dialog content
|
||||
Several directives are available to make it easier to structure your dialog content:
|
||||
|
||||
| Name | Description |
|
||||
|-----------------------|--------------------------------------------------------------------------|
|
||||
| `md-dialog-title` | \[Attr] Dialog title, applied to a heading element (e.g., `<h1>`, `<h2>`)|
|
||||
| `<md-dialog-content>` | Primary scrollable content of the dialog |
|
||||
| `<md-dialog-actions>` | Container for action buttons at the bottom of the dialog |
|
||||
| `md-dialog-close` | \[Attr] Added to a `<button>`, makes the button close the dialog on click|
|
||||
@@ -8,7 +8,6 @@ MdDialog is a service, which opens dialogs components in the view.
|
||||
| ---- | ----------- |
|
||||
| `open(component: ComponentType<T>, config: MdDialogConfig): MdDialogRef<T>` | Creates and opens a dialog matching material spec. |
|
||||
| `closeAll(): void` | Closes all of the dialogs that are currently open. |
|
||||
| `closeTop(): void` | Closes the topmost of the open dialogs. |
|
||||
|
||||
### Config
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ import {MdSnackBarContainer} from './snack-bar-container';
|
||||
|
||||
// TODO(josephperrott): Implement onAction observable.
|
||||
|
||||
|
||||
Observable.of([]);
|
||||
/**
|
||||
* Reference to a snack bar dispatched from the snack bar service.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user