Skip to content

Commit 7b05e5e

Browse files
author
yunshi
committed
docs.dev: improve hyperlink.rst after code review
1 parent 90237e8 commit 7b05e5e

File tree

1 file changed

+127
-95
lines changed

1 file changed

+127
-95
lines changed

‎docs/dev/analysis/features/text/hyperlink.rst

Lines changed: 127 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -2,88 +2,87 @@
22
Hyperlink
33
=========
44

5-
Word allows hyperlinks to be placed in the document or existing objects to be
6-
turned into hyperlinks.
5+
Word allows hyperlinks to be placed in the document.
76

8-
Hyperlinks can point to a named object or range within the current document or
9-
to an external resource. Hyperlinks can contain multiple runs of text.
7+
Hyperlink may link to a external location, for example, as an url. It may link to
8+
a location within the document, for example, as an bookmark. These two cases are
9+
handled differently. Until today (03/2016), we support only external links.
1010

11+
Hyperlinks can contain multiple runs of text.
1112

1213
Candidate protocol
1314
------------------
1415

16+
The hyperlink feature supports only external links.
17+
1518
Add a simple hyperlink with text and url:
1619

17-
>>> hyperlink = paragraph.add_hyperlink(text='Google', url='http://google.com')
20+
>>> hyperlink = paragraph.add_hyperlink(text='Google', address='https://google.com')
21+
>>> hyperlink
22+
<docx.text.hyperlink.Hyperlink at 0x7f...>
1823
>>> hyperlink.text
1924
'Google'
20-
>>> hyperlink.url
21-
'http://google.com'
22-
>>> hyperlink.anchor
23-
None
24-
>>> len(hyperlink.runs)
25-
1
25+
>>> hyperlink.address
26+
'https://google.com'
27+
>>> hyperlink.runs
28+
[<docx.text.run.Run at 0x7f...>]
2629

2730
Add multiple runs to a hyperlink:
2831

29-
>>> hyperlink = paragraph.add_hyperlink(url='http://github.com')
32+
>>> hyperlink = paragraph.add_hyperlink(address='https://github.com')
3033
>>> hyperlink.add_run('A')
3134
>>> hyperlink.add_run('formatted').italic = True
3235
>>> hyperlink.add_run('link').bold = True
33-
>>> len(hyperlink.runs)
34-
3
35-
36-
Add a hyperlink pointing to a named range in the current document:
36+
>>> hyperlink.runs
37+
[<docx.text.run.Run at 0x7f...>,
38+
<docx.text.run.Run at 0x7fb...>,
39+
<docx.text.run.Run at 0x7fb...>]
3740

38-
>>> hyperlink = paragraph.add_hyperlink(text='Section 1', anchor='section1')
39-
>>> hyperlink.anchor
40-
'section1'
41-
>>> hyperlink.url
42-
None
41+
Retrieve a paragraph's content:
4342

44-
Turning an existing object into a hyperlink:
43+
>>> paragraph = document.add_paragraph('A plain paragraph having some ')
44+
>>> paragraph.add_run('link such as ')
45+
>>> paragraph.add_hyperlink(address='http://github.com', text='github')
46+
>>> paragraph.iter_p_content():
47+
[<docx.text.paragraph.Run at 0x7f...>,
48+
<docx.text.paragraph.Hyperlink at 0x7f...>]
4549

46-
>>> existing_object = document.add_paragraph('Some text')
47-
>>> hyperlink = existing_object.hyperlink(url='http://google.com')
48-
>>> hyperlink.text
49-
'Some text'
50-
>>> len(hyperlink.runs)
51-
1
5250

5351

5452
Specimen XML
5553
------------
5654

5755
.. highlight:: xml
5856

59-
A simple hyperlink to an external url::
6057

61-
<w:hyperlink r:id="rId9">
62-
<w:r>
63-
<w:rPr>
64-
<w:rStyle w:val="Hyperlink"/>
65-
</w:rPr>
66-
<w:t>Google</w:t>
67-
</w:r>
68-
</w:hyperlink>
58+
External links
59+
~~~~~~~~~~~~~~
6960

61+
A simple hyperlink to an external url::
7062

71-
The relationship for the above url::
72-
73-
<Relationships xmlns="…">
74-
<Relationship Id="rId9" Mode="External" Target=http://google.com />
75-
</Relationships>
76-
77-
A hyperlink to an internal named range::
78-
79-
<w:hyperlink r:anchor="section1">
63+
<w:p>
8064
<w:r>
81-
<w:rPr>
82-
<w:rStyle w:val="Hyperlink"/>
83-
</w:rPr>
84-
<w:t>Google</w:t>
65+
<w:t xml:space="preserve">This is an external link to </w:t>
8566
</w:r>
86-
</w:hyperlink>
67+
<w:hyperlink r:id="rId4">
68+
<w:r>
69+
<w:rPr>
70+
<w:rStyle w:val="Hyperlink"/>
71+
</w:rPr>
72+
<w:t>Google</w:t>
73+
</w:r>
74+
</w:hyperlink>
75+
</w:p>
76+
77+
78+
The r:id="rId4" references the following relationship within the relationships
79+
part for the document document.xml.rels.::
80+
81+
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
82+
<Relationship Id="rId4" Mode="External"
83+
Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
84+
Target="http://google.com/"/>
85+
</Relationships>
8786

8887
A hyperlink with multiple runs of text::
8988

