选择器-筛选条件
## selector()
- 返回 选择器自身以便链式调用 {UiSelector}
**创建一个新的选择器**。++但一般情况不需要使用该函数，因为可以直接用相应条件的语句创建选择器++。
>w 由于历史遗留原因，本不应该这样设计(不应该让id(), text()等作为全局函数，而是应该用By.id(), By.text())，但为了后向兼容性只能保留这个设计。
这样的API设计会污染全局变量，后续可能会支持"去掉这些全局函数而使用By.*"的选项。
## UiSelector.text(str)
- str {string} 控件文本
- 返回 {UiSelector} 返回选择器自身以便链式调用
**为当前选择器附加控件"text等于字符串str"的筛选条件**。
控件的text(文本)属性是文本控件上的显示的文字，例如微信左上角的"微信"文本。
## UiSelector.textContains(str)
- str {string} 要包含的字符串
**为当前选择器附加控件"text需要包含字符串str"的筛选条件**。
>i 这是一个比较有用的条件，例如QQ动态页和微博发现页上方的"大家都在搜...."的控件可以用textContains("大家都在搜").findOne()来获取。
## UiSelector.textStartsWith(prefix)
- prefix {string} 前缀
**为当前选择器附加控件"text需要以prefix开头"的筛选条件**。
>i 这也是一个比较有用的条件，例如要找出Auto.js脚本列表中名称以"QQ"开头的脚本的代码为textStartsWith("QQ").find()。
## UiSelector.textEndsWith(suffix)
- suffix {string} 后缀
**为当前选择器附加控件"text需要以suffix结束"的筛选条件**。
## UiSelector.textMatches(reg)
- reg {string} | {Regex} 要满足的正则表达式。
**为当前选择器附加控件"text需要满足正则表达式reg"的条件**。
有关正则表达式，可以查看[正则表达式](https://www.w3school.com.cn/js/js_regexp.asp) -W3school。
需要注意的是，如果正则表达式是字符串，则需要使用\\来表达\(也即Java正则表达式的形式)，例如textMatches("\\d+")匹配多位数字
但如果使用JavaScript语法的正则表达式则不需要，例如textMatches(/\d+/)。
但如果使用字符串的正则表达式则该字符串不能以"/"同时以"/"结束，也即不能写诸如textMatches("/\\d+/")的表达式，否则会被开头的"/"和结尾的"/"会被忽略。
## UiSelector.desc(str)
- str {string} 控件文本
- 返回 {UiSelector} 返回选择器自身以便链式调用
**为当前选择器附加控件"desc等于字符串str"的筛选条件**。
控件的desc(描述，全称为Content-Description)属性是对一个控件的描述，例如网易云音乐右上角的放大镜图标的描述为搜索。要查看一个控件的描述，同样地可以借助悬浮窗查看。
desc属性同样是定位控件的利器。
## UiSelector.descContains(str)
- str {string} 要包含的字符串
**为当前选择器附加控件"desc需要包含字符串str"的筛选条件**。
## UiSelector.descStartsWith(prefix)
- prefix {string} 前缀
**为当前选择器附加控件"desc需要以prefix开头"的筛选条件**。
## UiSelector.descEndsWith(suffix)
- suffix {string} 后缀
**为当前选择器附加控件"desc需要以suffix结束"的筛选条件**。
## UiSelector.descMatches(reg)
- reg {string} | {Regex} 要满足的正则表达式。
**为当前选择器附加控件"desc需要满足正则表达式reg"的条件**。
有关正则表达式，可以查看[正则表达式](https://www.w3school.com.cn/js/js_regexp.asp) -W3school。
需要注意的是，如果正则表达式是字符串，则需要使用\\来表达\(也即Java正则表达式的形式)，例如descMatches("\\d+")匹配多位数字
但如果使用JavaScript语法的正则表达式则不需要，例如descMatches(/\d+/)。
但如果使用字符串的正则表达式则该字符串不能以"/"同时以"/"结束，也即不能写诸如descMatches("/\\d+/")的表达式，否则会被开头的"/"和结尾的"/"会被忽略。
## UiSelector.id(resId)
- resId {string} 控件的id，以"包名:id/"开头，例如"com.tencent.mm:id/send_btn"。也可以不指定包名，这时会以当前正在运行的应用的包名来补全id。例如id("send_btn"),在QQ界面想当于id("com.tencent.mobileqq:id/send_btn")。
**为当前选择器附加"id等于resId"的筛选条件**。
**控件的id属性通常是可以用来确定控件的唯一标识，如果一个控件有id，那么使用id来找到他是最好的方法**。要查看屏幕上的控件的id，可以开启悬浮窗并使用界面工具，点击相应控件即可查看。若查看到的控件id为null, 表示该控件没有id。另外，在列表中会出现多个控件的id相同的情况。例如微信的联系人列表，每个头像的id都是一样的。此时不能用id来唯一确定控件。
在QQ界面经常会出现多个id为"name"的控件，在微信上则每个版本的id都会变化。对于这些软件而言比较难用id定位控件。
>s Tips:如果一个id属性没有实际意义,那么它通常是会随版本变化的,如:抖音点赞按钮id为"aem"(抖音版本:9.2.0); 如果id有具体意义则一般不会发生变化,如:id为action_search,title等。-白丁
## UiSelector.idContains(str)
- str {string} id要包含的字符串
**为当前选择器附加控件"id包含字符串str"的筛选条件**。比较少用。
## UiSelector.idStartsWith(prefix)
- prefix {string} id前缀
**为当前选择器附加"id需要以prefix开头"的筛选条件**。比较少用。
## UiSelector.idEndsWith(suffix)
- suffix {string} id后缀
**为当前选择器附加"id需要以suffix结束"的筛选条件**。比较少用。
## UiSelector.idMatches(reg)
- reg {Regex} | {string} id要满足的正则表达式
**附加id需要满足正则表达式**。
## UiSelector.className(str)
- str {string} 控件文本
- 返回 {UiSelector} 返回选择器自身以便链式调用
**为当前选择器附加控件"className等于字符串str"的筛选条件**。
控件的className(类名)表示一个控件的类别，例如文本控件的类名为android.widget.TextView。
如果一个控件的类名以"android.widget."开头，则可以省略这部分，例如文本控件可以直接用className("TextView")的选择器。
常见控件的类名如下：
- android.widget.TextView 文本控件
- android.widget.ImageView 图片控件
- android.widget.Button 按钮控件
- android.widget.EditText 输入框控件
- android.widget.AbsListView 列表控件
- android.widget.LinearLayout 线性布局
- android.widget.FrameLayout 帧布局
- android.widget.RelativeLayout 相对布局
- android.widget.RelativeLayout 相对布局
- android.support.v7.widget.RecyclerView 通常也是列表控件
## UiSelector.classNameContains(str)
- str {string} 要包含的字符串
**为当前选择器附加控件"className需要包含字符串str"的筛选条件**。
## UiSelector.classNameStartsWith(prefix)
- prefix {string} 前缀
**为当前选择器附加控件"className需要以prefix开头"的筛选条件**。
## UiSelector.classNameEndsWith(suffix)
- suffix {string} 后缀
**为当前选择器附加控件"className需要以suffix结束"的筛选条件**。
## UiSelector.classNameMatches(reg)
- reg {string} | {Regex} 要满足的正则表达式。
**为当前选择器附加控件"className需要满足正则表达式reg"的条件**。
## UiSelector.packageName(str)
- str {string} 控件文本
- 返回 {UiSelector} 返回选择器自身以便链式调用
**为当前选择器附加控件"packageName等于字符串str"的筛选条件**。
控件的packageName表示控件所属界面的应用包名。例如微信的包名为"com.tencent.mm", 那么微信界面的控件的packageName为"com.tencent.mm"。
要查看一个应用的包名，可以用函数app.getPackageName()获取，例如toast(app.getPackageName("微信"))。
## UiSelector.packageNameContains(str)
- str {string} 要包含的字符串
**为当前选择器附加控件"packageName需要包含字符串str"的筛选条件**。
## UiSelector.packageNameStartsWith(prefix)
- prefix {string} 前缀
**为当前选择器附加控件"packageName需要以prefix开头"的筛选条件**。
## UiSelector.packageNameEndsWith(suffix)
- suffix {string} 后缀
**为当前选择器附加控件"packageName需要以suffix结束"的筛选条件**。
## UiSelector.packageNameMatches(reg)
- reg {string} | {Regex} 要满足的正则表达式。
**为当前选择器附加控件"packageName需要满足正则表达式reg"的条件**。
## UiSelector.bounds(left, top, right, buttom)
- left {number} 控件左边缘与屏幕左边的距离
- top {number} 控件上边缘与屏幕上边的距离
- right {number} 控件右边缘与屏幕左边的距离
- bottom {number} 控件下边缘与屏幕上边的距离
**一个控件的bounds属性为这个控件在屏幕上显示的范围**。我们可以用这个范围来定位这个控件。尽管用这个方法定位控件对于静态页面十分准确，却无法兼容不同分辨率的设备；同时对于列表页面等动态页面无法达到效果，因此使用不推荐该选择器。
注意参数的这四个数字不能随意填写，**必须精确的填写控件的四个边界才能找到该控件**。例如，要点击QQ主界面的右上角加号，我们用布局分析查看该控件的属性，如下图：
可以看到bounds属性为(951, 67, 1080, 196)，此时使用代码bounds(951, 67, 1080, 196).clickable().click()即可点击该控件。
**Tips:不建议使用。-白丁**
## UiSelector.boundsInside(left, top, right, buttom)
- left {number} 范围左边缘与屏幕左边的距离
- top {number} 范围上边缘与屏幕上边的距离
- right {number} 范围右边缘与屏幕左边的距离
- bottom {number} 范围下边缘与屏幕上边的距离
**为当前选择器附加控件"bounds需要在left, top, right, buttom构成的范围里面"的条件**。
这个条件用于限制选择器在某一个区域选择控件。例如要在屏幕上半部分寻找文本控件TextView，代码为:
```JavaScript
var w = className("TextView").boundsInside(0, 0, device.width, device.height / 2).findOne();
log(w.text());
```
其中我们使用了device.width来获取屏幕宽度，device.height来获取屏幕高度。
## UiSelector.boundsContains(left, top, right, buttom)
- left {number} 范围左边缘与屏幕左边的距离
- top {number} 范围上边缘与屏幕上边的距离
- right {number} 范围右边缘与屏幕左边的距离
- bottom {number} 范围下边缘与屏幕上边的距离
**为当前选择器附加控件"bounds需要包含left, top, right, buttom构成的范围"的条件**。
这个条件用于限制控件的范围必须包含所给定的范围。例如给定一个点(500, 300), 寻找在这个点上的可点击控件的代码为:
```JavaScript
var w = boundsContains(500, 300, device.width - 500, device.height - 300).clickable().findOne();
w.click();
```
## UiSelector.drawingOrder(order)
- order {number} 控件在父视图中的绘制顺序
**为当前选择器附加控件"drawingOrder等于order"的条件**。
drawingOrder为一个控件在父控件中的绘制顺序，通常可以用于区分同一层次的控件。
但该属性在Android 7.0以上才能使用。
## UiSelector.clickable([b = true])
- b {Boolean} 表示控件是否可点击
**为当前选择器附加控件是否可点击的条件**。但并非所有clickable为false的控件都真的不能点击，这取决于控件的实现。对于自定义控件(例如显示类名为android.view.View的控件)很多的clickable属性都为false都却能点击。
需要注意的是，可以省略参数b而表示选择那些可以点击的控件，例如className("ImageView").clickable()表示可以点击的图片控件的条件，className("ImageView").clickable(false)表示不可点击的图片控件的条件。
## UiSelector.longClickable([b = true])
- b {Boolean} 表示控件是否可长按
**为当前选择器附加控件是否可长按的条件**。
## UiSelector.checkable([b = true])
- b {Boolean} 表示控件是否可勾选
**为当前选择器附加控件是否可勾选的条件**。勾选通常是对于勾选框而言的，例如图片多选时左上角通常有一个勾选框。
## UiSelector.selected([b = true])
- b {Boolean} 表示控件是否被选
**为当前选择器附加控件是否已选中的条件**。被选中指的是，例如QQ聊天界面点击下方的"表情按钮"时，会出现自己收藏的表情，这时"表情按钮"便处于选中状态，其selected属性为true。
## UiSelector.enabled([b = true])
- b {Boolean} 表示控件是否已启用
**为当前选择器附加控件是否已启用的条件**。大多数控件都是启用的状态(enabled为true)，处于“禁用”状态通常是灰色并且不可点击。
## UiSelector.scrollable([b = true])
- b {Boolean} 表示控件是否可滑动
**为当前选择器附加控件是否可滑动的条件**。滑动包括上下滑动和左右滑动。
可以用这个条件来寻找可滑动控件来滑动界面。例如滑动Auto.js的脚本列表的代码为:
```JavaScript
className("android.support.v7.widget.RecyclerView").scrollable().findOne().scrollForward();
//或者classNameEndsWith("RecyclerView").scrollable().findOne().scrollForward();
```
## UiSelector.editable([b = true])
- b {Boolean} 表示控件是否可编辑
**为当前选择器附加控件是否可编辑的条件**。一般来说可编辑的控件为输入框(EditText)，但不是所有的输入框(EditText)都可编辑。
## UiSelector.multiLine([b = true])
- b {Boolean} 表示文本或输入框控件是否是多行显示的
**为当前选择器附加控件是否文本或输入框控件是否是多行显示的条件**。
##
**选择器的筛选条件构建完成,接下来就是控件的查找啦!。**