android sdk 文檔導讀之前傳：初涉

    看到csdn部落格上面其它大牛的系列性android部落格，小弟確實十分羨慕。所以經過一番思想鬥爭後，小弟終於要打算寫寫系列性的部落格了。通過對一些選題的推敲，我決定對android的sdk文檔進行一個比較徹底的研讀，並通過博文的形式和大家分享分享，交流交流。哈哈，現在想起來就熱血沸騰啊！

    這就是第一次嘗試啦。這篇文章主要介紹了android sdk文檔的結構和使用方法以及pakage index裡面的android這一條的相關知識。

    好啦，廢話少說，開動！

一、楔子：關於android sdk文檔

    第一，什麼是android sdk文檔？

    這個問題太白癡了：看到這裡，你肯定會在心裡這麼想。但且慢，這個問題我覺得還是值得談談的，理由嘛，看了下面的你就不點自明了。android sdk的全名是android software develop kit，也就是android程式開發工具組。這也就是說，它本質上也就是一個供大家使用的工具而已--和鎚子、扳手一樣（怪不得代表android開發的logo會是小機器人腰裡別著一個扳手和一個鎚子   ）。既然是一個工具，而且是由穀哥大大最近幾年才猛頂起來的一個新型工具，那麼如果想讓我們這些對它感興趣的人能夠把它使用自如的話，就必然得有一份詳盡的說明書來闡述它在哪裡用、怎麼用以及如何才是在最好的用。android sdk文檔則起到了這個作用：它包含了該工具的幾乎各種情況下使用的組件（也就是android sdk中包含的各種類）的介紹--UI構建時、Gps模組調用時、資料庫操作時、硬體調用時等等；它讓你能夠知道各種工具組件該怎麼使用--各種類所包含的方法、欄位介紹幾乎都已涵蓋，基本上有一定基礎的同學看過即知如何使用該類；它可以使你知道怎樣才是在最好的使用該工具--哪些方法已經到期它會告訴你，一些類的特殊屬性它會教你怎麼最好地使用（例如android.app.Service類的 startForeground (int id, Notification notification) 方法處它就教會了我用java反射機制來調用父類無法繼承給子類的final方法）。到了這裡，我們可以這麼描述android sdk文檔了：一份android sdk的使用說明書。

 

    第二，哪裡可以看到sdk文檔？

    看sdk文檔有兩個途徑，線上網頁瀏覽和離線文檔瀏覽。

    線上的地址是：developer.android.com（被河蟹掉了，表示極為不解，可以去這裡，感謝FaxLJ的提醒）

    離線查看無需你再去單獨下載文檔包，因為如果你當初下載android sdk時選擇完整下載了，文檔就被一併下載到本地了。一般andorid sdk的根目錄裡的docs檔案夾就是文檔所在地，裡面有一個index.html，開啟它就可以看到sdk文檔的homepage。

    個人推薦離線查看，雖然可能不是最新版本的文檔，但總比翻牆被龜速折磨來的好些╮(╯▽╰)╭。

    第三、文檔重要性。

    以前我剛開始學java的時候曾經做過一件很腦殘的事情：看到System.out.println("Hello World!");這一句代碼時我就想知道System是一個什麼樣的東西，於是就去網上搜尋--可是花了很多時間，也看了一些文章，但就還是無法對System有一個系統性的瞭解--還是到後來瞭解到java文檔，把java文檔下載下來（java文檔在sdk裡預設是不包含的）後去看了才把它瞭解透--What a shame!好了，不用我說你也就應該瞭解到了sdk文檔的重要性：文檔是官方提供的，所以具有無以倫比的權威性；文檔是起說明式作用的，所以你想要知道什麼，"騾跡"上是都會給你提供的；因為文檔是很重要的，所以文檔是很重要的。我建議大家要養成一個習慣，以後遇到疑問時，首先應該想到去sdk文檔上尋找，然後再去百度上google：這樣做一來可以鍛煉自己理解E文的能力，二來也會讓自己的印象更深刻些。

    第四、關於文檔的好東東推薦

    1.線上java2中文文檔查看

    2.google官方c++規範

    3.android中google地圖使用文檔

    4.關於javadoc

