android activity开发文档翻译 - 1 - 基础篇

由于本人英文能力实在有限，不足之初敬请谅解

本博客只要没有注明“转”，那么均为原创，转贴请注明本博客链接链接

 

android activity开发文档翻译 - 1 - 基础篇

android activity开发文档翻译 - 2 - 生命周期篇

 

本系列并没有对原文100%翻译，也没有100%的贴出原文

 

内容实在是基础的不能再基础，不做过多颜色标注。

 

Activities

Activity

An Activity is an application component that provides a screen with which users can interact in order to do something, such as dial the phone, take a photo, send an email, or view a map. 

Each activity is given a window in which to draw its user interface. 

The window typically fills the screen, but may be smaller than the screen and float on top of other windows.

activity是一个应用的组件，它提供一个用户可以与之交互按顺序做些什么的屏幕，例如拨打电话，照相，发送电子邮件或者浏览地图

每一个activity都会提供一个window来描绘ui

window往往填满屏幕，但是也许会比屏幕小一些并且悬浮在其他window之上。

 

 

An application usually consists of multiple activities that are loosely bound to each other. 

Typically, one activity in an application is specified as the "main" activity, which is presented to the user when launching the application for the first time. 

Each activity can then start another activity in order to perform different actions. 

Each time a new activity starts, the previous activity is stopped, but the system preserves the activity in a stack (the "back stack"). 

When a new activity starts, it is pushed onto the back stack and takes user focus. 

The back stack abides to the basic "last in, first out" stack mechanism, so, when the user is done with the current activity and presses the Back button, it is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is discussed more in the Tasks and Back Stack document.)

一个应用通常由多个结合不紧密的activity组成。

往往应用中当第一次启动应用时呈现给用户的activity被指定作为主activity  

每一次打开一个新activity，上一个activity就会stop，但是系统会在stack中保存这个activity。

当打开一个新的activity时，它被推到back stack中并且获得用户焦点

back stack遵守基本的“后进先出”stack原则，所以，当用户使用完当前的activity并且按back键，它就从stack中弹出（并且销毁）并且上一个activity重新开始。

 

 

When an activity is stopped because a new activity starts, it is notified of this change in state through the activity's lifecycle callback methods. 

There are several callback methods that an activity might receive, due to a change in its state—whether the system is creating it, stopping it, resuming it, or destroying it—and each callback provides you the opportunity to perform specific work that's appropriate to that state change. 

For instance, when stopped, your activity should release any large objects, such as network or database connections. 

When the activity resumes, you can reacquire the necessary resources and resume actions that were interrupted. 

These state transitions are all part of the activity lifecycle.

当一个activity停止时是因为一个新activity打开了，这种状态上变化是通过activity的生命周期回调函数通知的。

activity也许会收到几个回调函数的调用，取决于它自身状态的变化 - 系统是否要创建它、停止它、重新开始它或者销毁它 - 每个回调为你在那个状态变化的恰当的时机，提供机会来执行指定的工作。

例如：当activity停止时，你的activity应该释放大对象，比如网络或数据库连接。

当activity重新开始时，你可以再次搜取必要的资源并且重新开始被打断的动作。

这些状态的过渡均是activity生命周期的一部分。

 

 

The rest of this document discusses the basics of how to build and use an activity, including a complete discussion of how the activity lifecycle works, so you can properly manage the transition between various activity states.

文档的其余部分讨论基本的如何建立和使用一个activity，包括activity生命周期工作的完整讨论，所以你可以正确的处理多个activity状态间的过渡。

 

 

 

Creating an Activity

建立activity

To create an activity, you must create a subclass of Activity (or an existing subclass of it). 

In your subclass, you need to implement callback methods that the system calls when the activity transitions between various states of its lifecycle, such as when the activity is being created, stopped, resumed, or destroyed. 

The two most important callback methods are:

为了建立一个activity，你必须建立一个activity的子类（或者Activity存在的子类的子类）

在你的子类中，你需要实现当activity在多个生命周期的状态间转换时系统会调用的回调函数，比如当activity被建立、提供内置、重新开始、或者销毁。

最重要的两个回调函数是：

 

onCreate()

You must implement this method. 

The system calls this when creating your activity. 

Within your implementation, you should initialize the essential components of your activity. 

Most importantly, this is where you must call setContentView() to define the layout for the activity's user interface.

你必须实现这个函数。

系统当建立你的activity时候调用这个函数。

在你的实现中，你应该初始化你activity的必要组件。

最重要的，你必须在这调用setContentView()来为你的activity定义UI布局。

 

 

onPause()

The system calls this method as the first indication that the user is leaving your activity (though it does not always mean the activity is being destroyed). 

