تراشه های هوشمند

این راهنما نحوه و دلیل استفاده از API گوگل شیت برای افزودن و مدیریت تراشه‌های هوشمند در صفحات گسترده شما را شرح می‌دهد.

تراشه هوشمند چیست؟

با تراشه‌های هوشمند، می‌توانید داده‌های غنی و تعاملی را از سایر برنامه‌های Google Workspace مستقیماً به Sheets بیاورید. تراشه‌های هوشمند به کاربران امکان دسترسی سریع به اطلاعات و اقدامات را می‌دهند و یک پیوند سلولی را به یک شیء پویا تبدیل می‌کنند. برای کسب اطلاعات بیشتر، به درج تراشه‌های هوشمند در Google Sheets خود مراجعه کنید.

اضافه کردن تراشه هوشمند

تراشه‌ها به صورت تراشه‌های اجرا شده نمایش داده می‌شوند که بخشی از CellData هستند، بنابراین می‌توانید با استفاده از متد spreadsheets.batchUpdate موجود و با ارائه UpdateCellsRequest یا AppendCellsRequest ، یک تراشه را وارد کنید.

درخواست باید شامل فیلد chipRuns باشد. chip run ویژگی‌های یک تراشه و محل قرارگیری آن در متن سلول را شرح می‌دهد.

هنگام نوشتن chipRuns ، باید یک userEnteredValue نیز ارائه دهید که شامل کاراکترهای placeholder ( @ ) برای هر چیپی است که قصد اضافه کردن آن را دارید. هر اجرا در آرایه chipRuns با یکی از placeholderها مطابقت خواهد داشت. اجراهای بدون چیپ را می‌توان هنگام نوشتن حذف کرد.

مثال زیر نحوه نوشتن یک فایل چیپ، یک فایل چیپ افراد و یک متن ساده را در یک سلول واحد، A1، نشان می‌دهد. * {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

پیکربندی ویژگی‌های تراشه

یک شیء چیپ می‌تواند یکی از انواع ویژگی‌های زیر را داشته باشد:

ویژگی‌های شخص

از این برای ایجاد یک چیپ شخصی استفاده کنید.

  • email : (الزامی) آدرس ایمیل شخصی که می‌خواهید لینک دهید.
  • displayFormat : (اختیاری) قالب نمایش ترجیحی برای نام شخص. می‌تواند یکی از موارد زیر باشد:
    • DEFAULT : قالب استاندارد "نام کوچک نام خانوادگی".
    • LAST_NAME_COMMA_FIRST_NAME : قالب "نام خانوادگی، نام".
    • EMAIL : آدرس ایمیل شخص.

از این برای ایجاد یک تراشه پیوند غنی استفاده کنید. در حالی که API می‌تواند لینک‌های مربوط به سرویس‌های مختلف گوگل (مانند یوتیوب یا تقویم) را بخواند، فقط لینک‌های مربوط به فایل‌های گوگل درایو را می‌توان به صورت تراشه نوشت.

  • uri : (الزامی) آدرس اینترنتی منبع. برای نوشتن، این باید یک لینک فایل گوگل درایو باشد. آدرس‌های اینترنتی نمی‌توانند بیش از ۲۰۰۰ بایت باشند.

یک تراشه هوشمند را بخوانید.

برای خواندن داده‌های یک تراشه هوشمند، از متد spreadsheets.get استفاده کنید و sheets.data.rowData.values(chipRuns) را در پارامتر fields قرار دهید.

آرایه chipRuns در پاسخ، شامل اشیاء مربوط به تمام زیربخش‌های متن سلول خواهد بود.

  • اجراهای چیپ‌شده: این بخش‌ها یک شیء chip پر شده خواهند داشت که حاوی personProperties یا richLinkProperties است.
  • اجراهای بدون تراشه: بخش‌های متنی ساده نیز یک شیء اجرا خواهند داشت، اما فیلد chip آن خالی خواهد بود.

برای دریافت متن نمایشی یک چیپ، formattedValue به عنوان یک فیلد اضافه کنید.

به‌روزرسانی تراشه هوشمند

برای به‌روزرسانی یا جایگزینی یک تراشه هوشمند، باید محتوای سلول را بازنویسی کنید. از همان UpdateCellsRequest یا AppendCellsRequest که برای اضافه کردن یک تراشه استفاده می‌کردید، استفاده کنید و یک userEnteredValue و chipRun جدید ارائه دهید. این کار تراشه موجود در سلول را جایگزین می‌کند.

استفاده از تراشه‌های هوشمند با سایر ویژگی‌های Sheets

جداول : تراشه‌های هوشمند می‌توانند به عنوان یک نوع ستون جدول برای ردیابی صاحبان پروژه (تراشه افراد) یا اسناد مرتبط (تراشه فایل) استفاده شوند.

فیلترها : می‌توانید محدوده‌ها را بر اساس مقدار متن تراشه‌های هوشمند درون آنها فیلتر کنید.