uiautomator_2_selector

Selector is to identify specific ui object in current window.(选择器是在当前窗口中标识特定的UI对象)

# To seleted the object ,text is 'Clock' and its className is 'android.widget.TextView'
d(text='Clock', className='android.widget.TextView')

Selector supports below parameters. Refer to UiSelector java doc for detailed information.(选择器支持以下can有关详细信息，请参阅UiSelector java doc。)

• text, textContains, textMatches, textStartsWith
• className, classNameMatches
• description, descriptionContains, descriptionMatches, descriptionStartsWith
• checkable, checked, clickable, longClickable
• scrollable, enabled,focusable, focused, selected
• packageName, packageNameMatches
• resourceId, resourceIdMatches
• index, instance

Child and sibling UI object

• child

# get the child or grandchild
d(className="android.widget.ListView").child(text="Bluetooth")

• sibling

# get sibling or child of sibling
d(text="Google").sibling(className="android.widget.ImageView")

• child by text or description or instance（通过文字或描述或实例获取子控件）

# get the child match className="android.widget.LinearLayout"
# and also it or its child or grandchild contains text "Bluetooth"
d(className="android.widget.ListView", resourceId="android:id/list") \
 .child_by_text("Bluetooth", className="android.widget.LinearLayout")
# allow scroll search to get the child
d(className="android.widget.ListView", resourceId="android:id/list") \
 .child_by_text(
    "Bluetooth",
    allow_scroll_search=True,
    className="android.widget.LinearLayout"
  )

• child_by_description is to find child which or which's grandchild contains the specified description, others are the same as child_by_text.（child_by_description是查找哪个子控件或哪个孙控件包含指定的描述，其他的则与child_by_text相同）

• child_by_instance is to find child which has a child UI element anywhere within its sub hierarchy that is at the instance specified. It is performed on visible views without scrolling.（child_by_instance用于查找在其指定实例的子层次结构中具有子UI元素的子元素。它在没有滚动的可见视图上执行）

• See below links for detailed information（详细信息请参阅下面的链接）:

• UiScrollable, getChildByDescription, getChildByText, getChildByInstance
• UiCollection, getChildByDescription, getChildByText, getChildByInstance

We want to click the switch at the right side of text 'Wi‑Fi' to turn on/of Wi‑Fi. As there are several switches with almost the same properties, so we can not use like d(className="android.widget.Switch") to select the ui object. Instead, we can use code below to select it.（我们要点击文字“Wi-Fi”右侧的开关打开/关闭Wi-Fi。由于有几个开关几乎具有相同的属性，所以我们不能使用像d（className =“android.widget.Switch”）来选择ui对象。相反，我们可以使用下面的代码来选择它。）

d(className="android.widget.ListView", resourceId="android:id/list") \
  .child_by_text("Wi‑Fi", className="android.widget.LinearLayout") \
  .child(className="android.widget.Switch") \
  .click()

• relative position

Also we can use the relative position methods to get the view: left, right, top, bottom.（我们也可以使用相对位置方法来获得视图：左，右，上，下。）

• d(A).left(B), means selecting B on the left side of A.
• d(A).right(B), means selecting B on the right side of A.
• d(A).up(B), means selecting B above A.
• d(A).down(B), means selecting B under A.

So for above case, we can write code alternatively:

## select "switch" on the right side of "Wi‑Fi"
d(text="Wi‑Fi").right(className="android.widget.Switch").click()

• Multiple instances

Sometimes the screen may contain multiple views with the same e.g. text, then you will have to use "instance" properties in selector like below:（

有时，屏幕可能包含多个视图，例如相同的视图。文本，那么你将不得不在选择器中使用“实例”属性，如下所示：

）

d(text="Add new", instance=0)  # which means the first instance with text "Add new"

However, uiautomator provides list like methods to use it.（然而，uiautomator提供了类似列表的方法来使用它。）

# get the count of views with text "Add new" on current screen
d(text="Add new").count

# same as count property
len(d(text="Add new"))

# get the instance via index
d(text="Add new")[0]
d(text="Add new")[1]
...

# iterator
for view in d(text="Add new"):
    view.info  # ...

Notes : when you are using selector like a list, you must make sure the screen keep unchanged, else you may get ui not found error.（注意：当你像列表一样使用选择器时，你必须确保屏幕保持不变，否则你可能会遇到未找到错误。）

Get the selected ui object status and its information（获取选定的ui对象状态及其信息）

• Check if the specific ui object exists（监察特定的UI对象是否存在）

d(text="Settings").exists # True if exists, else False
d.exists(text="Settings") # alias of above property.

• Retrieve the info of the specific ui object

d(text="Settings").info

