相機獨立閃光燈Camera-independent Flashlight

本文章說明如何存取和使用裝置的燈光 (如果有的話)。This article shows how to access and use a device's lamp, if one is present. 燈光功能分別從裝置的相機和閃光燈功能來管理。Lamp functionality is managed separately from the device's camera and camera flash functionality. 除了取得燈光的參考及調整其設定以外,本文也說明如何在不使用燈光時正確地釋出燈光資源,以及如何偵測燈光的可用性何時變更以免另一個 App 正在使用它。In addition to acquiring a reference to the lamp and adjusting its settings, this article also shows you how to properly free up the lamp resource when it's not in use, and how to detect when the lamp's availability changes in case it is being used by another app.

取得裝置的預設燈光Get the device's default lamp

若要取得裝置的預設燈光裝置,請呼叫 Lamp.GetDefaultAsyncTo get a device's default lamp device, call Lamp.GetDefaultAsync. Windows.Devices.Lights 命名空間中可找到燈光 API。The lamp APIs are found in the Windows.Devices.Lights namespace. 請務必先為此命名空間新增 using 指示詞,再嘗試存取這些 API。Be sure to add a using directive for this namespace before attempting to access these APIs.

using Windows.Devices.Lights;
Lamp lamp;
lamp = await Lamp.GetDefaultAsync();

if (lamp == null)
{
    ShowErrorMessage("No Lamp device found");
    return;
}

如果傳回的物件是 null,則裝置不支援 Lamp API。If the returned object is null, the Lamp API is unsupported on the device. 即使裝置上有實際配備燈光,但有些裝置可能不支援 Lamp API。Some devices may not support the Lamp API even if there is a lamp physically present on the device.

取得使用燈光選取器字串的特定燈光Get a specific lamp using the lamp selector string

有些裝置可能有一個以上的燈光。Some devices may have more than one lamp. 若要取得裝置上可用燈光的清單,請呼叫 GetDeviceSelector 以取得裝置選取器字串。To obtain a list of lamps available on the device, get the device selector string by calling GetDeviceSelector. 此選取器字串可接著傳遞到 DeviceInformation.FindAllAsync 中。This selector string can then be passed into DeviceInformation.FindAllAsync. 這個方法用來列舉許多不同種類的裝置,而選取器字串可讓方法知道只要傳回燈光裝置。This method is used to enumerate many different kinds of devices and the selector string lets the method know to return only lamp devices. FindAllAsync 傳回的 DeviceInformationCollection 物件是 DeviceInformation 物件的集合,代表裝置上可用的燈光。The DeviceInformationCollection object returned from FindAllAsync is a collection of DeviceInformation objects representing the lamps available on the device. 選取清單中的其中一個物件,然後將 Id 屬性傳遞至 Lamp.FromIdAsync 以取得對要求之燈光的參考。Select one of the objects in the list and then pass the Id property to Lamp.FromIdAsync to get a reference to the requested lamp. 這個範例使用來自 System.Linq 命名空間的 GetFirstOrDefault 延伸方法來選取 DeviceInformation 物件,其中 EnclosureLocation.Panel 屬性的值為 Back,該值會選取裝置機殼背面的燈光 (如果有的話)。This example uses the GetFirstOrDefault extension method from the System.Linq namespace to select the DeviceInformation object where the EnclosureLocation.Panel property has a value of Back, which selects a lamp that is on the back of the device's enclosure, if one exists.

請注意,在 Windows.Devices.Enumeration 命名空間中可找到 DeviceInformation API。Note that the DeviceInformation APIs are found in the Windows.Devices.Enumeration namespace.

using Windows.Devices.Enumeration;
using System.Linq;
string selectorString = Lamp.GetDeviceSelector();


DeviceInformationCollection devices = await DeviceInformation.FindAllAsync(selectorString);