二、開端和升華：android sdk文檔基本知識介紹

    要想能夠快速的、有技巧的使用android sdk文檔，首先就要瞭解這個東東。所以接下來我會和大家侃侃android sdk文檔的結構、內容等各方面的基本知識。

    1.android sdk文檔結構

 

    1號地區：標籤欄，各個標籤代表了文檔所包含的不同種類的協助。

        Home：歡迎介面

        SDK：對各版本SDK的概述、對開發環境的搭建的指導等等一些開發準備知識

        Dev Guide：對開發本身進行了比較初級的指導，一些比較實用給力的例子都在這裡了

        Reference：類似於Java api文檔的android api文檔，以後我們會常光顧的地方（就是Reference的首頁）

        Resources Video 和 Blog：對開發人員的一些其他支援資源，我們的網路環境下估計是很難享受到的

        以後我會主要去探索Reference這個含金量比較多的版塊，另外有需要的話會穿插看看Dev  Guide。

    2號地區：Reference中的包列表

            關於各包的簡介看這裡。

    3號地區：Reference主要內容瀏覽地區

    4號地區：搜尋方塊，主要用於搜尋某個類後介面以快速探索該類的Reference（好用，極力推薦！）

          利用文檔內建的搜尋方塊的自動補全功能，你可以以神速搜尋到你想要查詢的類。例如我要搜尋LayoutParams，就只需輸入Layo四個字母就可以出現這個類，然後點擊該類就直接進入了LayoutParams的文檔。

    5號地區：用於根據android apiLevel（android中對各個版本的api作了一個序號對應，從而易於分辨。例如2.2版本對應8）過濾類和介面以及相關方法，也很實用

    6號地區：某包內各類以及介面的展示地區

2.文檔內容

    在這裡就說說Reference的主要內容吧。

    對於一個類，Reference相關於它會羅列出如下的幾部分相關內容：

  （1）重要屬性概述。該類的“首碼”——public、private、abstract等；該類的“親戚”關係——繼承於誰、實現了哪些介面、有哪些直接子類和間接子類等等；該類的曆史淵源——從哪個apiLevel開始存在。例如Intent（如）：

 

    這就告訴了我們Intent是一個public class，並且繼承自Object，它還實現了Parcelable以及Cloneable介面。它有一個直接子類LabeledIntent。而且Intent自Api Level 1就已經存在了（元老級人物啊）。

    （2）該類的整體介紹（Class Overview）。在這裡會對該類進行一個功能上的和性質上的描述，語言簡潔給力，是極為重要因而必須認真品讀的一部分。例如LayoutInflater的Class Overview：

 

    看完後大概就可以知曉：LayoutInflater是一個將XML檔案中的layout資訊進行執行個體化，轉化為View類執行個體的工具類。而且十分令人興奮的是，這裡還給予了一個獲得LayoutInflater的方法（中間java代碼處），真是考慮的周到啊（當你看了Activity、View、Intent等的Class Overview後，你甚至會感動地“內牛滿面”）！

    （3）簡述（Summary）。在這個地方會對該類的一切屬性（沒錯，就是一切，包括了XML代碼中會用到的屬性）進行一個概括式的（通常是一句話）描述——主要目的就是方便你尋找。這部分包含了如下幾個小單元：

i.該類的內部類（Nested Classes）

    在這裡會將會介紹該類的全部內部類。想要查看某個內部類的具體資訊，可以點擊該內部類的連結，這樣回跳到該內部類的文檔介面。