Below is a possible result:（以下是可能的结果）

{ u'contentDescription': u'',
  u'checked': False,
  u'scrollable': False,
  u'text': u'Settings',
  u'packageName': u'com.android.launcher',
  u'selected': False,
  u'enabled': True,
  u'bounds': {u'top': 385,
              u'right': 360,
              u'bottom': 585,
              u'left': 200},
  u'className': u'android.widget.TextView',
  u'focused': False,
  u'focusable': True,
  u'clickable': True,
  u'chileCount': 0,
  u'longClickable': True,
  u'visibleBounds': {u'top': 385,
                     u'right': 360,
                     u'bottom': 585,
                     u'left': 200},
  u'checkable': False
}

• Set/Clear text of editable field（设置/清除可编辑控件的文字）

d(text="Settings").clear_text()  # clear the text
d(text="Settings").set_text("My text...")  # set the text

Perform the click action on the seleted ui object（对选定的UI对象执行操作）

• Perform click on the specific ui object

# click on the center of the specific ui object
d(text="Settings").click()
# click on the bottomright corner of the specific ui object
d(text="Settings").click.bottomright()
# click on the topleft corner of the specific ui object
d(text="Settings").click.topleft()
# click and wait until the new window update
d(text="Settings").click.wait()

• Perform long click on the specific ui object

# long click on the center of the specific ui object
d(text="Settings").long_click()
# long click on the bottomright corner of the specific ui object
d(text="Settings").long_click.bottomright()
# long click on the topleft corner of the specific ui object
d(text="Settings").long_click.topleft()

Gesture action for the specific ui object（对特定UI对象执行手势动作）

• Drag the ui object to another point or ui object(将ui对象拖动到一个点或者一个对象)

# notes : drag can not be set until Android 4.3.
# drag the ui object to point (x, y)
d(text="Settings").drag.to(x, y, steps=100)
# drag the ui object to another ui object(center)
d(text="Settings").drag.to(text="Clock", steps=50)

• Swipe from the center of the ui object to its edge（从UI对象的中心滑到边缘）

Swipe supports 4 directions:

• left
• right
• top
• bottom

d(text="Settings").swipe.right()
d(text="Settings").swipe.left(steps=10)
d(text="Settings").swipe.up(steps=10)
d(text="Settings").swipe.down()

• Two point gesture from one point to another（从一点到另外一点的两个手势）

d(text="Settings").gesture((sx1, sy1), (sx2, sy2)) \
                  .to((ex1, ey1), (ex2, ey2))

• Two point gesture on the specific ui object

Supports two gestures:

• In, from edge to center
• Out, from center to edge

# notes : pinch can not be set until Android 4.3.
# from edge to center. here is "In" not "in"
d(text="Settings").pinch.In(percent=100, steps=10)
# from center to edge
d(text="Settings").pinch.Out()

• 3 point gesture（3点手势）

d().gestureM((sx1, sy1), (sx2, sy2),(sx3, sy3)) \
                  .to((ex1, ey1), (ex2, ey2),(ex3,ey3))
d().gestureM((100,200),(300,200),(600,200),(100,600),(300,600),(600,900))

• Wait until the specific ui object appears or gone（等待特定的UI对象出现或则消失）

# wait until the ui object appears
d(text="Settings").wait.exists(timeout=3000)
# wait until the ui object gone
d(text="Settings").wait.gone(timeout=1000)

• Perform fling on the specific ui object(scrollable)（对特定的ui对象执行一次（可滚动））

Possible properties:

• horiz or vert
• forward or backward or toBeginning or toEnd

# fling forward(default) vertically(default) 
d(scrollable=True).fling()
# fling forward horizentally
d(scrollable=True).fling.horiz.forward()
# fling backward vertically
d(scrollable=True).fling.vert.backward()
# fling to beginning horizentally
d(scrollable=True).fling.horiz.toBeginning(max_swipes=1000)
# fling to end vertically
d(scrollable=True).fling.toEnd()

• Perform scroll on the specific ui object(scrollable)（对特定的UI对象执行滚动（可滚动））

Possible properties:

• horiz or vert
• forward or backward or toBeginning or toEnd, or to

# scroll forward(default) vertically(default)
d(scrollable=True).scroll(steps=10)
# scroll forward horizentally
d(scrollable=True).scroll.horiz.forward(steps=100)
# scroll backward vertically
d(scrollable=True).scroll.vert.backward()
# scroll to beginning horizentally
d(scrollable=True).scroll.horiz.toBeginning(steps=100, max_swipes=1000)
# scroll to end vertically
d(scrollable=True).scroll.toEnd()
# scroll forward vertically until specific ui object appears
d(scrollable=True).scroll.to(text="Security")