<uri-relative-filter-group>

نحو:

<uri-relative-filter-group android:allow=["true" | "false"]>
  <data ... />
  ...
</uri-relative-filter-group>

مندرج در:

<intent-filter>

می‌تواند شامل موارد زیر باشد:

<data>

شرح:

نکته: عنصر <uri-relative-filter-group> و ویژگی‌های آن، از جمله تطبیق پرس‌وجو و قطعه کد و android:allow ، فقط در اندروید ۱۵ (سطح API 35) و بالاتر پشتیبانی می‌شوند. این ویژگی‌ها نادیده گرفته می‌شوند و در نسخه‌های پایین‌تر اندروید تأثیری ندارند.

قوانین تطبیق دقیق Intent ایجاد می‌کند که می‌تواند شامل پارامترهای پرس‌وجوی URI و قطعات URI باشد. این قوانین می‌توانند بسته به ویژگی android: allow ، قوانین شمول ( inclusion ) یا قوانین عدم شمول ( exclusion ) باشند. قوانین تطبیق توسط ویژگی‌های path* ، fragment* و query* عناصر <data> موجود مشخص می‌شوند.

نکته: فقط ویژگی‌های path* ، fragment* و query* برای تطبیق intent استفاده می‌شوند. سایر ویژگی‌های <data> نادیده گرفته می‌شوند.

تطبیق

برای تطبیق یک URI، هر بخش از گروه فیلتر نسبی URI باید با بخشی از URI مطابقت داشته باشد. ممکن است بخش‌هایی از URI وجود داشته باشند که در گروه فیلتر نسبی URI مشخص نشده باشند. برای مثال:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="true">
    <data android:query="param1=value1" />
    <data android:query="param2=value2" />
  </uri-relative-filter-group>
  ...
</intent-filter>

این فیلتر با https://project.example.com/any/path/here?param1=value1&param2=value2&param3=value3 مطابقت دارد زیرا هر چیزی که توسط گروه فیلتر نسبی URI مشخص شده است، وجود دارد. این فیلتر همچنین با https://project.example.com/any/path/here?param2=value2&param1=value1 مطابقت دارد زیرا ترتیب پارامترهای پرس و جو مهم نیست. با این حال، فیلتر با https://project.example.com/any/path/here?param1=value1 که param2=value2 ندارد، مطابقت ندارد.

یا و و

تگ‌های <data> خارج از <uri-relative-filter-group> با OR و تگ‌های <data> داخل <uri-relative-filter-group> با AND عمل می‌کنند.

به مثال زیر توجه کنید:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <data android:pathPrefix="/prefix" />
  <data android:pathSuffix="suffix" />
  ...
</intent-filter>

این فیلتر مسیرهایی را که با /prefix شروع می‌شوند یا با suffix تمام می‌شوند، تطبیق می‌دهد.

در مقابل، مثال بعدی مسیرهایی را که با /prefix شروع می‌شوند و با suffix پایان می‌یابند، مطابقت می‌دهد:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group>
    <data android:pathPrefix="/prefix" />
    <data android:pathSuffix="suffix" />
  </uri-relative-filter-group>
  ...
</intent-filter>

در نتیجه، چندین ویژگی path در یک <uri-relative-filter-group> با هیچ چیزی مطابقت ندارند:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group>
    <data android:path="/path1" />
    <data android:path="/path2" />
  </uri-relative-filter-group>
  ...
</intent-filter>

دستور اظهارنامه

به مثال زیر توجه کنید:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group>
    <data android:fragment="fragment" />
  </uri-relative-filter-group>
  <uri-relative-filter-group android:allow="false">
    <data android:fragmentPrefix="fragment" />
  </uri-relative-filter-group>
  ...
</intent-filter>

فیلتر با قطعه #fragment مطابقت دارد زیرا قبل از ارزیابی قانون طرد، تطابقی پیدا شده است، اما قطعاتی مانند #fragment123 مطابقت ندارند.

برچسب‌های خواهر و برادر

تگ‌های <uri-relative-filter-group> با تگ‌های <data> هم‌نیای خود (یعنی تگ‌های <data> که خارج از <uri-relative-filter-group> هستند اما درون همان <intent-filter> قرار دارند) کار می‌کنند. تگ‌های <uri-relative-filter-group> برای عملکرد صحیح باید تگ‌های <data> هم‌نیا داشته باشند، زیرا ویژگی‌های URI در سطح <intent-filter> به یکدیگر وابسته هستند:

• اگر scheme برای فیلتر intent مشخص نشده باشد، تمام ویژگی‌های دیگر URI نادیده گرفته می‌شوند.
• اگر host برای فیلتر مشخص نشده باشد، ویژگی port و تمام ویژگی‌های path* نادیده گرفته می‌شوند.