DeviceInformation deviceInfo =
    devices.FirstOrDefault(di => di.EnclosureLocation != null && 
        di.EnclosureLocation.Panel == Windows.Devices.Enumeration.Panel.Back);

if (deviceInfo == null)
{
    ShowErrorMessage("No Lamp device found");
}

lamp = await Lamp.FromIdAsync(deviceInfo.Id);

調整燈光設定Adjust lamp settings

擁有 Lamp 類別的執行個體後,請將 IsEnabled 屬性設定為 true 以開啟燈光。After you have an instance of the Lamp class, turn the lamp on by setting the IsEnabled property to true.

lamp.IsEnabled = true;

IsEnabled 屬性設定為 false,以關閉燈光。Turn the lamp off by setting the IsEnabled property to false.

lamp.IsEnabled = false;

部分裝置具有支援色彩值的燈光。Some devices have lamps that support color values. 檢查 IsColorSettable 屬性以查看燈光是否支援色彩。Check if a lamp supports color by checking the IsColorSettable property. 如果此值為 true,您可以使用 Color 屬性設定燈光的色彩。If this value is true, you can set the color of the lamp with the Color property.

if (lamp.IsColorSettable)
{
    lamp.Color = Windows.UI.Colors.Blue;
}

登錄以在燈光可用性變更時收到通知Register to be notified if the lamp availability changes

燈光存取權會授予最新的 App 以要求存取權。Lamp access is granted to the most recent app to request access. 因此,如果另一個 App 已啟動並要求您的 App 目前所使用的燈光資源,則在其他 App 釋出資源前,您的 App 將無法再控制燈光。So, if another app is launched and requests a lamp resource that your app is currently using, your app will no longer be able to control the lamp until the other app has released the resource. 若要在燈光的可用性變更時收到通知,請登錄 Lamp.AvailabilityChanged 事件的處理常式。To receive a notification when the availability of the lamp changes, register a handler for the Lamp.AvailabilityChanged event.

lamp = await Lamp.GetDefaultAsync();

if (lamp == null)
{
    ShowErrorMessage("No Lamp device found");
    return;
}

lamp.AvailabilityChanged += Lamp_AvailabilityChanged;

在此事件的處理常式中,檢查 LampAvailabilityChanged.IsAvailable 屬性,以判斷燈光是否可用。In the handler for the event, check the LampAvailabilityChanged.IsAvailable property to determine if the lamp is available. 在此範例中,用於開啟和關閉燈光的切換開關會根據燈光可用性來啟用或停用。In this example, a toggle switch for turning the lamp on and off is enabled or disabled based on the lamp availability.

private void Lamp_AvailabilityChanged(Lamp sender, LampAvailabilityChangedEventArgs args)
{
    lampToggleSwitch.IsEnabled = args.IsAvailable;
}

不使用燈光資源時的適當處置Properly dispose of the lamp resource when not in use

當您不再使用燈光時,您應該將它停用並呼叫 Lamp.Close 以釋出資源,讓其他 App 可存取此燈光。When you are no longer using the lamp, you should disable it and call Lamp.Close to release the resource and allow other apps to access the lamp. 如果您使用 C#,此屬性會對應至 Dispose 方法。This property is mapped to the Dispose method if you are using C#. 如果您已登錄 AvailabilityChanged,您應在處置燈光資源時取消登錄此處理常式。If you registered for the AvailabilityChanged, you should unregister the handler when you dispose of the lamp resource. 您的程式碼中處置燈光資源的適當位置取決於您的 App。The right place in your code to dispose of the lamp resource depends on your app. 若要將燈光存取的範圍限制為單一頁面,請釋出 OnNavigatingFrom 事件中的資源。To scope lamp access to a single page, release the resource in the OnNavigatingFrom event.

protected override void OnNavigatingFrom(NavigatingCancelEventArgs e)
{
    lamp.AvailabilityChanged -= Lamp_AvailabilityChanged;
    lamp.IsEnabled = false;
    lamp.Dispose();
    lamp = null;
}