ii.可以應用到該類上面的XML屬性（XML Attributes）

    很多童鞋在剛開始都有一些疑問：我該到哪裡去找一個UI組件的XML屬性介紹呢？我要把LinearLayout的背景設為某個圖片，可我該用哪個XML屬性呢？有沒有哪個XML屬性可以把我的Button變得更漂亮呢？剛開始我也十分困惑，而且總因為這些疑問得不到解決而鬱悶。到後來我仔細研究了android sdk文檔後，這些問題就大致得到解決了——因為文檔裡面有專門的一塊來

    介紹XML屬性。例如ImageView的XML屬性介紹：

 

    看了Description後，是不是很多疑問都變成浮雲啦（覺得給力就鼓掌吧，我可是不會介意的）？另外你可能會納悶——中間的Related Method有什麼用——這裡就是重點了：這些Related

    Method其實就是Related Method in java，也就是說在java代碼中能夠改變這個屬性的相關該類的方法。例如，想給ImageView設定一個圖片，你可以這樣來android:src="@drawable/my_picture"，而當你看到android:src屬性還有一個setImageResource(int)的相關方法時，你就還可以這樣來在java代碼中設定：myImageView.setImageResource(R.drawable.my_picture);。還記得當初我發現這個可是好好的竊喜了一段時間的。

iii.繼承而來的XML屬性（Inherited XML Attributes）

    沒錯，神奇的XML決定了android中的各種屬性是可以通過繼承從父類傳遞到子類的。當你在XML Attributes中找不到某個屬性時，你可以在這裡找找，一般是可以找到的。

iv.常量（Constants）

    這裡包含了該類擁有的一些常量。常量後面有簡介，點擊常量後會跳轉到該常量的詳細介紹。建議大家去看看Intent、Window等比較重要的類的常量介紹，相信我，很給力的。

v.繼承來的常量（Inherited Constants）

    從父類繼承而來的常量。

vi.方法列舉（Methods）

    這裡包含了該類所有的方法的索引式簡介——包括public protected方法，構造器（constructors）方法。private方法就別想看到了，如果你想使用的話，先去看看sdk原始碼，然後再利用反射來擷取該方法吧。

    （4）詳細描述

    此部分與簡述部分進行一一對應，將簡述部分的XML屬性、常量和方法進行了更詳細的描述。有的地方甚至還會提供一些範例供讀者參考。

    對於XML屬性，這裡會告訴你該給此屬性賦予什麼樣的值：

clickable必須設定為一個boolean值

    對於方法，這裡會提供參數以及傳回值的概述：

 

 

    好啦，我承認這一部分很小白，請各位不要見怪。但我覺得介紹一個東西就要負責任地完整展示，所以就把這部分放上來了。想要拍磚的童鞋看完這部分後請把磚留在評論部分，如果磚的品質還不錯，我會收藏的哦！

三、高 潮：android包介紹

     當你開啟Reference這頁文檔時，你在Pakage Index裡首先看到就是android包。這個包也許許多童鞋還沒進去光顧過吧——不過我得告訴你，這個包裡面的東西可是給力指數8星級的哦！流口水了吧？好，咱們這就去看看裡面的東東（這個包包含的東西相對結構簡單些，所以一次性全部介紹完）。

    android這個包裡面  

    該包所含類：

 

（1）Manifest

    好的，你肯定已經想到了android工程檔案中的AndroidManifest.xml

檔案，並且在猜想它和該類的“曖昧”關係了。Bingo！其實就是這樣的——它們的關係十分親密：Manifest類的執行個體其實一般是通過AndroidManifest.xml檔案通過XML解析後產生的（如果你暫時無法理解，可以聯想一下LayoutInflater這個將XML中的Layout解析為View類的執行個體這個很熟悉的過程）。Manifest執行個體中便儲存了AndroidManifest.xml中的資訊（Activity屬性資訊、許可權使用資訊）以協助系統處理你的應用——例如該把哪個Activity作為起始Activity、Activity是否禁止橫屏顯示等等。

