1page.title=限定範圍目錄存取
2page.keywords=preview,sdk,scoped directory access
3page.tags=androidn
4
5@jd:body
6
7<div id="qv-wrapper">
8<div id="qv">
9  <h2>此文件內容</h2>
10  <ol>
11    <li><a href="#accessing">存取外部儲存空間目錄</a></li>
12    <li><a href="#removable">存取抽取式媒體上的目錄</a></li>
13    <li><a href="#best">最佳做法</a></li>
14  </ol>
15</div>
16</div>
17
18<p>應用程式 (例如，相片應用程式) 通常只需要存取外部儲存空間中的特定目錄，例如 <code>Pictures</code> 目錄。
19目前用來存取外部儲存空間的方式並非設計來輕鬆地為這些類型的應用程式提供已設定目標的目錄存取。
20
21例如：</p>
22
23<ul>
24<li>在您的宣示說明中要求 {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} 或 {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} 可允許存取外部儲存空間ac上的所有公用目錄，但這可能超過您應用程式所需的存取權。
25
26
27</li>
28<li>使用<a href="{@docRoot}guide/topics/providers/document-provider.html">儲存空間存取架構</a>通常會使得您的使用者透過系統 UI 挑選目錄，這在您的應用程式一律存取相同外部目錄的情況下是不必要的。
29
30
31
32</li>
33</ul>
34
35<p>Android N 提供新的簡化 API，可用來存取常用外部儲存空間目錄。
36 </p>
37
38<h2 id="accessing">存取外部儲存空間目錄</h2>
39
40<p>使用 <code>StorageManager</code> 類別來取得適當的 <code>StorageVolume</code> 實例。
41接著，透過呼叫該實例的 <code>StorageVolume.createAccessIntent()</code> 方法以建立意圖。使用此意圖來存取外部儲存空間目錄。
42
43若要取得所有可用的磁碟區 (包括抽取式媒體磁碟區) 清單，請使用 <code>StorageManager.getVolumesList()</code>。
44
45</p>
46
47<p>下列程式碼片段是一個範例，它說明如何開啟主要共用儲存空間中的 <code>Pictures</code> 目錄：
48</p>
49
50<pre>
51StorageManager sm = (StorageManager)getSystemService(Context.STORAGE_SERVICE);
52StorageVolume volume = sm.getPrimaryVolume();
53Intent intent = volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
54startActivityForResult(intent, request_code);
55</pre>
56
57<p>系統會嘗試授予對外部目錄的存取權，並在需要時使用簡化的 UI 向使用者確認存取權：
58</p>
59
60<img src="{@docRoot}preview/images/scoped-folder-access-framed.png" srcset="{@docRoot}preview/images/scoped-folder-access-framed.png 1x,
61{@docRoot}preview/images/scoped-folder-access-framed_2x.png 2x" />
62<p class="img-caption"><strong>圖 1.</strong> 應用程式要求對 [圖片] 目錄的存取權。
63</p>
64
65<p>若使用者授予存取權，系統會呼叫您的 <code>onActivityResult()</code> 覆寫並傳回 <code>Activity.RESULT_OK</code> 的結果代碼，以及包含 URI 的意圖資料。
66
67使用提供的 URI 來存取目錄資訊，這類似於使用<a href="{@docRoot}guide/topics/providers/document-provider.html">儲存空間存取架構</a>所傳回的 URI。
68
69
70
71</p>
72
73<p>若使用者未授予存取權，系統會呼叫您的 <code>onActivityResult()</code> 覆寫並傳回 <code>Activity.RESULT_CANCELED</code> 的結果代碼，以及 Null 意圖資料。
74
75</p>
76
77<p class="note"><b>注意</b>：取得對特定外部目錄的存取權也會取得對該目錄之子目錄的存取權。
78</p>
79
80<h2 id="removable">存取抽取式媒體上的目錄</h2>
81
82<p>若要使用「限定範圍目錄存取」來存取抽取式媒體上的目錄，請先新增會接聽 {@link android.os.Environment#MEDIA_MOUNTED} 通知的 {@link android.content.BroadcastReceiver}，例如：
83
84</p>
85
86<pre>
87&lt;receiver
88    android:name=".MediaMountedReceiver"
89    android:enabled="true"
90    android:exported="true" &gt;
91    &lt;intent-filter&gt;
92        &lt;action android:name="android.intent.action.MEDIA_MOUNTED" /&gt;
93        &lt;data android:scheme="file" /&gt;
94    &lt;/intent-filter&gt;
95&lt;/receiver&gt;
96</pre>
97
98<p>當使用者掛接抽取式媒體 (例如 SD 卡) 時，系統會傳送 {@link android.os.Environment#MEDIA_MOUNTED} 通知。
99此通知會在意圖資料中提供 <code>StorageVolume</code> 物件，讓您用來存取抽取式媒體上的目錄。
100
101下列範例會存取抽取式媒體上的 <code>Pictures</code> 目錄：
102</p>
103
104<pre>
105// BroadcastReceiver has already cached the MEDIA_MOUNTED
106// notification Intent in mediaMountedIntent
107StorageVolume volume = (StorageVolume)
108    mediaMountedIntent.getParcelableExtra(StorageVolume.EXTRA_STORAGE_VOLUME);
109volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
110startActivityForResult(intent, request_code);
111</pre>
112
113<h2 id="best">最佳做法</h2>
114
115<p>如果可能，請將外部目錄存取 URI 設定為持續性，這樣您就不需要重複地要求使用者授予存取權。
116一旦使用者授予存取權，請使用目錄存取 URI 呼叫 <code>getContentResolver().takePersistableUriPermssion()</code>。
117
118系統會將該 URI 設定為持續性，而且後續存取要求將會傳回 <code>RESULT_OK</code>，而且不會為使用者顯示確認 UI。
119
120</p>
121
122<p>若使用者拒絕對外部目錄的存取權，請勿立刻又要求存取權。
123重複堅持取得存取權會導致極差的使用者體驗。
124</p>
125