עבודה עם טווחים בעלי שם

Google Docs API מאפשר להשתמש בטווחים בעלי שם כדי לפשט חלק ממשימות העריכה.

כשיוצרים טווח תאים בעל שם, צריך לזהות קטע במסמך שתוכלו להפנות אליו מאוחר יותר. האינדקסים של הטווח בעל השם מתעדכנים באופן אוטומטי כשמוסיפים תוכן למסמך ומסירים אותו. כך קל יותר לאתר טקסט לעדכון בעתיד, כי לא צריך לעקוב אחרי השינויים בעריכה או לחפש במסמך. במקום זאת, תוכלו לקבל מיקום לעריכה על ידי קריאת הטווח בעל השם ושימוש באינדקסים שלו.

לדוגמה, נניח שיצרתם טווח תאים בעל שם שבו המחרוזת "product description" חייבת להופיע במסמך:

כך אפשר להחליף את התיאור: פשוט מקבלים את אינדקסי ההתחלה והסיום של הטווח בעל השם, ולאחר מכן מעדכנים את הטקסט שבין האינדקסים האלה בתוכן החדש.

בקוד לדוגמה הבא אפשר לראות איך מטמיעים פונקציית עזר כדי להחליף את התוכן של טווח תאים בעל שם, במקרים שבהם הטווח בעל השם נוצר בעבר באמצעות CreateNamedRangeRequest.

Java

  /** Replaces the text in existing named ranges. */
  static void replaceNamedRange(Docs service, String documentId, String rangeName, String newText)
      throws IOException {
    // Fetch the document to determine the current indexes of the named ranges.
    Document document = service.documents().get(documentId).execute();

    // Find the matching named ranges.
    NamedRanges namedRangeList = document.getNamedRanges().get(rangeName);
    if (namedRangeList == null) {
      throw new IllegalArgumentException("The named range is no longer present in the document.");
    }

    // Determine all the ranges of text to be removed, and at which indexes the replacement text
    // should be inserted.
    List<Range> allRanges = new ArrayList<>();
    Set<Integer> insertIndexes = new HashSet<>();
    for (NamedRange namedRange : namedRangeList.getNamedRanges()) {
      allRanges.addAll(namedRange.getRanges());
      insertIndexes.add(namedRange.getRanges().get(0).getStartIndex());
    }

    // Sort the list of ranges by startIndex, in descending order.
    allRanges.sort(Comparator.comparing(Range::getStartIndex).reversed());

    // Create a sequence of requests for each range.
    List<Request> requests = new ArrayList<>();
    for (Range range : allRanges) {
      // Delete all the content in the existing range.
      requests.add(
          new Request().setDeleteContentRange(new DeleteContentRangeRequest().setRange(range)));

      if (insertIndexes.contains(range.getStartIndex())) {
        // Insert the replacement text.
        requests.add(
            new Request()
                .setInsertText(
                    new InsertTextRequest()
                        .setLocation(
                            new Location()
                                .setSegmentId(range.getSegmentId())
                                .setIndex(range.getStartIndex()))
                        .setText(newText)));

        // Re-create the named range on the new text.
        requests.add(
            new Request()
                .setCreateNamedRange(
                    new CreateNamedRangeRequest()
                        .setName(rangeName)
                        .setRange(
                            new Range()
                                .setSegmentId(range.getSegmentId())
                                .setStartIndex(range.getStartIndex())
                                .setEndIndex(range.getStartIndex() + newText.length()))));
      }
    }

    // Make a batchUpdate request to apply the changes, ensuring the document hasn't changed since
    // we fetched it.
    BatchUpdateDocumentRequest batchUpdateRequest =
        new BatchUpdateDocumentRequest()
            .setRequests(requests)
            .setWriteControl(new WriteControl().setRequiredRevisionId(document.getRevisionId()));
    service.documents().batchUpdate(documentId, batchUpdateRequest).execute();
  }

Python

def replace_named_range(service, document_id, range_name, new_text):
    """Replaces the text in existing named ranges."""

    # Determine the length of the replacement text, as UTF-16 code units.
    # https://developers.google.com/docs/api/concepts/structure#start_and_end_index
    new_text_len = len(new_text.encode('utf-16-le')) / 2

    # Fetch the document to determine the current indexes of the named ranges.
    document = service.documents().get(documentId=document_id).execute()

    # Find the matching named ranges.
    named_range_list = document.get('namedRanges', {}).get(range_name)
    if not named_range_list:
        raise Exception('The named range is no longer present in the document.')

    # Determine all the ranges of text to be removed, and at which indices the
    # replacement text should be inserted.
    all_ranges = []
    insert_at = {}
    for named_range in named_range_list.get('namedRanges'):
        ranges = named_range.get('ranges')
        all_ranges.extend(ranges)
        # Most named ranges only contain one range of text, but it's possible
        # for it to be split into multiple ranges by user edits in the document.
        # The replacement text should only be inserted at the start of the first
        # range.
        insert_at[ranges[0].get('startIndex')] = True

    # Sort the list of ranges by startIndex, in descending order.
    all_ranges.sort(key=lambda r: r.get('startIndex'), reverse=True)

    # Create a sequence of requests for each range.
    requests = []
    for r in all_ranges:
        # Delete all the content in the existing range.
        requests.append({
            'deleteContentRange': {
                'range': r
            }
        })

        segment_id = r.get('segmentId')
        start = r.get('startIndex')
        if insert_at[start]:
            # Insert the replacement text.
            requests.append({
                'insertText': {
                    'location': {
                        'segmentId': segment_id,
                        'index': start
                    },
                    'text': new_text
                }
            })
            # Re-create the named range on the new text.
            requests.append({
                'createNamedRange': {
                    'name': range_name,
                    'range': {
                        'segmentId': segment_id,
                        'startIndex': start,
                        'endIndex': start + new_text_len
                    }
                }
            })

    # Make a batchUpdate request to apply the changes, ensuring the document
    # hasn't changed since we fetched it.
    body = {
        'requests': requests,
        'writeControl': {
            'requiredRevisionId': document.get('revisionId')
        }
    }
    service.documents().batchUpdate(documentId=document_id, body=body).execute()

טווחים בעלי שם אינם פרטיים. כל מי שמשתמש ב-Docs API כדי לגשת למסמך יכול לראות את הגדרת הטווח בעל השם.

חשוב לזכור שטווחים בעלי שם מציינים טווח של תוכן מסמך, אבל הם לא חלק מהתוכן הזה. אם מחלצים תוכן שכולל טווח תאים בעל שם, ולאחר מכן מוסיפים אותו במיקום אחר, הטווח בעל השם יפנה רק לתוכן המקורי, ולא לקטע הכפול.