This is usually where you should commit any changes that should be persisted beyond the current user session (because the user might not come back).

系统作为第一个用户正在离开你的activity的指示调用这个方法（虽然这并不总是意味着activity正在被销毁）

你应该提交应该在当前用户会话中应该被保存的任何改变

 

 

There are several other lifecycle callback methods that you should use in order to provide a fluid user experience between activities and handle unexpected interuptions that cause your activity to be stopped and even destroyed. 

All of the lifecycle callback methods are discussed later, in the section about Managing the Activity Lifecycle.

在activity之间和处理导致你activity停止甚至被销毁的意外的中断间提供一个流畅的用户体验，你应该使用一些其他的生命周期回调函数。

所有的生命周期回调函数都在之后的Managing the Activity Lifecycle中讨论。

 

 

 

Implementing a user interface

实现UI

The user interface for an activity is provided by a hierarchy of views—objects derived from the View class. 

Each view controls a particular rectangular space within the activity's window and can respond to user interaction. 

For example, a view might be a button that initiates an action when the user touches it.

从View类中派生出来的视图-对象的层级关系为activity提供UI

每一个view在activity的window内控制特定的矩形空间，并且回应用户交互。

例如：一个view也许是一个按钮，当用户触摸它的时候启动一个动作。

 

 

Android provides a number of ready-made views that you can use to design and organize your layout. 

"Widgets" are views that provide a visual (and interactive) elements for the screen, such as a button, text field, checkbox, or just an image. 

"Layouts" are views derived from ViewGroup that provide a unique layout model for its child views, such as a linear layout, a grid layout, or relative layout. 

You can also subclass the View and ViewGroup classes (or existing subclasses) to create your own widgets and layouts and apply them to your activity layout.

Android提供许多现成的view，你可以使用他们来设计和组织你的布局。

"Widgets"是在屏幕上提供一个可见的（并且可交互的）元素，例如按钮，文本域，复选框或者就是一张图片的view。

"Layouts"是从ViewGroup派生出来的，提供了唯一的布局模型为其子view，例如线性布局，网格布局或者相对布局。

你也可以继承View或ViewGroup（或存在的其他子类）来建立你自己的widget和layout并且把他们应用在你的activity布局中。

 

 

The most common way to define a layout using views is with an XML layout file saved in your application resources. 

This way, you can maintain the design of your user interface separately from the source code that defines the activity's behavior. 

You can set the layout as the UI for your activity with setContentView(), passing the resource ID for the layout. 

However, you can also create new Views in your activity code and build a view hierarchy by inserting new Views into a ViewGroup, then use that layout by passing the root ViewGroup to setContentView().

最通常的使用view定义布局的方式是在你的应用资源中使用xml布局文件。

这样，你可以保持你自己的UI设计独立于定义activity行为的源码

你可以通过布局的资源ID使用setContentView()为你的activity设置UI布局。

你也可以在你的activity代码中建立新的view，通过往ViewGroup插入新view建立一个view层次结构，然后通过传递ViewGroup的根到setContentView()来使用那个布局。

 

For information about creating a user interface, see the User Interface documentation.

 

 

Declaring the activity in the manifest

在manifest中声明activity

You must declare your activity in the manifest file in order for it to be accessible to the system. 

To declare your activity, open your manifest file and add an <activity> element as a child of the <application> element. 

For example:

你必须在manifest文件中声明你的activity，这样系统才能访问。

为了声明你的activity，打开你的manifest文件并在<application>元素下添加子元素<activity>

例如

<manifest ... >
  <application ... >
      <activity android:name=".ExampleActivity" />
      ...
  </application ... >
  ...
</manifest >

There are several other attributes that you can include in this element, to define properties such as the label for the activity, an icon for the activity, or a theme to style the activity's UI. 

The android:name attribute is the only required attribute—it specifies the class name of the activity. 

Once you publish your application, you should not change this name, because if you do, you might break some functionality, such as application shortcuts (read the blog post, Things That Cannot Change).

你可以在这个元素中包含一些属性，来定义像是activity的UI标签、图标或者样式主题的属性。

android:name是唯一的必选项，它指定activity的类名

一旦你发布了你的应用，你不应该更改这个名字，因为如果你这么做，你也许会破坏一些功能，比如应用的快捷方式（阅读blog文章Things That Cannot Change - 此地址被墙）

See the <activity> element reference for more information about declaring your activity in the manifest.

 

 

Using intent filters

使用intent过滤器

An <activity> element can also specify various intent filters—using the <intent-filter> element—in order to declare how other application components may activate it.