@@ -99,66 +98,99 @@ A hyperlink with multiple runs of text::
9998
<w:rStyle w:val="Hyperlink"/>
10099
<w:i/>
101100
</w:rPr>
102-
<w:t xml:space="preserve">formatted</w:t>
101+
<w:t xml:space="preserve"> formatted</w:t>
103102
</w:r>
104103
<w:r>
105104
<w:rPr>
106105
<w:rStyle w:val="Hyperlink"/>
107106
<w:b/>
108107
</w:rPr>
109-
<w:t xml:space="preserve">link</w:t>
108+
<w:t xml:space="preserve"> link</w:t>
110109
</w:r>
111110
</w:hyperlink>
112111

113112

114-
Resources
115-
---------
116-
117-
* `Document Members (Word) on MSDN`_
118-
* `Hyperlink Members (Word) on MSDN`_
119-
* `Hyperlinks Members (Word) on MSDN`_
120-
* `Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN`_
121-
* `Hyperlink Class (OpenXML.Wordprocessing) on MSDN`_
122-
123-
124-
.. _Document Members (Word) on MSDN:
125-
http://msdn.microsoft.com/en-us/library/office/ff840898.aspx
126-
127-
.. _Hyperlink Members (Word) on MSDN:
128-
http://msdn.microsoft.com/en-us/library/office/ff195109.aspx
129-
130-
.. _Hyperlinks Members (Word) on MSDN:
131-
http://msdn.microsoft.com/en-us/library/office/ff192421.aspx
113+
Internal links
114+
~~~~~~~~~~~~~~
132115

133-
.. _Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN:
134-
http://msdn.microsoft.com/en-us/library/documentformat.openxml.office2010.customui.hyperlink.aspx
116+
**Note that internal links are not supported.**
135117

136-
.. _Hyperlink Class (OpenXML.Wordprocessing) on MSDN:
137-
http://msdn.microsoft.com/en-us/library/documentformat.openxml.wordprocessing.hyperlink.aspx
118+
An internal link, that link to a location in the document, is specified by the anchor attribute.
119+
The value of the anchor attribute is the name of a bookmark in the document.
138120

121+
Example::
139122

140-
MS API
141-
------
142-
143-
The Hyperlinks property on Document holds references to hyperlink
144-
objects in the MS API.
123+
<w:p>
124+
<w:r>
125+
<w:t xml:space="preserve">This is an </w:t>
126+
</w:r>
127+
<w:hyperlink w:anchor="myAnchor">
128+
<w:r>
129+
<w:rPr>
130+
<w:rStyle w:val="Hyperlink"/>
131+
</w:rPr>
132+
<w:t>internal link</w:t>
133+
</w:r>
134+
</w:hyperlink>
135+
</w:p>
136+
137+
...
138+
139+
<w:p>
140+
<w:r>
141+
<w:t xml:space="preserve">This is text with a </w:t>
142+
</w:r>
143+
<w:bookmarkStart w:id="0" w:name="myAnchor"/>
144+
<w:r>
145+
<w:t>bookmark</w:t>
146+
</w:r>
147+
<w:bookmarkEnd w:id="0"/>
148+
</w:p>
145149

146-
Hyperlinks contain the following properties:
147150

148-
* Address
149-
* SubAddress
150-
* EmailSubject
151-
* ExtraInfoRequired
152-
* Range (In python-docx this would be the runs inside the hyperlink)
153-
* ScreenTip
154-
* Shape
155-
* Target (where to open the hyperlink. e.g. "_blank", "_left", "_top", "_self", "_parent" etc)
156-
* TextToDisplay
157-
* Type (msoHyperlinkRange, msoHyperlinkShape or msoHyperlinkInlineShape)
151+
Schema excerpt
152+
--------------
158153

154+
.. highlight:: xml
159155

160-
Spec references
161-
---------------
156+
::
157+
158+
<xsd:complexType name="CT_Hyperlink">
159+
<xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
160+
<xsd:attribute name="tgtFrame" type="s:ST_String" use="optional"/>
161+
<xsd:attribute name="tooltip" type="s:ST_String" use="optional"/>
162+
<xsd:attribute name="docLocation" type="s:ST_String" use="optional"/>
163+
<xsd:attribute name="history" type="s:ST_OnOff" use="optional"/>
164+
<xsd:attribute name="anchor" type="s:ST_String" use="optional"/>
165+
<xsd:attribute ref="r:id"/>
166+
</xsd:complexType>
167+
168+
<xsd:group name="EG_PContent"> <!-- denormalized -->
169+
<xsd:choice>
170+
<xsd:element name="r" type="CT_R"/>
171+
<xsd:element name="hyperlink" type="CT_Hyperlink"/>
172+
<xsd:element name="fldSimple" type="CT_SimpleField"/>
173+
<xsd:element name="sdt" type="CT_SdtRun"/>
174+
<xsd:element name="customXml" type="CT_CustomXmlRun"/>
175+
<xsd:element name="smartTag" type="CT_SmartTagRun"/>
176+
<xsd:element name="dir" type="CT_DirContentRun"/>
177+
<xsd:element name="bdo" type="CT_BdoContentRun"/>
178+
<xsd:element name="subDoc" type="CT_Rel"/>
179+
<xsd:group ref="EG_RunLevelElts"/>
180+
</xsd:choice>
181+
</xsd:group>
182+
183+
<xsd:complexType name="CT_R">
184+
<xsd:sequence>
185+
<xsd:group ref="EG_RPr" minOccurs="0"/>
186+
<xsd:group ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
187+
</xsd:sequence>
188+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
189+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
190+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
191+
</xsd:complexType>
192+
193+
<xsd:simpleType name="ST_RelationshipId">
194+
<xsd:restriction base="xsd:string"/>
195+
</xsd:simpleType>
162196

163-
* 17.16.17 hyperlink (Hyperlink)
164-
* 2.3.61 CT_Hyperlink

0 commit comments

Comments
 (0)