فرزندان <data> یک <intent-filter> قبل از هر تگ <uri-relative-filter-group> ارزیابی می‌شوند. سپس تگ‌های <uri-relative-filter-group> به ترتیب ارزیابی می‌شوند، برای مثال:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="false">
    <data android:path="/path" />
    <data android:query="query" />
  </uri-relative-filter-group>
  <data android:path="/path" />
  ...
</intent-filter>

این فیلتر https://project.example.com/path?query را می‌پذیرد زیرا با <data android:path="/path" /> مطابقت دارد، که خارج از قانون حذف <uri-relative-filter-group> است.

نکته: از آنجایی که ویژگی‌های path* از تگ‌های <data> قبل از تگ‌های <uri-relative-filter-group> ارزیابی می‌شوند (که به ترتیب تعریف ارزیابی می‌شوند)، بهتر است ویژگی‌های path* قبل از تگ‌های <uri-relative-filter-group> قرار گیرند.

مورد استفاده رایج

تصور کنید که آدرس اینترنتی https://project.example.com/path را دارید که می‌خواهید بسته به وجود یا مقدار یک پارامتر پرس‌وجو، آن را با یک Intent مطابقت دهید. برای ایجاد یک فیلتر intent که با https://project.example.com/path مطابقت داشته باشد و https://project.example.com/path?query را مسدود کند، می‌توانید چیزی شبیه به این را امتحان کنید:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="true">
    <data android:path="/path" />
  </uri-relative-filter-group>
  ...
</intent-filter>

در واقع، این کار نمی‌کند. آدرس اینترنتی https://project.example.com/path?query با مسیر /path مطابقت دارد و برچسب <uri-relative-filter-group> در صورت تطابق، امکان اضافه کردن بخش‌های اضافی را فراهم می‌کند.

فیلتر intent را به صورت زیر اصلاح کنید:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="false">
    <data android:path="/path" />
    <data android:queryAdvancedPattern=".+" />
  </uri-relative-filter-group>
  <uri-relative-filter-group android:allow="true">
    <data android:path="/path" />
  </uri-relative-filter-group>
  ...
</intent-filter>

این فیلتر به این دلیل کار می‌کند که ابتدا قوانین مسدودکننده‌ای که پارامترهای پرس‌وجوی غیرخالی را ممنوع می‌کنند، ارزیابی می‌شوند.

برای ساده‌سازی کد، رفتار را برعکس کنید تا پارامترهای پرس‌وجو مجاز باشند و URIهای بدون پارامترهای پرس‌وجو مسدود شوند:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="true">
    <data android:path="/path" />
    <data android:queryAdvancedPattern=".+" />
  </uri-relative-filter-group>
  ...
</intent-filter>

کاراکترهای کدگذاری شده توسط URI

برای تطبیق URIهایی که حاوی کاراکترهای کدگذاری شده با URI هستند، کاراکترهای خام و کدگذاری نشده را در فیلتر بنویسید، برای مثال:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="true">
    <data android:query="param=value!" />
  </uri-relative-filter-group>
  ...
</intent-filter>

فیلتر با ?param=value! و ?param=value%21 مطابقت دارد.

با این حال، اگر کاراکترهای رمزگذاری شده را در فیلتر به صورت زیر بنویسید:

<intent-filter...>
  <data android:scheme="https" android:host="project.example.com" />
  <uri-relative-filter-group android:allow="true">
    <data android:query="param=value%21" />
  </uri-relative-filter-group>
  ...
</intent-filter>

این فیلتر نه با ?param=value! و نه با ?param=value%21 مطابقت ندارد.

تعداد عناصر

شما می‌توانید هر تعداد عنصر <uri-relative-filter-group> را درون یک <intent-filter> قرار دهید.

منابع اضافی

برای اطلاعات در مورد نحوه کار فیلترهای intent، از جمله قوانین مربوط به نحوه تطبیق اشیاء intent با فیلترها، به Intents و Intent Filters و Intent Filters مراجعه کنید.

برای اطلاعات بیشتر در مورد <uri-relative-filter-group> ، به UriRelativeFilterGroup و UriRelativeFilter مراجعه کنید.

ویژگی‌ها:

android:allow

اینکه آیا این گروه فیلتر نسبی URI یک قانون شمول ( allow ) است یا یک قانون عدم شمول ( blocking ). مقدار پیش‌فرض "true" است.

ارزش	توضیحات
"true" (پیش‌فرض)	اگر گروه فیلتر نسبی URI مطابقت داشته باشد، فیلتر intent نیز مطابقت خواهد داشت.
"false"	اگر گروه فیلتر نسبی URI مطابقت داشته باشد، فیلتر intent مطابقت ندارد.

معرفی شده در:

سطح API 35

همچنین ببینید:

<intent-filter>
<data>