一个<activity>也可以指定多种intent过滤器 - 使用<intent-filter>元素 - 为了声明其他应用组件如何触发它。

 

When you create a new application using the Android SDK tools, the stub activity that's created for you automatically includes an intent filter that declares the activity responds to the "main" action and should be placed in the "launcher" category. 

The intent filter looks like this:

当你使用Android SDK工具建立一个新的应用，工具会自动为你建立包含一个intent过滤器的activity，它声明了activity回应“main”动作并且应该被放在“launcher”类目里。

<activity android:name=".ExampleActivity" android:icon="@drawable/app_icon">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

The <action> element specifies that this is the "main" entry point to the application. 

The <category> element specifies that this activity should be listed in the system's application launcher (to allow users to launch this activity).

<action>元素指定应用的“main”入口处。

<category>元素指定这个activity应该放入系统launcher应用中列出。

 

If you intend for your application to be self-contained and not allow other applications to activate its activities, then you don't need any other intent filters. 

Only one activity should have the "main" action and "launcher" category, as in the previous example. 

Activities that you don't want to make available to other applications should have no intent filters and you can start them yourself using explicit intents (as discussed in the following section).

如果你打算只是在本应用使用此activity而不允许其他应用使用，那么你不再需要其他任何intent过滤器。

只有一个activity应该有“amin”动作和"launcher"类目，就像上面的例子那样。

 

 

However, if you want your activity to respond to implicit intents that are delivered from other applications (and your own), then you must define additional intent filters for your activity. 

For each type of intent to which you want to respond, you must include an <intent-filter> that includes an <action> element and, optionally, a <category> element and/or a <data> element. 

These elements specify the type of intent to which your activity can respond.

然而，如果你想要你的activity响应从其他应用（和你自己的应用）发出的隐式的intent，那么你必须为你的activity定义额外的intent过滤器。

对于每一种你想响应的intent，你必须包含一个<intent-filter>，其包含<action>元素和一个可选的<category>，<data>元素可有可无。

这些元素指定你的activity可以响应的intent类型。

 

For more information about how your activities can respond to intents, see the Intents and Intent Filters document.

 

 

 

Starting an Activity

启动一个activity

You can start another activity by calling startActivity(), passing it an Intent that describes the activity you want to start. 

The intent specifies either the exact activity you want to start or describes the type of action you want to perform (and the system selects the appropriate activity for you, which can even be from a different application). 

An intent can also carry small amounts of data to be used by the activity that is started.

你可以通过调用startActivity()来打开另一个activity，传递一个描述你想打开的activity的intent。

这个intent要么显示指定你想打开的activity，要么描述你想执行的内容的动作类型（并且系统为你选择恰当activity，甚至可以是其他应用中的activity）

一个intent也可以传递一些小数据来给要启动的activity使用。

 

 

When working within your own application, you'll often need to simply launch a known activity. 

You can do so by creating an intent that explicitly defines the activity you want to start, using the class name. 

For example, here's how one activity starts another activity named SignInActivity:

当你在你自己的应用中工作的时候，你会经常简单的需要启动一个已知的activity。

你可以通过建立一个intent，通过使用类名显示定义你想要打开的acitivity来做上面所说的事情。

例如，下面是一个activity如何启动另一个名字为SignInActivity的activity。

Intent intent = new Intent(this, SignInActivity.class);
startActivity(intent);

However, your application might also want to perform some action, such as send an email, text message, or status update, using data from your activity. 

In this case, your application might not have its own activities to perform such actions, so you can instead leverage the activities provided by other applications on the device, which can perform the actions for you. 

This is where intents are really valuable—you can create an intent that describes an action you want to perform and the system launches the appropriate activity from another application. 

If there are multiple activities that can handle the intent, then the user can select which one to use. 

For example, if you want to allow the user to send an email message, you can create the following intent:

然而，你的应用也许也想使用你的activity中的数据执行一些动作，比如发送邮件，输入消息，或者是状态更新。

这种情况下，你的应用也许不会有它自己的activity来执行这些动作，所以，代替的是，你可以使用设备上其他应用提供的可以为你执行这些动作的activity。

这就是intent真正有用的地方，你可以建立一个intent来描述一个你想执行的动作并且系统会从其他启动恰当的activity。

如果有多个activity可以处理这个intent，那么用户可以选择一个来处理。

例如，如果你想允许用户发送一封电子邮件，你可以建立下面的intent

Intent intent = new Intent(Intent.ACTION_SEND);
intent.putExtra(Intent.EXTRA_EMAIL, recipientArray);
startActivity(intent);

The EXTRA_EMAIL extra added to the intent is a string array of email addresses to which the email should be sent. 

