mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
docs(input): update docs to describe md-input-container rather than md-input (#2256)
* Update input docs and add note that md-input and md-sidenav-layout are deprecated. * style fix * use bold since github doesn't like color
This commit is contained in:
mmalerba
+154
-126
@@ -1,155 +1,183 @@
|
||||
# mdInput / mdTextarea
|
||||
**NOTE: The <code>md-input</code> element is deprecated. <code>md-input-container</code> should be
|
||||
used instead.**
|
||||
|
||||
Inputs are the basic input component of Material 2. The spec can be found [here](https://www.google.com/design/spec/components/text-fields.html).
|
||||
# md-input-container
|
||||
|
||||
Inputs are the basic input component of Material 2. The spec can be found
|
||||
[here](https://www.google.com/design/spec/components/text-fields.html). `md-input-container` acts as
|
||||
a wrapper for native `input` and `textarea` elements. The native element wrapped by the
|
||||
`md-input-container` must be marked with the `md-input` directive.
|
||||
|
||||
|
||||
## Notes
|
||||
* The `<md-input>` / `<md-textarea>` component fully support two-way binding of `ngModel`, as if it was a normal `<input>` and `<textarea>`.
|
||||
|
||||
|
||||
|
||||
## Type
|
||||
|
||||
At the time of writing this README, the `[type]` attribute is copied to the actual `<input>` element in the `<md-input>`.
|
||||
|
||||
The valid `type` attribute values are any supported by your browser, with the exception of `file`, `checkbox` and `radio`. File inputs aren't supported for now, while check boxes and radio buttons have their own components.
|
||||
|
||||
|
||||
## Placeholder
|
||||
|
||||
A placeholder is an indicative text displayed in the input zone when the input does not contain text. When text is present, the indicative text will float above this input zone.
|
||||
|
||||
You can set the `floatingPlaceholder` attribute to `false` to hide the indicative text instead when text is present in the input.
|
||||
|
||||
You can specify a placeholder for the input in one of two ways; either using the `placeholder` attribute, or using an `<md-placeholder>` directive in the `<md-input>`. Using both will raise an error.
|
||||
|
||||
|
||||
## Prefix and Suffix
|
||||
|
||||
You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as per the Material specification, and clicking it will focus the input.
|
||||
|
||||
To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the `md-suffix` attribute. For example, in a template:
|
||||
|
||||
#### Example
|
||||
|
||||
Simple `input` example:
|
||||
```html
|
||||
<md-input placeholder="amount" align="end">
|
||||
<span md-prefix>$ </span>
|
||||
<span md-suffix>.00</span>
|
||||
</md-input>
|
||||
<md-input-container>
|
||||
<input md-input>
|
||||
</md-input-container>
|
||||
```
|
||||
|
||||
Will result in this:
|
||||
Simple `textarea` example:
|
||||
```html
|
||||
<md-input-container>
|
||||
<textarea md-input></textarea>
|
||||
</md-input-container>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### `input` and `textarea` attributes
|
||||
|
||||
All of the attributes that can be used with normal `input` and `textarea` elements can be used on
|
||||
elements within the `md-input-container` as well. This includes angular specific ones such as
|
||||
`ngModel` and `formControl`.
|
||||
|
||||
The only limitations are that the `type` attribute can only be one of the values supported by
|
||||
`md-input-container` and the native element cannot specify a `placeholder` attribute if the
|
||||
`md-input-container` also contains a `md-placeholder` element.
|
||||
|
||||
#### Supported `input` types
|
||||
|
||||
The following [input types](http://www.w3schools.com/TAGs/att_input_type.asp) can be used with
|
||||
`md-input-container`:
|
||||
* date
|
||||
* datetime-local
|
||||
* email
|
||||
* month
|
||||
* number
|
||||
* password
|
||||
* search
|
||||
* tel
|
||||
* text
|
||||
* time
|
||||
* url
|
||||
* week
|
||||
|
||||
### Placeholder
|
||||
|
||||
A placeholder is an indicative text displayed in the input zone when the input does not contain
|
||||
text. When text is present, the indicative text will float above this input zone.
|
||||
|
||||
You can set the `floatingPlaceholder` attribute of `md-input-container` to `false` to hide the
|
||||
indicative text instead when text is present in the input.
|
||||
|
||||
You can specify a placeholder for the input in one of two ways; either using the `placeholder`
|
||||
attribute on the `input` or `textarea`, or using an `md-placeholder` element in the
|
||||
`md-input-container`. Using both will raise an error.
|
||||
|
||||
### Prefix and Suffix
|
||||
|
||||
You can include HTML before, and after the input tag, as prefix or suffix. It will be underlined as
|
||||
per the Material specification, and clicking it will focus the input.
|
||||
|
||||
To add a prefix, use the `md-prefix` attribute on the element. Similarly, to add a suffix, use the
|
||||
`md-suffix` attribute. For example, in a template:
|
||||
|
||||
```html
|
||||
<md-input-container align="end">
|
||||
<input md-input placeholder="amount">
|
||||
<span md-prefix>$ </span>
|
||||
<span md-suffix>.00</span>
|
||||
</md-input-container>
|
||||
```
|
||||
|
||||
<img src="https://material.angularjs.org/material2_assets/input/prefix-suffix.png">
|
||||
|
||||
### Hint Labels
|
||||
|
||||
Hint labels are the labels that show below the underline. You can have up to two hint labels; one on
|
||||
the `start` of the line (left in an LTR language, right in RTL), and one on the `end`.
|
||||
|
||||
## Hint Labels
|
||||
|
||||
Hint labels are the labels that shows the underline. You can have up to two hint labels; one on the `start` of the line (left in an LTR language, right in RTL), or one on the `end`.
|
||||
|
||||
You specify a hint-label in one of two ways; either using the `hintLabel` attribute, or using an `<md-hint>` directive in the `<md-input>`, which takes an `align` attribute containing the side. The attribute version is assumed to be at the `start`.
|
||||
|
||||
You specify a hint label in one of two ways; either using the `hintLabel` attribute of
|
||||
`md-input-container`, or using an `md-hint` element inside the `md-input-container`, which takes an
|
||||
`align` attribute containing the side. The attribute version is assumed to be at the `start`.
|
||||
Specifying a side twice will result in an exception during initialization.
|
||||
|
||||
#### Example
|
||||
|
||||
A simple character counter can be made like the following:
|
||||
|
||||
For example, a simple character counter can be made like the following:
|
||||
```html
|
||||
<md-input placeholder="Character count (100 max)" maxlength="100" class="demo-full-width"
|
||||
value="Hello world. How are you?"
|
||||
#characterCountHintExample>
|
||||
<md-hint align="end">{{characterCountHintExample.characterCount}} / 100</md-hint>
|
||||
</md-input>
|
||||
<md-input-container>
|
||||
<input md-input
|
||||
placeholder="Character count (100 max)"
|
||||
maxlength="100"
|
||||
value="Hello world. How are you?"
|
||||
#characterCountHintExample>
|
||||
<md-hint align="end">{{characterCountHintExample.value.length}} / 100</md-hint>
|
||||
</md-input-container>
|
||||
```
|
||||
|
||||
<img src="https://material.angularjs.org/material2_assets/input/character-count.png">
|
||||
|
||||
### Divider Color
|
||||
|
||||
The divider (line under the `input` content) color can be changed by using the `dividerColor`
|
||||
attribute of `md-input-container`. A value of `primary` is the default and will correspond to your
|
||||
theme primary color. Alternatively, you can specify `accent` or `warn`.
|
||||
|
||||
## Divider Color
|
||||
|
||||
The divider (line under the `<md-input>` content) color can be changed by using the `dividerColor` attribute. A value of `primary` is the default and will correspond to your theme primary color. Alternatively, you can specify `accent` or `warn`.
|
||||
|
||||
#### Example
|
||||
|
||||
^((please note that this example has been doctored to show the colors; they would normally show only on focus)^)
|
||||
```html
|
||||
<md-input-container>
|
||||
<input md-input placeholder="Default color" value="example">
|
||||
</md-input-container>
|
||||
<md-input-container dividerColor="accent">
|
||||
<input md-input placeholder="Accent color" value="example">
|
||||
</md-input-container>
|
||||
<md-input-container dividerColor="warn">
|
||||
<input md-input placeholder="Warn color" value="example">
|
||||
</md-input-container>
|
||||
```
|
||||
|
||||
_please note that this image has been doctored to show each `input` as if it were focused:_
|
||||
<img src="https://material.angularjs.org/material2_assets/input/divider-colors.png">
|
||||
|
||||
### Full Forms
|
||||
|
||||
|
||||
## Labelling
|
||||
|
||||
You can label the `<md-input>` as you would a regular `<input>`.
|
||||
|
||||
## Focus
|
||||
|
||||
You can put the focus on an input component using the `focus()` method.
|
||||
|
||||
### Example
|
||||
You can make a full form using inputs, and they will support autofill natively.
|
||||
|
||||
```html
|
||||
<md-input #nameInput placeholder="name"></md-input>
|
||||
<form>
|
||||
<md-input-container style="width: 100%">
|
||||
<input md-input placeholder="Company (disabled)" disabled value="Google">
|
||||
</md-input-container>
|
||||
|
||||
<table style="width: 100%" cellspacing="0"><tr>
|
||||
<td><md-input-container style="width: 100%">
|
||||
<input md-input placeholder="First name">
|
||||
</md-input-container></td>
|
||||
<td><md-input-container style="width: 100%">
|
||||
<input md-input placeholder="Long Last Name That Will Be Truncated">
|
||||
</md-input-container></td>
|
||||
</tr></table>
|
||||
|
||||
<p>
|
||||
<md-input-container width="100%">
|
||||
<textarea md-input placeholder="Address" value="1600 Amphitheatre Pkway"></textarea>
|
||||
</md-input-container>
|
||||
<md-input-container width="100%">
|
||||
<textarea md-input placeholder="Address 2"></textarea>
|
||||
</md-input-container>
|
||||
</p>
|
||||
|
||||
<table style="width: 100%" cellspacing="0"><tr>
|
||||
<td><md-input-container width="100%">
|
||||
<input md-input placeholder="City">
|
||||
</md-input-container></td>
|
||||
<td><md-input-container width="100%">
|
||||
<input md-input placeholder="State">
|
||||
</md-input-container></td>
|
||||
<td><md-input-container width="100%">
|
||||
<input md-input #postalCode maxlength="5" placeholder="Postal Code" value="94043">
|
||||
<md-hint align="end">{{postalCode.value.length}} / 5</md-hint>
|
||||
</md-input-container></td>
|
||||
</tr></table>
|
||||
</form>
|
||||
```
|
||||
|
||||
```ts
|
||||
export class MyComponent implements AfterViewInit {
|
||||
@ViewChild('nameInput') nameInput: MdInput;
|
||||
|
||||
ngAfterViewInit() {
|
||||
this.nameInput.focus();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Textareas
|
||||
|
||||
```html
|
||||
<md-textarea placeholder="Textarea with autosize"></md-textarea>
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
## Full Forms
|
||||
|
||||
You can make a full form using inputs, and it will support autofill natively.
|
||||
|
||||
#### Example
|
||||
|
||||
```html
|
||||
<md-card class="demo-card demo-basic">
|
||||
<md-toolbar color="primary">Basic</md-toolbar>
|
||||
<md-card-content>
|
||||
<form>
|
||||
<md-input class="demo-full-width" placeholder="Company (disabled)" disabled value="Google">
|
||||
</md-input>
|
||||
|
||||
<table style="width: 100%" cellspacing="0"><tr>
|
||||
<td><md-input placeholder="First name" style="width: 100%"></md-input></td>
|
||||
<td><md-input placeholder="Long Last Name That Will Be Truncated" style="width: 100%"></md-input></td>
|
||||
</tr></table>
|
||||
<p>
|
||||
<md-textarea class="demo-full-width" placeholder="Address" value="1600 Amphitheatre Pkway"></md-textarea>
|
||||
<md-textarea class="demo-full-width" placeholder="Address 2"></md-textarea>
|
||||
</p>
|
||||
<table style="width: 100%" cellspacing="0"><tr>
|
||||
<td><md-input class="demo-full-width" placeholder="City"></md-input></td>
|
||||
<td><md-input class="demo-full-width" placeholder="State"></md-input></td>
|
||||
<td><md-input #postalCode class="demo-full-width" maxlength="5"
|
||||
placeholder="Postal Code"
|
||||
value="94043">
|
||||
<md-hint align="end">{{postalCode.characterCount}} / 5</md-hint>
|
||||
</md-input></td>
|
||||
</tr></table>
|
||||
</form>
|
||||
</md-card-content>
|
||||
</md-card>
|
||||
```
|
||||
|
||||
Will result in this:
|
||||
|
||||
<img src="https://material.angularjs.org/material2_assets/input/full-form.png">
|
||||
|
||||
## API Summary
|
||||
|
||||
### Inputs
|
||||
|
||||
| Name | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `align` | `"start" | "end"` | The alignment of the `input` or `textarea`. Default = `"start"`. |
|
||||
| `dividerColor` | `"primary" | "accent" | "warn"` | The color of the placeholder and underline. Default = `"primary"`. |
|
||||
| `floatingPlaceholder` | boolean | Whether the placeholder should float above the input after text is entered. Default = `true`. |
|
||||
| `hintLabel` | string | The hint text to show on the start end of the `md-input-container`. |
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
**NOTE: The <code>md-sidenav-layout</code> element is deprecated. <code>md-sidenav-container</code>
|
||||
should be used instead.**
|
||||
|
||||
|
||||
# MdSidenav
|
||||
|
||||
MdSidenav is the side navigation component for Material 2. It is composed of two components: `<md-sidenav-container>` and `<md-sidenav>`.
|
||||
|
||||
@@ -132,7 +132,7 @@ right-to-left languages.
|
||||
| `max` | number | Optional, the maximum number for the slider. Default = `100`. |
|
||||
| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. |
|
||||
| `value` | number | Optional, the value to start the slider at. |
|
||||
| `tick-interval` | `"auto" | number` | Optional, how many steps between tick marks. |
|
||||
| `tick-interval` | `"auto"` \| number | Optional, how many steps between tick marks. |
|
||||
| `invert` | boolean | Optional, whether to invert the axis the thumb moves along. |
|
||||
| `vertical` | boolean | Optional, whether the slider should be oriented vertically. |
|
||||
| `disabled` | boolean | Optional, whether or not the slider is disabled. Default = `false`. |
|
||||
|
||||
Reference in New Issue
Block a user