（2）Manifest.permission和Manifest.permission_group

    這兩個類的主要成員是一些String。通過這些String，android實現了應用許可權的的給予以及管理。   

    如果你在android程式中使用過Google Api的話，或者你曾經研究過調用相機來拍照的話，那你就對這幾句代碼不會陌生：

1	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"></uses-permission>
2	<uses-permission android:name="android.permission.INTERNET"></uses-permission>
3	<uses-permission android:name="android.permission.CAMERA"> </uses-permission>

    這些代碼都聲明了你的應用的使用許可權——位置擷取功能使用許可權、使用網路的許可權、硬體相機的使用許可權——如果你不聲明許可權的話，應用就會意外終止。而這些在AndroidManifest.xml中聲明的語句其實也會在應用載入的過程中被解析為Manifest.permission和Manifest.permission_group中的String對象。

（3）R以及它的所有子類（從R.anim至R.xml）

    這裡的R代表的是Resource，也就是資源的意思。不難猜想到這一系列的類構成了android系統內建資源的集合。

    R.anim：系統內建的android動畫檔案，包含我們熟悉的fade_in和fade_out

    R.array：系統內建數組。

    R.attr：這個類是十分給力的，因為android中所有的xml屬性都在這裡查得到——不用說常見的layout_height和layout_width，一些我們基本不會遇到的xml屬性這裡都有介紹。所以，以後如果在別人的代碼中看到了一個自己聞所未聞的xml屬性，就來這裡查查吧——相信我，你不會失望的！

    R.bool：很奇怪的類，因為它除了一個構造方法外什麼都沒有——他是幹什麼用的呢？期待大鳥解答！

    R.color：一些系統平時會調用到的顏色資源（應該也就是一些RGB顏色碼的數值吧），當然，你也可以在你的應用中調用，從而使它盡量和android系統保持一樣的配色風格。

    R.demon：看了文檔我只知到它和android的程式啟動器（android launcher）有關——因為它有一個屬性是app_icon_size，這個屬性定義了標準的應用表徵圖大小。

    R.drawable:一些系統會用到的drawable資源。

    R.id：系統程式會調用到得組件的id。

    R.integer：這裡有一些常量，而且都用於控制android animation的時間長度——長、中等、短（config_longAnimTime、config_mediumAnimTime、config_shortAnimTime）。你可以在你自訂的animation中使用這些現成的時間長度，從而讓你的animation符合android的本地特色。

    R.layout：系統裡面經常用到的layout檔案都在這裡。平時我們使用Spinner時常常會使用到android.R.layout.simple_list_item_single_choice就是出自這裡。

    R.plurals：和bool一樣等待高人解釋。

    R.raw：沒有任何成員被文檔指出，但根據名字我猜想是系統的一些原生資源的集合地（例如開關機的音效檔）。

    R.string：一些系統會調用的string對象。

    R.style：系統內一些常用的android style檔案（也就是一些主題（Theme）檔案）。

 

    寫到這裡，希望能夠解決掉各位童鞋心中的些許抑或，一個我也很高興很滿足了。

 

四、尾聲：一些聲明

 

    由於是第一篇，所以講的東西可能對於大牛們這些東西就有些小白了，但是為了照顧剛剛起步的童鞋們，還是把一些最基礎的知識加了進來形成第一篇“前傳”。對於已經對上述基礎熟悉的童鞋們，就看看講述android包的那部分吧，應該還是有點協助的——另外該包裡有幾個沒有我沒有研究透的，希望有高手協助解決——不勝感激啦！

 

    至於轉載的話，隨便你啦，覺得好，有協助就頂下吧！另外請註明是出於csdn（說不說是俺沒關係，但是csdn的是必須註明的，望理解）。

 

    好啦，鳴謝：擺渡、穀哥。

 

    各位看官，謝謝圍觀。

    如有紕漏，歡迎拍磚！