When an email application responds to this intent, it reads the string array provided in the extra and places them in the "to" field of the email composition form. 

In this situation, the email application's activity starts and when the user is done, your activity resumes.

被添加到intent中的额外的数据EXTRA_EMAIL是一个收件人string数组。

当一个电子邮件应用响应这个intent时，它读这个额外的string数组，并且把他们放置在电子邮件形式构成的“收件人”中。

这种情况下，电子邮件应用的activity启动，当用户完成邮件，你的activity重新开始。

 

 

Starting an activity for a result

启动一个需要返回结果的activity

Sometimes, you might want to receive a result from the activity that you start. 

In that case, start the activity by calling startActivityForResult() (instead of startActivity()). 

To then receive the result from the subsequent activity, implement the onActivityResult() callback method. 

When the subsequent activity is done, it returns a result in an Intent to your onActivityResult() method.

有时候，你也许想要从你启动的activity中收到一个结果。

这种情况下，调用startActivityForResult()来启动activity（代替startActivity()）

为了之后能从其后的activity中接受到结果，需要实现onActivityResult()这个回调函数。

当之后的activity完成时，它会在一个intent中返回一个结果到onActivityResult()方法中。

 

 

For example, perhaps you want the user to pick one of their contacts, so your activity can do something with the information in that contact. 

Here's how you can create such an intent and handle the result:

例如，也许你想让用户选择一个联系人，这样你的activity可以使用那个联系人的信息做些什么

下面是你如何建立一个这样的intent并且处理其结果

private void pickContact() {
    // Create an intent to "pick" a contact, as defined by the content provider URI
    Intent intent = new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI);
    startActivityForResult(intent, PICK_CONTACT_REQUEST);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    // If the request went well (OK) and the request was PICK_CONTACT_REQUEST
    if (resultCode == Activity.RESULT_OK && requestCode == PICK_CONTACT_REQUEST) {
        // Perform a query to the contact's content provider for the contact's name
        Cursor cursor = getContentResolver().query(data.getData(),
        new String[] {Contacts.DISPLAY_NAME}, null, null, null);
        if (cursor.moveToFirst()) { // True if the cursor is not empty
            int columnIndex = cursor.getColumnIndex(Contacts.DISPLAY_NAME);
            String name = cursor.getString(columnIndex);
            // Do something with the selected contact's name...
        }
    }
}

This example shows the basic logic you should use in your onActivityResult() method in order to handle an activity result. 

The first condition checks whether the request was successful—if it was, then the resultCode will be RESULT_OK—and whether the request to which this result is responding is known—in this case, the requestCode matches the second parameter sent with startActivityForResult(). 

From there, the code handles the activity result by querying the data returned in an Intent (the data parameter).

这个例子展示了要处理activity的结果，你应该在你的onActivityResult()方法中使用的基本的逻辑。

第一个条件是检查请求是否成功 - 如果成功了，那么resultCode应该为RESULT_OK - 并且响应结果的请求是否已知 - 这种情况下，requestCode匹配startActivityForResult()发送的第二个参数

从这看出，这些代码通过查询返回的intent中的数据处理activity的结果

 

 

What happens is, a ContentResolver performs a query against a content provider, which returns a Cursor that allows the queried data to be read. 

For more information, see the Content Providers document.

现在的情况是，ContentResolver违反content provider执行一个查询返回一个游标允许读取查询的数据。

 

For more information about using intents, see the Intents and Intent Filters document.

 

 

 

Shutting Down an Activity

关闭activity

You can shut down an activity by calling its finish() method. 

You can also shut down a separate activity that you previously started by calling finishActivity().

你可以通过调用finish()函数来关闭一个activity

你也可以通过调用finishActivity()关闭之前启动的activity。（通过startActivityForResult打开的）

 

Note: In most cases, you should not explicitly finish an activity using these methods. 

As discussed in the following section about the activity lifecycle, the Android system manages the life of an activity for you, so you do not need to finish your own activities. 

Calling these methods could adversely affect the expected user experience and should only be used when you absolutely do not want the user to return to this instance of the activity.

注意：大多数情况下，你不应该使用这些方法显式的关闭activity。

像下面zctivity生命周期章节讨论的，Android系统为你管理activity的生命，所以你不需要结束你自己的activity。

调用这些方法也许反而会影响用户期待的体验，你必须确定不想让用户返回到activity的这个实例才调用这些方法。

 

 

原文地址如下，英文水平实在有限，希望拍砖同时能给予指正。

http://developer.android.com/guide/components/activities.html

 

 

 

 

转贴请保留以下链接

本人blog地址

http://su1216.iteye.com/

http://blog.csdn.net/su1216/